flecks/packages/core/build/dox/concepts/build.md

# Build directory ⚡️

The `build` directory is where build-time configuration is specified.

The prime example of this for Flecks is `flecks.yml`, but it extends to other more general
configuration such as `.eslintrc.js`, `babel.config.js`, etc.

For a list of all build configuration, see the
[build configuration page](https://github.com/cha0s/flecks/blob/gh-pages/build-configs.md)

## `flecks.yml` ⛏️

`flecks.yml` specifies the flecks that compose your project.

Using `@flecks/create-fleck` creates the following `flecks.yml`:

```yml
'@flecks/core': {}
'@flecks/fleck': {}
```

This means that by default a new fleck will pull in the `@flecks/core` fleck, and the
`@flecks/fleck` fleck, both with default configuration.

### Overriding configuration 💪

`@flecks/core`'s configuration has an `id` key. Starting from the example above, overriding the
ID to, say, `'example'`, would look like this:

```yml
'@flecks/core':
  id: 'example'
'@flecks/fleck': {}
```

See [the configuration page](https://github.com/cha0s/flecks/blob/gh-pages/config.md) for a list of
all configuration.

### Aliasing 🕵️‍♂️

Flecks may be aliased to alternative paths.

Say you have an application structured as a monorepo with a `packages` directory. If you have a
subpackage named `@my-monorepo/foo`, you could alias your fleck, like so:

```yml
'@flecks/core': {}
'@flecks/server': {}
'@my-monorepo/foo:./packages/foo/src': {}
```

Within your application, the fleck will be referred to as `@my-monorepo/foo` even though
`./packages/foo/src` is where the package is actually located.

This way you can use package structure without having to worry about actually publishing them to
npm (or running verdaccio, for instance).

## On-the-fly compilation(!) 🤯

If your flecks are aliased (as above) or symlinked (e.g. `yarn link`), they will be treated
specially and will be compiled on-the-fly. The flecks are searched for a local `babel.config.js`,
which is used to compile the code if present.

This means you can e.g. develop your `packages` in a monorepo with full HMR support, on both the
server and the client, each with their own babel configuration!

Have fun!

## Resolution order 🤔

The flecks server provides an interface (`flecks.buildConfig()`) for gathering configuration files
from the `build` directory. The resolution order is determined by a few variables:

- `filename` specifies the name of the configuration file, e.g. `server.webpack.config.js`.

- `general` specifies a general variation of the given configuration. The general form of `server.webpack.config.js` is `webpack.config.js`.

- `root` specifies an alternative location to search. Defaults to `FLECKS_CORE_ROOT`.

- `fleck` specifies the fleck owning the configuration. `@flecks/server` owns `server.webpack.config.js`.

Given these considerations, and supposing we had the above variables set like:

```javascript
const filename = 'server.webpack.config.js';
const general = 'webpack.config.js';
const root = '/foo/bar/baz';
const fleck = '@flecks/server';
```

Flecks will then search the following paths top-down until it finds the build configuration:

- `/foo/bar/baz/build/server.webpack.config.js`
- `/foo/bar/baz/build/webpack.config.js`
- `${FLECKS_CORE_ROOT}/build/server.webpack.config.js`
- `${FLECKS_CORE_ROOT}/build/webpack.config.js`
- `@flecks/server/build/server.webpack.config.js`
- `@flecks/server/build/webpack.config.js`