diff --git a/website/docs/adding-flecks.mdx b/website/docs/adding-flecks.mdx new file mode 100644 index 0000000..7164d8d --- /dev/null +++ b/website/docs/adding-flecks.mdx @@ -0,0 +1,41 @@ +--- +title: Adding flecks +description: Add flecks to your application to extend its functionality. +--- + +# Adding flecks + +`@flecks/web` is a fleck that builds and serves a webpage. You can add it to your application +using flecks: + +```bash +npx flecks add @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. You'll see how to configure that hook in the next section. + +For now, 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/configuration.mdx b/website/docs/configuration.mdx index dac0b7d..a251d33 100644 --- a/website/docs/configuration.mdx +++ b/website/docs/configuration.mdx @@ -3,15 +3,13 @@ title: Configuration description: Configure `build/flecks.yml` and your application. --- -import InstallPackage from '@site/helpers/install-package'; - # Configuration You have a flecks application! ...but it doesn't do much. This is because a flecks application is composed of individual flecks and by default, your application will have only two flecks: `@flecks/core` and `@flecks/server`. Your `build/flecks.yml` file will look like this: -```yml +```yml title="build/flecks.yml" '@flecks/core': {} '@flecks/server': {} ``` @@ -24,17 +22,10 @@ For a deep dive of configurable core flecks, see A good first configuration step is to set the ID of your application. -Your `build/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 `build/flecks.yml` to look like this: -```yml +```yml title="build/flecks.yml" // highlight-start '@flecks/core': id: 'hello_world' @@ -49,46 +40,4 @@ above, you may have noticed that there were a lot more flecks there than just th 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 `build/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! +that can build and serve a webpage. We'll see how to add it in the next section. diff --git a/website/docs/creating-flecks.mdx b/website/docs/creating-a-fleck.mdx similarity index 77% rename from website/docs/creating-flecks.mdx rename to website/docs/creating-a-fleck.mdx index 5b5485f..1bca8bc 100644 --- a/website/docs/creating-flecks.mdx +++ b/website/docs/creating-a-fleck.mdx @@ -4,9 +4,6 @@ description: A fleck is a module but also so much more. --- import Create from '@site/helpers/create'; -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: @@ -18,7 +15,7 @@ If you are following along from the previous getting started
About that "3 flecks" thing... - Actually, your application has 6 flecks at this point: + Actually, your server application has 6 flecks at this point: - `@flecks/core` - `@flecks/core/server` @@ -53,24 +50,16 @@ This isn't any hard requirement, it's only a suggestion. ::: +### Create the fleck + Let's create our little fleck: -After some output, you'll find your new fleck at `packages/say-hello`. There is a source file at -`packages/say-hello/src/index.js` but for now it's empty. Let's fill it out a bit: +After some output, you'll find your new fleck at `packages/say-hello`. Let's inspect our +`build/flecks.yml`: -```javascript -exports.hooks = { - '@flecks/web/client.up': async () => { - window.document.body.append('hello world'); - }, -}; -``` - -Good? Good! Now, let's add this to our `build/flecks.yml`: - -```yml +```yml title="build/flecks.yml" '@flecks/core': id: 'hello_world' '@flecks/server': {} @@ -85,19 +74,22 @@ Notice there's a colon separating the path for this one. This is because this is [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 using the alias (e.g. `require('@hello-world/say-hello');`) [as if it were a package](https://webpack.js.org/configuration/resolve/#resolvealias).
- Wait, my flecks don't have to be in node_modules? + Wait, my modules don't have to be in node_modules? Nope! 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). + That being said, sharing your packages on npm is a cool thing to do, so be rad and share your + awesome flecks with the rest of us! + + :::warning + You probably shouldn't do things like name an alias the same thing as a package that actually exists in your `node_modules` directory. This is mitigated if you use the default monorepo structure (unless your application name is identical to a monorepo organization that already @@ -106,24 +98,40 @@ By the way, your other application code can import using the alias (e.g. If you'd like to help define what happens in these edge cases you could always [submit a pull request](https://github.com/cha0s/flecks/compare). :smile: - That being said, sharing your packages on npm is a cool thing to do, so be rad and share your - awesome flecks with the rest of us! + :::
+### Your first hook + +There is a source file at `packages/say-hello/src/index.js` but for now it's empty. Let's fill it +out a bit: + +```javascript title="packages/say-hello/src/index.js" +exports.hooks = { + '@flecks/web/client.up': async () => { + window.document.body.append('hello world'); + }, +}; +``` + +Now, restart your application and visit your website. Glorious, isn't it? + ## 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: - +```bash +npx flecks add @flecks/electron +``` Then you'll update your `build/flecks.yml` like so: ```yml '@flecks/core': id: 'hello_world' -// highlight-start '@flecks/electron': {} +// highlight-start '@flecks/server': up: - '...' @@ -136,17 +144,30 @@ Then you'll update your `build/flecks.yml` like so: ### ~~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` serves a webpage -before `@flecks/electron` tries to visit it. +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` serves a webpage before +`@flecks/electron` tries to visit it. -:::note +:::tip -There are future plans to make this the default with no configuration required. +`'...'` just means "everything else": if any other flecks implement that hook then they will run +here. It is valid to provide entries both before and after `'...'`. + +The default configuration of +`@flecks/server.up` is simply: + +```yml +'@flecks/server': + up: + - '...' +``` + +However in this case the order of hook execution is undefined. That's why we configure it +explicitly. ::: -Finally `npm start` and you should see something like this: +Finally `npm start` and you will see something like this: ![An image of our simple hello world application running inside an Electron window](./flecks-electron.png) diff --git a/website/docs/database.mdx b/website/docs/database.mdx index 4c6e304..571e6df 100644 --- a/website/docs/database.mdx +++ b/website/docs/database.mdx @@ -18,17 +18,10 @@ We'll start from scratch as an example. Create a new flecks application: -Now in your new application directory, install `@flecks/db`: +Now in your new application directory, add `@flecks/db`: - - -Then, add the fleck to your `build/flecks.yml`: - -```yml title="build/flecks.yml" -'@flecks/core': {} -// highlight-next-line -'@flecks/db': {} -'@flecks/server': {} +```bash +npx flecks add @flecks/db ``` Finally, `npm start` your application and you will see lines like the following in the logs: @@ -55,16 +48,6 @@ First, create a fleck in your application: -Then, add it to `build/flecks.yml`: - -```yml title="build/flecks.yml" -'@flecks/core': {} -'@flecks/db': {} -'@flecks/server': {} -// highlight-next-line -'@db_test/tags:./packages/tags': {} -``` - Now, let's hop into `packages/tags/src/index.js` and add a hook implementation: ```javascript title="packages/tags/src/index.js" @@ -92,11 +75,15 @@ export const hooks = { } ``` -:::note +:::tip + +`@flecks/db` uses [Sequelize](https://sequelize.org/) under the hood. You can dive into +[their documentation](https://sequelize.org/docs/v6/getting-started/) to learn even more. The static `attributes` method above is sugar on top of [`sequelize.define`](https://sequelize.org/docs/v6/core-concepts/model-basics/#using-sequelizedefine) -and you should consult that documentation for details on how to define your models. +and you should consult that documentation for more details on how to define and validate your +models. To implement associations between models, there is a static `associate` method. Suppose you also had a `Post` model along with your `Tags` model. You might do something like this in your `Tags` @@ -105,6 +92,7 @@ model: ``` static associate({Post}) { Post.hasMany(this); + this.hasMany(Post); } ``` @@ -120,9 +108,10 @@ Our model is recognized! ## Gathering models -If we stuff all of our models into that file, things are going to start getting unwieldy. Let's -create a `src/models` directory in our `packages/tags` fleck and add a `tags.js` source file with the following -code: +When building Real:tm: applications we are usually going to need a bunch of models. If we add all +of them into that one single file, things are going to start getting unwieldy. Let's create a +`src/models` directory in our `packages/tags` fleck and add a `tags.js` source file with the +following code: ```javascript title="packages/tags/src/models/tags.js" export default (flecks) => { @@ -147,7 +136,7 @@ export default (flecks) => { Notice that this looks very similar to how we defined the model above, but this time we're only returning the class. -Now, hop over to `src/index.js` and let's rewrite the hook implementation: +Now, hop over to `packages/tags/src/index.js` and let's rewrite the hook implementation: ```javascript title="packages/tags/src/index.js" export const hooks = { @@ -157,7 +146,7 @@ export const hooks = { We're passing the path to our models directory to `require.context` which is then passed to `Flecks.provide`. This is completely equivalent to our original code, but now we can add more -models and keep things tidy. +models by adding individual files in `packages/tags/src/models` and keep things tidy. :::info @@ -227,6 +216,7 @@ restart it, you'll get a fresh new database every time. Obviously, this isn't ve any real purpose. Let's make a change to our `build/flecks.yml`: ```yml title="build/flecks.yml" +'@db_test/tags:./packages/tags': {} '@flecks/core': {} '@flecks/db': {} // highlight-start @@ -234,7 +224,6 @@ any real purpose. Let's make a change to our `build/flecks.yml`: database: './persistent.sql' // highlight-end '@flecks/server': {} -'@db_test/tags:./packages/tags': {} ``` Now `npm start` again. You'll see our old familiar message: @@ -288,6 +277,7 @@ Let's add another fleck to our project: Configure `build/flecks.yml`: ```yml title="build/flecks.yml" +'@db_test/tags:./packages/tags': {} '@flecks/core': {} '@flecks/db': {} // highlight-start @@ -303,7 +293,6 @@ Configure `build/flecks.yml`: - '@flecks/db' - '@db_test/tags' // highlight-end -'@db_test/tags:./packages/tags': {} ``` Notice that we configured `@flecks/server.up` to make sure to enforce a specific order in which @@ -440,8 +429,3 @@ docker-compose -f dist/docker-compose.yml up This demonstrates that your application is now being orchestrated by Docker Compose and is chugging right along! - -## Going further - -`@flecks/db` uses Sequelize under the hood. You can dive into -[their documentation](https://sequelize.org/docs/v6/getting-started/) to learn even more. diff --git a/website/sidebars.js b/website/sidebars.js index e812522..a8e381e 100644 --- a/website/sidebars.js +++ b/website/sidebars.js @@ -11,7 +11,8 @@ export default { items: [ 'installation', 'configuration', - 'creating-flecks', + 'adding-flecks', + 'creating-a-fleck', ], }, {