emulsify-cli

Command line interface for Emulsify.

Installation

This project is deployed to npm. In order to use this CLI, install it as a global dependency:

npm install -g @emulsify/cli

Usage

For more information on how to use emulsify-cli, please see the usage documentation.

Customizing component templates

Projects can override the built-in component create templates by adding files under .cli/templates/ at the Emulsify project root. Overrides replace only the known artifacts that the CLI already generates; they do not add extra files or change which files are created.

Default component overrides:

• .cli/templates/default/component.twig
• .cli/templates/default/component.scss
• .cli/templates/default/component.yml
• .cli/templates/default/component.stories.js

SDC component overrides:

• .cli/templates/sdc/component.twig
• .cli/templates/sdc/component.scss
• .cli/templates/sdc/component.component.yml
• .cli/templates/sdc/component.js
• .cli/templates/sdc/component.stories.js

Override files can use double-brace tokens. Supported tokens are {{ filename }}, {{ className }}, {{ camelName }}, {{ snakeName }}, {{ humanName }}, {{ directory }}, and {{ format }}. Unknown tokens are left unchanged and logged as warnings.

For each generated artifact, the CLI first checks for the matching override file. If the override is missing or empty, the built-in template is used. Partial override sets are supported, so a project can override only component.twig and keep the built-in SCSS, data, and story templates. Arbitrary extra files and template ejection helpers are future work.

Development

Emulsify-cli is developed using TypeScript. You can find all of the source files in the src directory, which is organized in the following manner:

• src/index.ts - uses Commander to compose the CLI.
• src/handlers - contains all functions that handle CLI commands, such as emulsify init.
• src/lib - general definitions and logging tools.
• src/schemas - contains JSON-Schema files that describe project, system, and variant configuration. These schema files are used to generate TypeScript types.
• src/scripts - holds utility scripts for the project.
• src/types - type modules live here, auto-generated ones are prefixed with an underscore (_).
• src/util - contains utility functions that are used in handlers to do various things, such as caching systems and resolving component template overrides.

Setup

• Install the version of node as specified in this project's .nvmrc file. If you are using nvm, simply run nvm use.
• Clone this repository into a directory of your choosing.
• In the directory, run npm install.
• Build the project: npm run build, or watch: npm run watch.
• To test the CLI, run: npm link.

Scripts

• npm run build: builds the project based on the configuration in tsconfig.dist.json.
• npm run build-schema-types: Compiles the json-schema definitions within this project into ts types.
• npm run watch: watches the codebase, and re-compiles every time a change is made.
• npm run format: uses prettier to format all ts files within the codebase.
• npm run lint: runs the Jest test suite via the test script.
• npm run test: runs Jest on the codebase. You can specify a path to a single test, and add any flags supported by Jest's CLI.
• npm run type: uses typescript to check all type signatures.
• npm run twatch: runs Jest without coverage, in verbose and watch mode. This is useful for running a single test during active development.
• npm run semantic-release: publishes a release using release.config.cjs.

Deployment

This project is automatically built and deployed to NPM via the release GitHub Actions workflow. Pushes to main run npm run build and then npm run semantic-release.

Contributors

Patrick Coffey	Brian Lewis	Randy Oest	Callin Mullaney	Jeff Tomlinson	mikeethedude
Roberto Hernández Badilla	Andrii Shutov	Jim Vomero	Caleb Tucker-Raymond	Carlos Valencia Rivero	Igor R. Plity
Ryan Hagerty