Skip to main content

Creating a fleck

If you are following along from the previous getting started configuration page, you have an application with 2 flecks:

  • @flecks/core
  • @flecks/server
About that "2 flecks" thing...

Actually, your server application has 6 flecks at this point:

  • @flecks/build
  • @flecks/build/server
  • @flecks/core
  • @flecks/core/server
  • @flecks/server
  • @flecks/server/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.

flecks can also load dependencies. This is why your application includes @flecks/build: it's marked as a dependency by @flecks/server.

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. flecks also provides a built-in utility to create a fleck.

Your application is a monorepo by default

You may have noticed that your little starter application has a packages directory. By default, flecks structures your application as a monorepo.

This isn't any hard requirement, it's only a suggestion.

Create the fleck​

Let's create our little fleck:

npm init @flecks/fleck -w packages/say-hello

After some output, you'll find your new fleck at packages/say-hello. Let's inspect our build/flecks.yml:

build/flecks.yml
'@flecks/core':
  id: 'hello-world'
'@flecks/server': {}
'@hello-world/say-hello': {}

Your first hook implementation​

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:

packages/say-hello/src/index.js
export const hooks = {
  '@flecks/server.up': async () => {
    process.stdout.write('  hello server\n');
  },
};

Now, restart your application:

npm run start

You will be greeted by a line in the output:

  hello server

flecks injection​

Hook implementations may receive arguments. After any arguments, the flecks instance is always passed.

@flecks/server.up doesn't pass any arguments, so the flecks instance is the first argument. Let's see how to use the instance to read some configuration:

packages/say-hello/src/index.js
export const hooks = {
  '@flecks/server.up': async (flecks) => {
    const {id} = flecks.get('@flecks/core');
    process.stdout.write(`  hello server: ID ${id}\n`);
  },
};
That's hot

Save that file and notice that the server restarted automatically! There are some juicy hints in the logs:

HMR failed for fleck: @flecks/server.up implementation changed!
[HMR] Cannot apply update.
[HMR] Restart requested!
[HMR] You need to restart the application!
[HMR] Restarting application...

It knows.

After which comes the expected line:

  hello server: ID hello-world
Still with us?

...or whatever your application's ID is. We're assuming you're following along from the configuration page.

Next, let's add and interact with some of the flecks shipped by default.