Skip to content

Release(2.3.0): Add WordPress platform support #347

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
callinmullaney wants to merge 10 commits into
base: main
Choose a base branch
from
Open

Release(2.3.0): Add WordPress platform support #347

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
10 commits
Select commit Hold shift + click to select a range
e6a5f70
chore(deps-dev): bump lint-staged from 17.0.7 to 17.0.8
dependabot[bot] Jun 22, 2026
7485262
Merge pull request #343 from emulsify-ds/dependabot/npm_and_yarn/lint…
callinmullaney Jun 22, 2026
20b9637
chore(deps-dev): bump @commitlint/cli from 21.0.2 to 21.1.0
dependabot[bot] Jun 24, 2026
bd8c947
chore(deps-dev): bump @commitlint/config-conventional
dependabot[bot] Jun 24, 2026
d8a5744
chore(deps-dev): bump @types/node from 26.0.0 to 26.0.1
dependabot[bot] Jun 25, 2026
b5316fd
feat(platform): add WordPress support
Jun 28, 2026
113030f
Merge pull request #344 from emulsify-ds/dependabot/npm_and_yarn/comm…
callinmullaney Jun 28, 2026
02e2347
Merge pull request #345 from emulsify-ds/dependabot/npm_and_yarn/comm…
callinmullaney Jun 28, 2026
6f4a96b
Merge pull request #346 from emulsify-ds/dependabot/npm_and_yarn/type…
callinmullaney Jun 28, 2026
41fd6f8
build(deps): update dependencies and audit fixes
Jul 4, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
8 changes: 8 additions & 0 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -37,6 +37,14 @@ emulsify component install card
emulsify component create promo-card --directory molecules --format default
```

Built-in platforms are `drupal`, `wordpress`, and `none`. For WordPress child themes, use the WordPress platform and starter:

```bash
emulsify init "My Theme" ./wp-content/themes --platform wordpress
```

When WordPress is auto-detected, Emulsify initializes child themes into the detected themes directory, such as `wp-content/themes/my-theme` or `web/app/themes/my-theme` for Bedrock.

For non-interactive environments, pass the flags that normally prompt for input:

```bash
Expand Down
26 changes: 13 additions & 13 deletions docs/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,16 +2,16 @@

These docs expand on the short project README and are organized by the task a project user or maintainer is usually trying to complete.

| Topic | Use This When |
| ----------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- |
| [CLI Reference](./cli-reference.md) | Looking up commands, aliases, options, and examples. |
| [Project Initialization](./project-initialization.md) | Creating a new Emulsify project from a starter, including Drupal and non-interactive examples. |
| [Systems](./systems.md) | Listing built-in systems, installing systems, using custom system repositories, or understanding system configuration. |
| [Components](./components.md) | Listing installable components, installing components and dependencies, using dry runs, and creating local components. |
| [Project Configuration](./configuration.md) | Understanding `project.emulsify.json`, system and variant references, structure mappings, and validation. |
| [Component Template Overrides](./component-template-overrides.md) | Replacing the built-in `component create` templates with project-level templates. |
| [Hooks And Cache](./hooks-and-cache.md) | Understanding starter hooks, system install hooks, script execution, and the `~/.emulsify/cache` repository cache. |
| [Development](./development.md) | Setting up this repository, understanding source layout, and running checks. |
| [Release](./release.md) | Understanding CI, develop version bumps, semantic-release, and npm publishing. |
| [Contributors](./contributors.md) | Viewing project contributors moved out of the root README. |
| [Website Usage Copy](./emulsify-info-cli-updates.md) | Copy-ready usage content for the `emulsify.info` CLI page. |
| Topic | Use This When |
| ----------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- |
| [CLI Reference](./cli-reference.md) | Looking up commands, aliases, options, and examples. |
| [Project Initialization](./project-initialization.md) | Creating a new Emulsify project from a starter, including Drupal, WordPress, and non-interactive examples. |
| [Systems](./systems.md) | Listing built-in systems, installing systems, understanding variant compatibility, or using custom system repositories. |
| [Components](./components.md) | Listing installable components, installing components and dependencies, using dry runs, and creating local components. |
| [Project Configuration](./configuration.md) | Understanding `project.emulsify.json`, system and variant references, structure mappings, and validation. |
| [Component Template Overrides](./component-template-overrides.md) | Replacing the built-in `component create` templates with project-level templates. |
| [Hooks And Cache](./hooks-and-cache.md) | Understanding starter hooks, system install hooks, script execution, and the `~/.emulsify/cache` repository cache. |
| [Development](./development.md) | Setting up this repository, understanding source layout, and running checks. |
| [Release](./release.md) | Understanding CI, develop version bumps, semantic-release, and npm publishing. |
| [Contributors](./contributors.md) | Viewing project contributors moved out of the root README. |
| [Website Usage Copy](./emulsify-info-cli-updates.md) | Copy-ready usage content for the `emulsify.info` CLI page. |
32 changes: 24 additions & 8 deletions docs/cli-reference.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -29,21 +29,29 @@ emulsify init [name] [path]

