cha0s/flecks
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat: dox++

Browse Source
This commit is contained in:
cha0s 2024-01-04 03:23:04 -06:00
parent 0c470cfae1
commit 18a48034e9
5 changed files with 115 additions and 119 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

41
website/docs/adding-flecks.mdx Normal file
View File

@ -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!

57
website/docs/configuration.mdx
View File

@ -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:
<InstallPackage pkg="@flecks/web" />
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.

81
website/docs/creating-flecks.mdx → website/docs/creating-a-fleck.mdx
View File

@ -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
<details>
<summary>About that "3 flecks" thing...</summary>
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:
<Create type="fleck" pkg="say-hello" />
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).
<details>
<summary>Wait, my flecks don't have to be in <code>node_modules</code>?</summary>
<summary>Wait, my modules don't have to be in <code>node_modules</code>?</summary>
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!
:::
</details>
### 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:
<InstallPackage pkg="@flecks/electron" />
```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)

52
website/docs/database.mdx
View File

@ -18,17 +18,10 @@ We'll start from scratch as an example. Create a new flecks application:
<Create pkg="db_test" type="app" />
Now in your new application directory, install `@flecks/db`:
Now in your new application directory, add `@flecks/db`:
<InstallPackage pkg="@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:
<Create pkg="tags" type="fleck" />
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.

3
website/sidebars.js
View File

@ -11,7 +11,8 @@ export default {
items: [
'installation',
'configuration',
'creating-flecks',
'adding-flecks',
'creating-a-fleck',
],
},
{