From 06417c2c76e7875f54f6bb4f7f60ceb491ce9a56 Mon Sep 17 00:00:00 2001 From: cha0s Date: Sun, 31 Dec 2023 16:23:28 -0600 Subject: [PATCH] feat: dox++ --- .gitignore | 4 - README.md | 2 +- build/docusaurus.config.js | 47 +++++++++ build/flecks.yml | 17 ++++ package.json | 20 +++- website/docs/.gitignore | 1 + website/docs/configuration.mdx | 84 ++++++++++++++++ website/docs/creating-flecks.mdx | 147 ++++++++++++++++++++++++++++ website/docs/documentation.mdx | 14 +++ website/docs/flecks-core.mdx | 20 ++++ website/docs/flecks-electron.png | Bin 0 -> 10936 bytes website/docs/installation.mdx | 6 ++ website/docs/introduction.mdx | 61 ++++++++++++ website/docs/isomorphism.mdx | 11 +++ website/helpers/install-package.jsx | 19 ++++ website/pages/index.jsx | 41 ++++++++ website/pages/index.module.css | 23 +++++ website/sidebars.js | 43 ++++++++ 18 files changed, 552 insertions(+), 8 deletions(-) create mode 100644 build/docusaurus.config.js create mode 100644 build/flecks.yml create mode 100644 website/docs/.gitignore create mode 100644 website/docs/configuration.mdx create mode 100644 website/docs/creating-flecks.mdx create mode 100644 website/docs/documentation.mdx create mode 100644 website/docs/flecks-core.mdx create mode 100644 website/docs/flecks-electron.png create mode 100644 website/docs/installation.mdx create mode 100644 website/docs/introduction.mdx create mode 100644 website/docs/isomorphism.mdx create mode 100644 website/helpers/install-package.jsx create mode 100644 website/pages/index.jsx create mode 100644 website/pages/index.module.css create mode 100644 website/sidebars.js diff --git a/.gitignore b/.gitignore index 0628a25..49a9f90 100644 --- a/.gitignore +++ b/.gitignore @@ -116,11 +116,7 @@ dist .pnp.* # local -/build /yarn.lock # package-locals /packages/*/yarn.lock - -# Generated documentation -/dox diff --git a/README.md b/README.md index 24efb57..0db1373 100644 --- a/README.md +++ b/README.md @@ -12,7 +12,7 @@ This is largely untested software. There are undoubtedly many bugs that haven't yet been found. - I reserve the right to break all semantic versioning guarantees as long as the project is v1.x.x! 😈 + I reserve the right to break all semantic versioning guarantees as long as there is a critical need for fundamental changes that significantly improve the project's architecture, performance, or address security vulnerabilities, and these modifications are deemed essential for the long-term stability, innovation, and overall betterment of the software. The project is young enough that I can get away with that. This will be revisited. **You've been warned!** diff --git a/build/docusaurus.config.js b/build/docusaurus.config.js new file mode 100644 index 0000000..0800552 --- /dev/null +++ b/build/docusaurus.config.js @@ -0,0 +1,47 @@ +// @ts-check +// `@type` JSDoc annotations allow editor autocompletion and type checking +// (when paired with `@ts-check`). +// There are various equivalent ways to declare your Docusaurus config. +// See: https://docusaurus.io/docs/api/docusaurus-config + +// For some reason we get a webpack warning if we use import here... +const {configDefaults} = require('@flecks/dox/server'); // eslint-disable-line import/no-extraneous-dependencies + +export default async function flecksDocusaurus() { + const defaults = configDefaults(); + /** @type {import('@docusaurus/types').Config} */ + const config = { + ...defaults, + title: 'flecks', + tagline: 'not static', + // favicon: 'img/flecks.svg', + url: 'https://cha0s.github.io', + baseUrl: '/flecks/', + organizationName: 'cha0s', // Usually your GitHub org/user name. + projectName: 'flecks', // Usually your repo name. + themeConfig: + /** @type {import('@docusaurus/preset-classic').ThemeConfig} */ + ({ + ...defaults.themeConfig, + navbar: { + title: 'flecks', + // logo: { + // alt: 'flecks logo', + // src: 'img/flecks.svg', + // }, + items: [ + { + href: 'https://github.com/cha0s/flecks', + label: 'GitHub', + position: 'right', + }, + ], + }, + footer: { + style: 'dark', + copyright: `Copyright © ${new Date().getFullYear()} cha0s. Built with Docusaurus.`, + }, + }), + }; + return config; +} diff --git a/build/flecks.yml b/build/flecks.yml new file mode 100644 index 0000000..955a2f6 --- /dev/null +++ b/build/flecks.yml @@ -0,0 +1,17 @@ +'@flecks/core': {} +'@flecks/create-app': {} +'@flecks/create-fleck': {} +'@flecks/db': {} +'@flecks/docker': {} +'@flecks/dox': {} +'@flecks/electron': {} +'@flecks/fleck': {} +'@flecks/governor': {} +'@flecks/react': {} +'@flecks/redis': {} +'@flecks/redux': {} +'@flecks/repl': {} +'@flecks/server': {} +'@flecks/socket': {} +'@flecks/user': {} +'@flecks/web': {} diff --git a/package.json b/package.json index 4c91edb..fd5bf8c 100644 --- a/package.json +++ b/package.json @@ -8,15 +8,29 @@ "bfp": "for i in $(npx lerna exec pwd); do cd $i; bfp || break; done; cd ../..", "build": "lerna run build", "clean": "for i in $(npx lerna exec pwd); do cd $i; rm -rf yarn.lock node_modules; yarn; done; cd ../..", - "dox": "FLECKS_ENV_FLECKS_DOX_SERVER_filenameRewriters=\"{\\\"^@flecks/(.*):([0-9]+):([0-9]+)\\\": \\\"@flecks/\\$1:\\$2:\\$3\\\"}\" yarn flecks dox", "lint": "lerna run lint", "publish": "lerna publish --conventional-commits --contents=dist --registry https://registry.npmjs.org", "refresh": "npm run clean && npm run bfp", "test": "lerna run test --no-bail -- --silent" }, - "dependencies": {}, "devDependencies": { - "@flecks/core": "*", + "@flecks/core": "^2.0.3", + "@flecks/create-app": "*", + "@flecks/create-fleck": "*", + "@flecks/db": "*", + "@flecks/docker": "*", + "@flecks/dox": "^2.0.3", + "@flecks/electron": "*", + "@flecks/fleck": "*", + "@flecks/governor": "*", + "@flecks/react": "*", + "@flecks/redis": "*", + "@flecks/redux": "*", + "@flecks/repl": "*", + "@flecks/server": "*", + "@flecks/socket": "*", + "@flecks/user": "*", + "@flecks/web": "*", "lerna": "^7.4.2" } } diff --git a/website/docs/.gitignore b/website/docs/.gitignore new file mode 100644 index 0000000..ebf8332 --- /dev/null +++ b/website/docs/.gitignore @@ -0,0 +1 @@ +/flecks \ No newline at end of file diff --git a/website/docs/configuration.mdx b/website/docs/configuration.mdx new file mode 100644 index 0000000..f2c9dcd --- /dev/null +++ b/website/docs/configuration.mdx @@ -0,0 +1,84 @@ +--- +title: Configuration +description: Configure `flecks.yml` and your application. +--- + +import InstallPackage from '@site/helpers/install-package'; + +You have a flecks application! ...but it doesn't do much. This is because a flecks application is +composed of individual flecks. By default, your application will have two flecks: `@flecks/core` and +`@flecks/server`. Each fleck may have configuration that can be set through `flecks.yml`. For a +list of configurable core flecks, see [the generated configuration page](/docs/flecks/config). + +## First steps + +A good first configuration step is to set the ID of your application. + +Your `flecks.yml` will look like this after you generate your application: + +```yml +'@flecks/core': {} +'@flecks/server': {} +``` + +Your application's ID is configured at the `id` key of `@flecks/core`'s configuration. To set your +application's ID to `hello_world`, update your `flecks.yml` to look like this: + +```yml +// highlight-start +'@flecks/core': + id: 'hello_world' +// highlight-end +'@flecks/server': {} +``` + +## Getting somewhere + +If you were studious enough to take a peek at [the generated configuration page](/docs/flecks/config) +above, you may have noticed that there were a bunch more flecks there than just the two in our +application. + +For instance, there is a `@flecks/web` fleck that turns your little old server application into one +that can build and serve a webpage. You can add it to your application in two steps. + +1. Add the package to your project using your favorite package manager: + + + +2. Add the fleck to your `flecks.yml`: + +```yml +'@flecks/core': + id: 'hello_world' +'@flecks/server': {} +// highlight-next-line +'@flecks/web': {} +``` + +Now, if you run `npm start`, you'll see a line in the output: + +``` + @flecks/web/server/http HTTP server up @ 0.0.0.0:32340! +``` + +## Finally... a white page? + +If you visit `localhost:32340` in your browser, you should now see... a blank white page! Don't fret +though; if you open the devtools in your browser, you will see a little messaging from your +application that will look something like: + +``` +[webpack-dev-server] Server started: Hot Module Replacement enabled, Live Reloading enabled, Progress disabled, Overlay enabled. +[HMR] Waiting for update signal from WDS... +flecks client v2.0.3 loading runtime... +``` + +This is a good sign! This means we successfully added a web server with HMR enabled by default. +Oh, the possibilities... + +## Proceed with the hooking + +How does flecks know to start the web server when the application starts? Great question! This is +accomplished through the use of [hooks](#todo). + +Next, we'll learn how to create our own fleck and do a little hooking of our own. Take that, dad! diff --git a/website/docs/creating-flecks.mdx b/website/docs/creating-flecks.mdx new file mode 100644 index 0000000..cf05505 --- /dev/null +++ b/website/docs/creating-flecks.mdx @@ -0,0 +1,147 @@ +--- +title: Creating a fleck +description: A fleck is a module but also so much more. +--- + +import InstallPackage from '@site/helpers/install-package'; + +So you want to create a fleck. Think you got what it takes? + +If you are following along from the previous getting started +[configuration page](./configuration), you have an application with 3 flecks: + +- `@flecks/core` +- `@flecks/server` +- `@flecks/web` + +
+ About that "3 flecks" thing... + + Actually, your application has 6 flecks at this point: + + - `@flecks/core` + - `@flecks/core/server` + - `@flecks/server` + - `@flecks/server/server` + - `@flecks/web` + - `@flecks/web/server` + + flecks will load the `[...]/server` fleck under any fleck that is loaded on the server. This is + also the case when using `@flecks/web` which will automatically load `[...]/client` flecks + which are only loaded in the browser. We'll be exploring this specifically in the next section. + If you're intersted in diving deeper, see [the platforms concept page](#todo). + + Some frameworks make it a little cheesier to work with isomorphic code, but the flecks + philosophy is that visibility is believability: you'll have to be explicit about which code + runs where. +
+ +## Your first fleck + +Let's make your website greet the user with a good ol' **hello world**. + +To do this, you'll be creating your own little fleck. You'll create the fleck at `src/hello-world`. +A fleck is just a package, so we'll need to add a `package.json`. Nothing much; a name will suffice: + +### `package.json` + +```json +{ + "name": "hello-world", +} +``` + +and we'll add our little source file: + +### `index.js` + +```javascript +exports.hooks = { + '@flecks/web/client.up': async () => { + window.document.body.append('hello world'); + }, +}; +``` + +You should now have a `src` directory that looks like this: + +``` +src +└── hello-world + β”œβ”€β”€ index.js + └── package.json +``` + +Good? Good! Now, let's add this to our `flecks.yml`: + +```yml +'@flecks/core': + id: 'hello_world' +'@flecks/server': {} +'@flecks/web': {} +// highlight-next-line +'hello-world:./src/hello-world': {} +``` + +### Aliasing for the win + +Notice there's a colon separating the path for this one. This is because this is an +[aliased fleck](#todo). The part before the colon is the alias and the part after is the +path to the package. + +Now, restart your application and visit your website. Glorious, isn't it? + +By the way, your other application code can import the alias (e.g. `require('hello-world');`) +[as if it were a package](https://webpack.js.org/configuration/resolve/#resolvealias). + +
+ Wait, my flecks don't have to be in node_modules? + + Nope! That's an intentional feature. When you're developing applications, it can be real nice to + just pull in local source "packages". If you're wondering how this works, see + [the alias concept page](#todo). + + You probably shouldn't do things like name an alias the same thing as a package that actually + exists in your `node_modules` directory. If you'd like to help define what happens in that case + you could always [submit a pull request](https://github.com/cha0s/flecks/compare). + + That being said, sharing your package on npm is a cool thing to do, so be rad and share your + awesome flecks with the rest of us! +
+ +## Everything so far... plus Electron! + +Let's add another core fleck. flecks ships with a core fleck `@flecks/electron`. This runs your +application inside of an instance of [Electron](https://www.electronjs.org/). You'll add the fleck: + + + +Then you'll update your `flecks.yml` like so: + +```yml +'@flecks/core': + id: 'hello_world' +// highlight-start +'@flecks/electron': {} +'@flecks/server': + up: + - '...' + - '@flecks/web' + - '@flecks/electron' +// highlight-end +'@flecks/web': {} +'hello-world:./src/hello-world': {} +``` + +### ~~flecking~~ pecking order + +Did you notice we added some configuration to `@flecks/server`? The `up` key configures the order in +which flecks are initialized when the server comes up. We make sure `@flecks/web` initializes +before `@flecks/electron` so there's a webpage to visit. There are future plans to make this the +default with no configuration required. + +Finally `npm start` and you should see something like this: + +![An image of our simple hello world application running inside an Electron window](./flecks-electron.png) + +Cool, huh? diff --git a/website/docs/documentation.mdx b/website/docs/documentation.mdx new file mode 100644 index 0000000..87b2273 --- /dev/null +++ b/website/docs/documentation.mdx @@ -0,0 +1,14 @@ +--- +title: Documentation +description: Document your project. +--- + +# Documentation + +Ah, the most ~~boring~~ awesome part of development. + +flecks provides a fleck called `@flecks/dox` that helps you generate a documentation website for +your project. In fact, this very website you're viewing now has been built with the same tooling! + +`@flecks/dox` implements a [CLI command](/flecks/docs/flecks/@flecks/dox/hooks#fleckscorecommands) +to run [Docusaurus](https://docusaurus.io/) and generate a documentation site for your project. diff --git a/website/docs/flecks-core.mdx b/website/docs/flecks-core.mdx new file mode 100644 index 0000000..7f286e6 --- /dev/null +++ b/website/docs/flecks-core.mdx @@ -0,0 +1,20 @@ +--- +description: flecks core handles the orchestration of your flecks +slug: /flecks-core +--- + +# `@flecks/core` + +## CLI + +## Debug logs + +## Helpers + +### Event emitter + +### Middleware + +### Compose + +## `@flecks/core/server` \ No newline at end of file diff --git a/website/docs/flecks-electron.png b/website/docs/flecks-electron.png new file mode 100644 index 0000000000000000000000000000000000000000..95c9ab4fb254a04089448b577fa0c2b1e2d54cc4 GIT binary patch literal 10936 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 literal 0 HcmV?d00001 diff --git a/website/docs/installation.mdx b/website/docs/installation.mdx new file mode 100644 index 0000000..34d8867 --- /dev/null +++ b/website/docs/installation.mdx @@ -0,0 +1,6 @@ +--- +title: Installation +description: How to get started with your first flecks project +--- + +This is some text. diff --git a/website/docs/introduction.mdx b/website/docs/introduction.mdx new file mode 100644 index 0000000..ece771f --- /dev/null +++ b/website/docs/introduction.mdx @@ -0,0 +1,61 @@ +--- +description: flecks makes a joy of JavaScript app development. +slug: / +--- + +# Introduction + +⚑️ flecks will help you build a **flexible and powerful application in no time**. + +πŸ’Έ Save time and money and don't duplicate effort. Instead, **lean on infrastructure that already exists** to solve your problems. + +πŸ’₯ Ready for more? Use **advanced features** like [running flecks on your toaster](#todo) + +🧐 Flecks is an **exceptionally-extensible fullstack application production system**. Its true purpose +is to make application development a more joyful endeavor. Intelligent defaults combined with +a highly dynamic structure motivate consistency while allowing you to easily express your own +opinions. + +## Features {#features} + +flecks is built with supreme attention to the developer and end-user experience. + +- 🧩 **Small but pluggable** + - The simplest application is two flecks, `core` and `server`: you don't pay for what you don't buy + - Endlessly configurable through built-in hooks and then your own +- πŸ› οΈ **Ready to build real applications** + - babel + Webpack 5 + - [React](#todo)/[redux](#todo) + - [Database](#todo) + - [electron](#todo) + - [docker](#todo) + - [REPL](#todo) + - [websockets](#todo) with lots of goodies like binary packing and packet dispatching out of the box + - [docusaurus](#todo): This documentation website you're looking at, available to your own apps for your own documentation by simply adding [`@flecks/dox`](#todo) to your own application +- πŸ‘· **Developers, developers, developers** + - πŸͺ„ Easy to create a fleck; no need to publish packages or use voodoo + - Write server or client (or both) tests, run on server/in browser/[your own custom platform](#todo) + - HMR (even on the server) + - Create a fleck with your [redux slice](https://redux-toolkit.js.org/api/createslice/) provided through a hook. Finally, real [ducks](https://github.com/erikras/ducks-modular-redux)! + - Easily spin up a database or redis server ([or...](/docs/flecks/hooks#flecksdockercontainers)) using [Docker](#todo) during development, and generate a `Dockerfile` and `docker-compose.yml` automatically for production + - Small hookable core means less exposed wires. You could always help by [submitting a pull request](https://github.com/cha0s/flecks/compare) though. + +Our shared goalβ€”to help you quickly develop your application. We share our best practices to help you build your application right and well. + +## Design principles {#design-principles} + +- **Little to learn**. flecks should be easy to learn and use as the API is quite small. Most things will still be achievable by users, even if it takes them more code and more time to write. Not having abstractions is better than having the wrong abstractions, and we don't want users to have to hack around the wrong abstractions. Mandatory talkβ€”[Minimal API Surface Area](https://www.youtube.com/watch?v=4anAwXYqLG8). +- **Intuitive**. Users will not feel overwhelmed when looking at the project directory of a flecks project or adding new features. It should look intuitive and easy to build on top of, using approaches they are familiar with. +- **Modular**. flecks is built from the ground up with separation of concerns as a first-class concern. +- **Sensible defaults**. Common and popular performance optimizations and configurations will be done for users but they are given the option to override them. +- **No vendor lock-in**. Users are not required to use the default flecks, although they are highly encouraged to. + +We believe that, as developers, knowing how a library works helps us become better at using it. Hence we're dedicating effort to explaining the architecture and various aspects of flecks with the hope that users reading it will gain a deeper understanding and be even more proficient in using it. + +## Staying informed {#staying-informed} + +- [GitHub](https://github.com/cha0s/flecks) + +## Something missing? {#something-missing} + +If you find issues with the documentation or have suggestions on how to improve the documentation or the project in general, please [file an issue](https://github.com/cha0s/flecks/issues/new) for us. diff --git a/website/docs/isomorphism.mdx b/website/docs/isomorphism.mdx new file mode 100644 index 0000000..9407a74 --- /dev/null +++ b/website/docs/isomorphism.mdx @@ -0,0 +1,11 @@ +--- +description: It might matter where your code is running. +--- + +# Isomorphism + +All this code we're writing could be running on your Node.js server, it could be running in the +browser, or both. + +flecks solves this problem with [platforms](#todo) and the intelligent inclusion of only the code +relevant to the platform where the code is running. diff --git a/website/helpers/install-package.jsx b/website/helpers/install-package.jsx new file mode 100644 index 0000000..5c4ad73 --- /dev/null +++ b/website/helpers/install-package.jsx @@ -0,0 +1,19 @@ +import CodeBlock from '@theme/CodeBlock'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + +export default function PackageInstall({pkg}) { + return ( + + + npm install {pkg} + + + yarn add {pkg} + + + bun install {pkg} + + + ); +} diff --git a/website/pages/index.jsx b/website/pages/index.jsx new file mode 100644 index 0000000..4c693d7 --- /dev/null +++ b/website/pages/index.jsx @@ -0,0 +1,41 @@ +import clsx from 'clsx'; +import Link from '@docusaurus/Link'; +import useDocusaurusContext from '@docusaurus/useDocusaurusContext'; +import Layout from '@theme/Layout'; + +import Heading from '@theme/Heading'; +import styles from './index.module.css'; + +function HomepageHeader() { + const {siteConfig} = useDocusaurusContext(); + return ( +
+
+ + {siteConfig.title} + +

{siteConfig.tagline}

+
+ + Your documentation here + +
+
+
+ ); +} + +export default function Home() { + const {siteConfig} = useDocusaurusContext(); + return ( + + + + ); +} diff --git a/website/pages/index.module.css b/website/pages/index.module.css new file mode 100644 index 0000000..9f71a5d --- /dev/null +++ b/website/pages/index.module.css @@ -0,0 +1,23 @@ +/** + * CSS files with the .module.css suffix will be treated as CSS modules + * and scoped locally. + */ + +.heroBanner { + padding: 4rem 0; + text-align: center; + position: relative; + overflow: hidden; +} + +@media screen and (max-width: 996px) { + .heroBanner { + padding: 2rem; + } +} + +.buttons { + display: flex; + align-items: center; + justify-content: center; +} diff --git a/website/sidebars.js b/website/sidebars.js new file mode 100644 index 0000000..44b0729 --- /dev/null +++ b/website/sidebars.js @@ -0,0 +1,43 @@ +export default { + flecksSidebar: [ + 'introduction', + { + type: 'category', + label: 'Getting Started', + link: { + type: 'generated-index', + }, + collapsed: false, + items: [ + 'installation', + 'configuration', + 'creating-flecks', + ], + }, + { + type: 'category', + label: 'Guides', + link: { + type: 'generated-index', + }, + collapsed: false, + items: [ + 'documentation', + 'isomorphism', + ], + }, + { + type: 'category', + label: 'Generated details', + link: { + type: 'generated-index', + }, + items: [ + 'flecks/@flecks/dox/hooks', + 'flecks/@flecks/dox/config', + 'flecks/@flecks/dox/build-configs', + 'flecks/@flecks/dox/TODO', + ], + }, + ], +};