Options:

| Option | Description |
| ------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------- |
| `-m, --machineName <machineName>` | Machine-friendly project folder and config name. If omitted, the CLI derives it from the project name. Drupal machine names use underscores. |
| `-s, --starter <repository>` | Starter Git repository to clone. |
| `-c, --checkout <commit/branch/tag>` | Starter commit, branch, or tag to check out after clone. |
| `-p, --platform <platform>` | Platform to use when auto-detection is unavailable or should be overridden. Built-in starters are currently available for `drupal` and `none`. |
| `-y, --yes` | Accept default values for missing init options without prompting. |
| Option | Description |
| ------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------- |
| `-m, --machineName <machineName>` | Machine-friendly project folder and config name. If omitted, the CLI derives it from the project name. Drupal machine names use underscores. |
| `-s, --starter <repository>` | Starter Git repository to clone. |
| `-c, --checkout <commit/branch/tag>` | Starter commit, branch, or tag to check out after clone. |
| `-p, --platform <platform>` | Platform to use when auto-detection is unavailable or should be overridden. Built-in platforms are `drupal`, `wordpress`, and `none`. |
| `-y, --yes` | Accept default values for missing init options without prompting. |

When `--platform` is not provided and the platform cannot be detected, interactive terminals prompt with `drupal` and `none`.
When `--platform` is not provided and the platform cannot be detected, interactive terminals prompt with `drupal`, `wordpress`, and `none`.

WordPress auto-detection creates child themes inside the detected themes directory:

- Standard WordPress: `wp-content/themes/<machine-name>`
- Bedrock: `web/app/themes/<machine-name>`

The built-in WordPress starter is `https://github.com/emulsify-ds/emulsify-wordpress-starter`.

Examples:

```bash
emulsify init "My Project" ./projects --platform none
emulsify init "My Theme" ./web/themes/custom --platform drupal
emulsify init "My Theme" ./wp-content/themes --platform wordpress
emulsify init "My Theme" ./web/themes/custom --platform drupal --machineName my_custom_theme
emulsify init "My Project" ./projects --starter https://github.com/emulsify-ds/emulsify-starter --checkout main --platform none
```
Expand Down Expand Up @@ -93,6 +101,14 @@ emulsify system install --repository https://github.com/example/example-system.g

Selecting `create a new system` writes `system.emulsify.json` in the current Emulsify project root. Complete the generated system name, repository, structures, variants, and components before using it to install or generate components.

System variant compatibility is selected from each variant's `platform` expression. Examples:

- `"platform": "wordpress"` matches WordPress projects.
- `"platform": "drupal || wordpress"` matches Drupal and WordPress projects.
- `"platform": "none"` is generic and can be installed by any concrete project platform.

Project configuration uses only concrete `project.platform` values: `drupal`, `wordpress`, or `none`. Only system variants use `||` expressions. A project with `project.platform: "none"` can install any component library system; when multiple variants are equally compatible, the CLI prompts in an interactive terminal or errors in non-interactive mode.

## `component list`

```bash
Expand Down
48 changes: 30 additions & 18 deletions docs/configuration.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -19,12 +19,14 @@ Emulsify CLI stores project state in `project.emulsify.json`. Commands search fo
}
```

