Skip to main content

Building your application

flecks takes a build manifest at build/flecks.yml such as:

'@flecks/core': {}
'@flecks/server': {}
'@hello-world/say-hello:./packages/say-hello': {}

and determines both the roots and paths that compose the application, and whether they require compilation.

Roots​

A root is the package root of a fleck. A package root is defined as a directory with a package.json file.

Multiple fleck paths may share the same root.

Sneaky little fleckses

@flecks/react's root contains 7 flecks!

  • @flecks/react
  • @flecks/react/client
  • @flecks/react/router
  • @flecks/react/router/client
  • @flecks/react/router/server
  • @flecks/react/server
  • @flecks/react/tabs

A root prefers to discover flecks within the src directory, but will fallback to discovering files under the root if that fails.

Clean defaults

When you create a fleck with @flecks/create-fleck, it organizes your source code into a src directory as a default convention. Automatically discovering src allows you to e.g. require('@hello-world/say-hello/server') instead of having to use the real filepath e.g. require('@hello-world/say-hello/src/server').

Compilation​

A fleck will not always be compiled. flecks you e.g. install from npm have already gone through a compilation step and will load very fast. Skipping compilation saves a lot of time when building an application!

There are some conditions which when matched will result in a fleck being compiled.

If you organize your application's flecks as npm workspaces (the current recommended example), npm will symlink your packages in the application.

Compilation condition

If a root path is a symlinked path, the root path is compiled.

Land of linkin'

@flecks/create-fleck uses a couple conventions to structure your fleck:

  • Source code is organized under the src directory
  • Build output goes to dist/fleck

If the linked path ends with /dist/fleck, the parent directory will be used as the root path! This means that flecks will discover the src directory as explained above and use it when compiling your application. Nice and hot!

Paths and aliases​

Paths are the package names of flecks. From our example above, @hello-world/say-hello is a path. ./packages/say-hello is an alias.

Compilation condition

The root path of an aliased fleck is compiled.

Pitfalls with aliasing
Aliased modules spaghetti

When an aliased fleck is compiled, its own node_modules directory is added to the module search paths for the application. This makes it very easy to get started writing a modular fleck.

There can easily come a point where aliased flecks in an application may have very esoteric relationship between their node_modules directories, including but not limited to duplicate versions of libraries being included in a compilation.

flecks makes very little effort to solve this problem as it is considered out of scope.

Unlikely alias

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 exists on npm: don't do that).

All that being said, aliasing exists!

If you'd like to help define better behavior for these edge cases you could always submit a pull request. 😄

Link 'em up

When you are rapidly developing anything Sufficiently Complex™, best practice is to symlink your fleck so that your package manager can do its job and manage your dependency tree.

Aliasing is only provided as an escape hatch.