compas
The Compas CLI
Unified backend tooling.
Examples:
- compas docker up
- compas lint --jsdoc
- compas visualise erd --generated-directory ./src/generated
References:
- Docs: https://compasjs.com
- Source: https://github.com/compasjs/compas
- Issues: https://github.com/compasjs/compas/issues
| Option | Description |
|---|---|
| -h, --help | Display information about the current command. (boolean) |
compas completions
Configure shell auto-complete for this CLI.
| Option | Description |
|---|---|
| -h, --help | Display information about the current command. (boolean) |
compas check-env
Various checks helping with a better Compas experience.
This command is able to check a few things in the current project, to see if it is optimally configured.
- '.env.local' should be in the .gitignore
- '.cache' should be in the .gitignore
- Only a single Compas version should be installed
- Docker should be available to use with
compas docker
| Option | Description |
|---|---|
| -h, --help | Display information about the current command. (boolean) |
compas code-mod
Execute code-mods to help migrating to new Compas versions.
Since Compas generates quite a bit of boilerplate, this command can help you migrate to new Compas versions that have breaking changes in generated code. By detecting usage patterns of the generated output of a previous Compas version, it can migrate (most of) your usages to whatever the new version brings.
| Option | Description |
|---|---|
| -h, --help | Display information about the current command. (boolean) |
compas code-mod list
List the available code-mods.
| Option | Description |
|---|---|
| -h, --help | Display information about the current command. (boolean) |
compas code-mod exec
Execute the specified code-mod.
| Option | Description |
|---|---|
| --name | The code-mod name to execute. (string, required) |
| -h, --help | Display information about the current command. (boolean) |
compas docker
Manage common docker components.
Manages a single PostgreSQL and Minio container for use in all your local projects. It can switch between multiple PostgreSQL versions (12, 13 and 14 are supported via --postgres-version), however only a single version can be 'up' at a time.
PostgreSQL credentials:
postgresql://postgres:postgres@127.0.0.1:5432/postgres
Minio credentials:
- ACCESS_KEY: minio
- SECRET_KEY: minio123
Don't use this command and secrets for your production deployment.
| Option | Description |
|---|---|
| --postgres-version | Specify the PostgreSQL version to use. Defaults to 12. (number) |
| --use-host | Skip Docker altogether and assume that Postgres and Minio are enabled on the host. Alternatively, set COMPAS_SKIP_DOCKER=true. (boolean) |
| -h, --help | Display information about the current command. (boolean) |
compas docker up
Start the managed containers.
| Option | Description |
|---|---|
| --postgres-version | Specify the PostgreSQL version to use. Defaults to 12. (number) |
| --use-host | Skip Docker altogether and assume that Postgres and Minio are enabled on the host. Alternatively, set COMPAS_SKIP_DOCKER=true. (boolean) |
| -h, --help | Display information about the current command. (boolean) |
compas docker down
Stop the managed containers.
Stop any of the containers that could possibly be started by this CLI. It ignores context and stops any PostgreSQL container started by this CLI, ignoring --postgres-version.
| Option | Description |
|---|---|
| --postgres-version | Specify the PostgreSQL version to use. Defaults to 12. (number) |
| --use-host | Skip Docker altogether and assume that Postgres and Minio are enabled on the host. Alternatively, set COMPAS_SKIP_DOCKER=true. (boolean) |
| -h, --help | Display information about the current command. (boolean) |
compas docker clean
Clean up all containers and volumes, or only the PostgreSQL databases of the specified projects.
When no arguments are passed, all created docker containers and volumes are removed.
By passing '--project', it can clean up PostgreSQL databases without having to restart the containers. The flag is repeatable, so multiple projects can be cleaned at the same time. If no value is passed, it defaults to 'process.env.APP_NAME'.
| Option | Description |
|---|---|
| --project | Specify the project(s) to remove. If no value is passed, the current project is read from environment.APP_NAME. (booleanOrString[]) |
| --postgres-version | Specify the PostgreSQL version to use. Defaults to 12. (number) |
| --use-host | Skip Docker altogether and assume that Postgres and Minio are enabled on the host. Alternatively, set COMPAS_SKIP_DOCKER=true. (boolean) |
| -h, --help | Display information about the current command. (boolean) |
compas init
Init various files in the current project.
| Option | Description |
|---|---|
| --all | Enable '--gitignore', '--jsconfig' and '--lint-config'. (boolean) |
| --gitignore | Creates or overwrites the .gitignore, with defaults for IDE(s), Yarn/NPM and caches. (boolean) |
| --jsconfig | Creates or overwrites the root jsconfig.json file, to use with the Typescript Language Server. (boolean) |
| --lint-config | Creates or overwrites .eslintrc.cjs, .eslintignore and .prettierignore files, and overwrites the 'prettier' key in the package.json. (boolean) |
| -h, --help | Display information about the current command. (boolean) |
compas lint
Lint all project files.
Uses Prettier and ESLint to lint project files.
ESLint is used for all JavaScript files and Prettier runs on JavaScript, JSON, Markdown, and YAML files. The default configuration can be initialized via 'compas init --lint-config'.
| Option | Description |
|---|---|
| --skip-prettier | Skip running Prettier. (boolean) |
| --skip-eslint | Skip running ESLint. (boolean) |
| --eslint-cache-location | Location of ESLint cache directory. Defaults to '.cache/eslint/'. (string) |
| -h, --help | Display information about the current command. (boolean) |
compas migrate
Run PostgreSQL migrations via the @compas/store migration system.
The migrations are managed via the @compas/store provided system. And are forward only.
A custom Postgres connection object can be provided by exporting a 'postgresConnectionSettings' object from the files specified via the '--connection-settings' flag.
| Option | Description |
|---|---|
| --connection-settings | Specify a path that contains the PostgreSQL connection object. (string) |
| --watch | Run the command, restarting it when file changes happen. See 'compas help watch' for more information. (boolean) |
| -h, --help | Display information about the current command. (boolean) |
compas migrate info
Print the current migration state.
Print information about the migration state and exit. The information consists of migrations that are not applied yet, and migrations that have 'hashChanges', basically saying that the file on disk is out of sync with the migration that was applied in the past.
| Option | Description |
|---|---|
| --connection-settings | Specify a path that contains the PostgreSQL connection object. (string) |
| --watch | Run the command, restarting it when file changes happen. See 'compas help watch' for more information. (boolean) |
| -h, --help | Display information about the current command. (boolean) |
compas migrate rebuild
Recreate migration state based on the file system.
Rebuild migration table with current file state. This allows for reordering migrations, squashing migrations and other things that alter the migration files, but do not affect the schema in any way. Note that Compas can't enforce any consistency between the migration files and the current schema state. So use with caution.
| Option | Description |
|---|---|
| --connection-settings | Specify a path that contains the PostgreSQL connection object. (string) |
| --watch | Run the command, restarting it when file changes happen. See 'compas help watch' for more information. (boolean) |
| -h, --help | Display information about the current command. (boolean) |
compas run
Run arbitrary JavaScript files, scripts defined in the package.json and scripts located in the scripts directory.
| Option | Description |
|---|---|
| --script-args | Arguments passed as is to the script when executed (like '--port 3000'). (string) |
| --node-args | Arguments passed to Node when executing the script (like '--inspect'). (string) |
| -h, --help | Display information about the current command. (boolean) |
compas run $script
The file or script to run.
| Option | Description |
|---|---|
| --watch | Run the command, restarting it when file changes happen. See 'compas help watch' for more information. (boolean) |
| --script-args | Arguments passed as is to the script when executed (like '--port 3000'). (string) |
| --node-args | Arguments passed to Node when executing the script (like '--inspect'). (string) |
| -h, --help | Display information about the current command. (boolean) |
compas test
Run all tests in your project.
The test runner searches for all files ending with '.test.js' and runs them. Tests run in series in a single worker and subtests run serially in the order they are defined. If '--serial' is not passed, there will be multiple workers each executing parts of the tests.
Test files should be ordinary JavaScript files. By calling 'mainTestFn' at the top of your file you can still use 'node ./path/to/file.test.js' to execute the tests.
Global configuration can be applied to the test runners via a 'test/config.js' file. A global timeout can be configured by setting 'export const timeout = 2500;'. The value is specified in milliseconds. There is also a global 'setup' and 'teardown' function that can be exported from the 'test/config.js' file. They may return a Promise.
To prevent flaky tests, '--randomize-rounds' can be used. This shuffles the order in which the tests are started. And prevents dependencies between test files. Making it easier to run a single test file via for examples 'compas run ./path/to/file.test.js'.
Collecting and processing coverage information is done using C8. Use one of the supported configuration files by C8 to alter its behaviour. See https://www.npmjs.com/package/c8 for more information.
| Option | Description |
|---|---|
| --serial | Run tests serially instead of in parallel. Alternatively set '--parallel-count 1' (boolean) |
| --bail | Exit the test runner after the first failed assertion. Requires '--serial'. (boolean) |
| --parallel-count | The number of workers to use, when running in parallel. Defaulting to (the number of CPU cores - 1) or 4, whichever is lower. (number) |
| --randomize-rounds | Runs test the specified amount of times, shuffling the test file order between runs. (number) |
| --coverage | Collect coverage information while running the tests. (boolean) |
| --with-logs | Enable output of application loggers in the tests. (boolean) |
| --watch | Run the command, restarting it when file changes happen. See 'compas help watch' for more information. (boolean) |
| -h, --help | Display information about the current command. (boolean) |
compas version
Print the installed Compas version and exit
| Option | Description |
|---|---|
| -h, --help | Display information about the current command. (boolean) |
compas help
Display help for any of the available commands.
// TODO
| Option | Description |
|---|---|
| -h, --help | Display information about the current command. (boolean) |
compas watch
Run the command, restarting it when file changes happen.
Some commands in this CLI can be watched. They can be executed via compas watch [..subCommand] or by adding the '--watch' flag when invoking the command.
The watching happens by monitoring all the files in your project and restarting the command once files are changed. Manually restarting is also possible by sending rs<enter> to the program.
Watch behaviour can be tuned by commands. Setting 'modifiers.isWatchable' to 'true' is necessary for it to allow watching, and 'watchSettings' can be specified with custom extensions to be watched or specific directories to ignore. When watch behavior is needed for custom scripts, following the steps in extending the cli is mandatory.
export const cliDefinition = {
name: "my-command",
shortDescription: "My command",
modifiers: {
isWatchable: true, // This is mandatory
},
watchSettings: {
extensions: ["js", "ts"], // Defaults to '["js", "json"]'
ignorePatterns: ["__fixtures__"], // Defaults to '[".cache", "coverage", "node_modules"]'
},
};You can also add a compas config file at 'config/compas.{js,json}' to specify project specific items. They are appended to the specification of the command and can be used if your tests write files that may trigger the watcher. See the Compas configuration reference for more information about the allowed options.
{
"cli": {
"globalWatchOptions": {
"extensions": [],
"ignorePatterns": ["__fixtures__", "test/tmp"]
}
}
}| Option | Description |
|---|---|
| -h, --help | Display information about the current command. (boolean) |