| Field | Required | Description |
| --------------------- | -------- | ------------------------------------------------ |
| `project.platform` | Yes | Platform name for starter and variant selection. |
| `project.name` | Yes | Human-facing project name provided during init. |
| `project.machineName` | Yes | Machine-friendly folder/config name. |
| `starter.repository` | Yes | Starter repository used to create the project. |
| Field | Required | Description |
| --------------------- | -------- | ------------------------------------------------------------------------------------------- |
| `project.platform` | Yes | Concrete platform name for starter and variant selection: `drupal`, `wordpress`, or `none`. |
| `project.name` | Yes | Human-facing project name provided during init. |
| `project.machineName` | Yes | Machine-friendly folder/config name. |
| `starter.repository` | Yes | Starter repository used to create the project. |

`project.platform` never uses compatibility expressions. Values such as `drupal || wordpress` are valid only on system variant `platform` fields.

## System And Variant Configuration

Expand All @@ -48,15 +50,25 @@ Emulsify CLI stores project state in `project.emulsify.json`. Commands search fo
}
```

| Field | Required After System Install | Description |
| ---------------------------------- | ----------------------------- | ---------------------------------------------------------------------------------------------------------------------- |
| `system.repository` | Yes | Git repository containing the selected system. Must be a URL ending in `.git` for commands that parse the system name. |
| `system.checkout` | Yes | Commit, branch, or tag used for the cached system. |
| `variant.platform` | Yes | Platform variant selected from the system. Built-in schemas currently allow `none` and `drupal`. |
| `variant.structureImplementations` | Yes | Project-relative directories for each named system structure. |
| Field | Required After System Install | Description |
| ---------------------------------- | ----------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
| `system.repository` | Yes | Git repository containing the selected system. Must be a URL ending in `.git` for commands that parse the system name. |
| `system.checkout` | Yes | Commit, branch, or tag used for the cached system. |
| `variant.platform` | Yes | Selected system variant platform string. It may be concrete, such as `wordpress`, or an expression such as `drupal \|\| wordpress`. |
| `variant.structureImplementations` | Yes | Project-relative directories for each named system structure. |

Component commands require both `system` and `variant` to be present.

Variant compatibility examples:

```json
{ "platform": "wordpress" }
{ "platform": "drupal || wordpress" }
{ "platform": "none" }
```

`variant.platform: "none"` is generic and can be selected by any concrete project platform. A project with `project.platform: "none"` can install any compatible component library system; if multiple variants are equally compatible, the CLI prompts in an interactive terminal or errors in non-interactive mode.

## Structure Implementations

Structure implementations tell the CLI where installed or generated components belong.
Expand Down Expand Up @@ -107,9 +119,9 @@ Common validation issues:

Manual edits are safe when they preserve the schema and match the installed system. Be careful changing:

| Field | Risk |
| ---------------------------------- | -------------------------------------------------------------------------------------------------------------------- |
| `system.checkout` | The local cache path depends on checkout. Changing it may cause the CLI to clone or load a different system version. |
| `system.repository` | Component commands parse the system name from this URL and expect a `.git` suffix. |
| `variant.structureImplementations` | Install and create destinations are calculated from these directories. |
| `project.platform` | System install selects variants from this value. Existing system and variant config may no longer match. |
| Field | Risk |
| ---------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `system.checkout` | The local cache path depends on checkout. Changing it may cause the CLI to clone or load a different system version. |
| `system.repository` | Component commands parse the system name from this URL and expect a `.git` suffix. |
| `variant.structureImplementations` | Install and create destinations are calculated from these directories. |
| `project.platform` | System install selects variants from this concrete value. Existing system and variant config may no longer match. Do not change it to a `\|\|` expression. |
4 changes: 2 additions & 2 deletions docs/development.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -36,7 +36,7 @@ emulsify --help

| Script | Purpose |
| ---------------------------- | ------------------------------------------------------------------------------------------------------------------------ |
| `npm run build` | Generate schema types, compile TypeScript, copy `package.json` to `dist`, and install production dependencies in `dist`. |
| `npm run build` | Generate schema types, compile TypeScript, copy package metadata to `dist`, and install production dependencies in `dist`. |
| `npm run build-schema-types` | Generate TypeScript definitions from JSON Schema files. |
| `npm run build-ts` | Compile TypeScript with `tsconfig.dist.json`. |
| `npm run watch` | Rebuild when files in `src` change. |
Expand Down Expand Up @@ -75,4 +75,4 @@ npm run build
npm run test
```

`npm run build` may report npm audit warnings from dependencies after the production install in `dist`; those warnings are not TypeScript build failures.
`npm run build` installs production dependencies in `dist` from the root lockfile.
Loading
Loading