An Nx monorepo for various libraries and plugins.
It is highly recommended when developing locally to use a devcontainer. This will ensure your environment is set up correctly, and not risk interfering with any other settings or packages you may have configured across your desktop.
The .devcontainer directory is fully set up. If you open this repo in VSCode, you should immediately see an option to open it up in DevContainer.
PNPM is used for package management. It is highly efficient for sharing disk space while allowing packages to manage dependencies separately.
Nx is used for task running. It manages the required prerequisite steps (e.g. building dependencies) with caching to simplify workflows.
A majority of the code written here is developed with Typescript targeting a Node ESM executable. Conceptually it is not restricted to only that, and could support other languages as well. No raw Javascript should be be used if Typescript is a viable alternative. CommonJS should be avoided unless explicitly required by consomers. Even then, lightly wrapping ESM with libraries like CommonProxy are preferable to maintaining a full CommonJS codebase.
Eslint enforces highly opinionated linting of Typescript files, to both catch issues and enforce a consitent coding style.
Biome enforces Typescript and JSON formatting. It is an optimized replacement for Prettier.
This repo is designed to be used in a DevContainer. This ensures all your runtimes and configurations are properly set up by default, and won't pollute the rest of your workspace.
"Global" packages are installed automatically if using a dev container, but if not see the Dockerfile for list of dependencies (e.g. Node and pnpm).
Run pnpm i to get started.
From there, run nx run <package-name>:<task>. See Nx documetation for more details.
Many tasks are broken down into subtasks to manage the various steps required. For example a typescript build script may perform some codegen before generating the final .js files. See the nx-lifecyle package to see how we manage this!
Some standard tasks are:
- build
- Generates executable output code
- analyze
- Applies linters/formatters
- test
- Runs full test suite for package
Try running nx run-many -t test to build, analyze, and test the entire package!
See individual packages for documentation.
This repository is currently undergoing a migration to Dagger for CI builds. It will continue to use Nx locally, but will use that metadata to produce much more reliable builds.
All dagger functions are contained in the /dagger directory.
To get started, run dagger call --mod ./dagger/test-and-build/ run --source .
To replicate local Nx builds (build project -> test it -> build dependents -> ...) the nx-dagger executor is used to autogenerate a monorepo Dagger function.
To re-generate that file, edit any relevant settings in nx-dagger.json, and run nx run @leyman/main:dagger.
You may hook up your own Dagger cloud account (dagger login) for better view of execution pipeline and debugging.
It is still highly recommended to run nx run-many -t test before trying to execute dagger.
Any issues like linter or build failures will materialize much faster with Nx, at the cost of greater dependency on global installations and less deterministic caching.
If it works on Nx, it isn't guaranteed to work in CI, but if it works in Dagger it will work on CI!
All changes should include a changeset file that reports how packages are impacted.
Simply run changeset once you are done and follow the instructions in the CLI.
Then include the generated file in your commit.