diff --git a/README.md b/README.md index aab24c1..a1299d7 100644 --- a/README.md +++ b/README.md @@ -1,13 +1,15 @@ [![Emulsify Design System](https://user-images.githubusercontent.com/409903/170579210-327abcdd-2c98-4922-87bb-36446a4cc013.svg)](https://www.emulsify.info/) ![npm](https://img.shields.io/npm/dm/@emulsify/cli?style=flat-square) -# emulsify-cli +# Emulsify CLI -Command line interface for Emulsify. +Command line interface for Emulsify projects. ## Installation -This project is deployed to [npm](https://www.npmjs.com/package/@emulsify/cli). In order to use this CLI, install it as a global dependency: +Emulsify CLI requires Node 24 or newer. + +Install Emulsify CLI globally from [npm](https://www.npmjs.com/package/@emulsify/cli): ```bash npm install -g @emulsify/cli @@ -15,11 +17,113 @@ npm install -g @emulsify/cli ## Usage -For more information on how to use emulsify-cli, please see the [usage documentation](https://www.emulsify.info/docs/supporting-projects/emulsify-cli/emulsify-cli-usage). +Run `emulsify --help` for the current command list. + +### Commands + +| Command | Alias | Description | +| ----------------------------------- | ----------------------------- | ----------------------------------------------------------------- | +| `emulsify init [name] [path]` | | Initializes an Emulsify project from a starter. | +| `emulsify system list` | `emulsify system ls` | Lists built-in systems available for installation. | +| `emulsify system install [name]` | | Installs a system in the current Emulsify project. | +| `emulsify component list` | `emulsify component ls` | Lists components available from the installed system and variant. | +| `emulsify component install [name]` | `emulsify component i [name]` | Installs one component from the installed system and variant. | +| `emulsify component create [name]` | `emulsify component c [name]` | Creates a local component in the current Emulsify project. | + +### Initialize A Project + +`emulsify init [name] [path]` clones a starter, writes the project configuration, installs dependencies, runs the starter init hook when present, and removes the starter Git history. + +Options: + +- `--machineName `: Sets the machine-friendly project name. When omitted, Emulsify CLI derives it from the project name. +- `--starter `: Uses a specific starter repository. +- `--checkout `: Checks out a specific starter commit, branch, or tag. +- `--platform `: Sets the project platform when auto-detection is unavailable or should be overridden. For Drupal projects, pass `drupal`. +- `--yes`: Accepts default init values for missing options without prompting. + +Current starter repositories: + +- `https://github.com/emulsify-ds/emulsify-starter` +- `https://github.com/emulsify-ds/emulsify-drupal-starter` + +Examples: + +```bash +emulsify init "My Project" ./projects +emulsify init "My Theme" ./web/themes/custom --platform drupal --yes +emulsify init "My Project" ./projects --starter https://github.com/emulsify-ds/emulsify-starter --checkout main +``` + +### Systems + +`emulsify system list` lists the built-in systems that Emulsify CLI can install. `emulsify system ls` is the same command. + +```bash +emulsify system list +emulsify system ls +``` + +`emulsify system install [name]` installs a system in the current Emulsify project. Use `compound` to install the built-in Compound system. The command installs required components by default. + +Options: + +- `--repository `: Installs a system from a specific Git repository. +- `--checkout `: Checks out a specific system commit, branch, or tag. This is required when `--repository` is used. +- `--all`: Installs all available components from the system instead of only required components. -### Customizing component templates +Examples: + +```bash +emulsify system install compound +emulsify system install compound --all +emulsify system install --repository https://github.com/example/example-system.git --checkout v1.0.0 +``` -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. +### Components + +`emulsify component list` lists components available from the installed system and variant. `emulsify component ls` is the same command. + +```bash +emulsify component list +emulsify component ls +``` + +`emulsify component install [name]` installs one component from the installed system and variant. `emulsify component i [name]` is the same command. + +Options: + +- `--force`: Replaces an installed component. +- `--all`: Installs all available components instead of one named component. + +Examples: + +```bash +emulsify component install button +emulsify component i card --force +emulsify component install --all +``` + +`emulsify component create [name]` creates a local component in the current Emulsify project. `emulsify component c [name]` is the same command. + +Options: + +- `--directory `: Sets the variant structure directory where the component is created. +- `--format `: Sets the component format. Supported values are `default` and `sdc`. +- `--yes`: Replaces an existing component without an overwrite confirmation prompt. + +In non-interactive environments, pass both `--directory` and `--format`. + +Examples: + +```bash +emulsify component create card --directory base --format default +emulsify component create teaser --directory molecules --format sdc --yes +``` + +### Component Template Overrides + +Projects can override the built-in `component create` templates by adding component template override files under `.cli/templates/` at the Emulsify project root. Overrides replace only the known artifacts that Emulsify CLI already generates; they do not add extra files or change which files are created. Default component overrides: @@ -36,13 +140,23 @@ SDC component overrides: - `.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. +Override files can use double-brace tokens: + +- `{{ filename }}` +- `{{ className }}` +- `{{ camelName }}` +- `{{ snakeName }}` +- `{{ humanName }}` +- `{{ directory }}` +- `{{ format }}` + +For each generated artifact, Emulsify CLI first checks for the matching override file. If the override is missing, the built-in template is used. If the override exists but is empty, the built-in template is used and a warning is logged. Unknown tokens are left unchanged and logged as warnings. Partial override sets are supported, so a project can override only `component.twig` and keep the built-in SCSS, data, and story templates. Extra arbitrary files are not generated by component template overrides. -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. +For more documentation, see the [Emulsify CLI usage documentation](https://www.emulsify.info/docs/supporting-projects/emulsify-cli/emulsify-cli-usage). ## 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: +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`. @@ -54,7 +168,7 @@ Emulsify-cli is developed using TypeScript. You can find all of the source files ### Setup -- Install the version of node as specified in this project's `.nvmrc` file. If you are using nvm, simply run `nvm use`. +- Install the version of Node specified in this project's `.nvmrc` file. If you are using nvm, 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`. @@ -63,7 +177,7 @@ Emulsify-cli is developed using TypeScript. You can find all of the source files ### 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 build-schema-types`: Compiles the JSON Schema definitions within this project into TypeScript 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. @@ -74,7 +188,7 @@ Emulsify-cli is developed using TypeScript. You can find all of the source files ## 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`. +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 diff --git a/docs/emulsify-info-cli-updates.md b/docs/emulsify-info-cli-updates.md new file mode 100644 index 0000000..014127b --- /dev/null +++ b/docs/emulsify-info-cli-updates.md @@ -0,0 +1,146 @@ +# Emulsify CLI Website Updates + +Copy-ready updates for the emulsify.info Emulsify CLI usage page. + +## Installation + +Emulsify CLI requires Node 24 or newer. + +Install Emulsify CLI globally with npm: + +```bash +npm install -g @emulsify/cli +``` + +## Commands + +| Command | Alias | Description | +| ----------------------------------- | ----------------------------- | ----------------------------------------------------------------- | +| `emulsify init [name] [path]` | | Initializes an Emulsify project from a starter. | +| `emulsify system list` | `emulsify system ls` | Lists built-in systems available for installation. | +| `emulsify system install [name]` | | Installs a system in the current Emulsify project. | +| `emulsify component list` | `emulsify component ls` | Lists components available from the installed system and variant. | +| `emulsify component install [name]` | `emulsify component i [name]` | Installs one component from the installed system and variant. | +| `emulsify component create [name]` | `emulsify component c [name]` | Creates a local component in the current Emulsify project. | + +## Initialize A Project + +`emulsify init [name] [path]` clones a starter, writes the project configuration, installs dependencies, runs the starter init hook when present, and removes the starter Git history. + +Options: + +- `--machineName `: Sets the machine-friendly project name. When omitted, Emulsify CLI derives it from the project name. +- `--starter `: Uses a specific starter repository. +- `--checkout `: Checks out a specific starter commit, branch, or tag. +- `--platform `: Sets the project platform when auto-detection is unavailable or should be overridden. For Drupal projects, pass `drupal`. +- `--yes`: Accepts default init values for missing options without prompting. + +Current starter repositories: + +- `https://github.com/emulsify-ds/emulsify-starter` +- `https://github.com/emulsify-ds/emulsify-drupal-starter` + +Examples: + +```bash +emulsify init "My Project" ./projects +emulsify init "My Theme" ./web/themes/custom --platform drupal --yes +emulsify init "My Project" ./projects --starter https://github.com/emulsify-ds/emulsify-starter --checkout main +``` + +## Systems + +`emulsify system list` lists the built-in systems that Emulsify CLI can install. `emulsify system ls` is the same command. + +```bash +emulsify system list +emulsify system ls +``` + +`emulsify system install [name]` installs a system in the current Emulsify project. Use `compound` to install the built-in Compound system. The command installs required components by default. + +Options: + +- `--repository `: Installs a system from a specific Git repository. +- `--checkout `: Checks out a specific system commit, branch, or tag. This is required when `--repository` is used. +- `--all`: Installs all available components from the system instead of only required components. + +Examples: + +```bash +emulsify system install compound +emulsify system install compound --all +emulsify system install --repository https://github.com/example/example-system.git --checkout v1.0.0 +``` + +## Components + +`emulsify component list` lists components available from the installed system and variant. `emulsify component ls` is the same command. + +```bash +emulsify component list +emulsify component ls +``` + +`emulsify component install [name]` installs one component from the installed system and variant. `emulsify component i [name]` is the same command. + +Options: + +- `--force`: Replaces an installed component. +- `--all`: Installs all available components instead of one named component. + +Examples: + +```bash +emulsify component install button +emulsify component i card --force +emulsify component install --all +``` + +`emulsify component create [name]` creates a local component in the current Emulsify project. `emulsify component c [name]` is the same command. + +Options: + +- `--directory `: Sets the variant structure directory where the component is created. +- `--format `: Sets the component format. Supported values are `default` and `sdc`. +- `--yes`: Replaces an existing component without an overwrite confirmation prompt. + +In non-interactive environments, pass both `--directory` and `--format`. + +Examples: + +```bash +emulsify component create card --directory base --format default +emulsify component create teaser --directory molecules --format sdc --yes +``` + +## Component Template Overrides + +Projects can override the built-in `component create` templates by adding component template override files under `.cli/templates/` at the Emulsify project root. Overrides replace only the known artifacts that Emulsify 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: + +- `{{ filename }}` +- `{{ className }}` +- `{{ camelName }}` +- `{{ snakeName }}` +- `{{ humanName }}` +- `{{ directory }}` +- `{{ format }}` + +For each generated artifact, Emulsify CLI first checks for the matching override file. If the override is missing, the built-in template is used. If the override exists but is empty, the built-in template is used and a warning is logged. Unknown tokens are left unchanged and logged as warnings. Partial override sets are supported, so a project can override only `component.twig` and keep the built-in SCSS, data, and story templates. Extra arbitrary files are not generated by component template overrides.