Skip to content

UPGRADE.md

Latest commit

 

History

History
144 lines (114 loc) · 5.79 KB

UPGRADE.md

File metadata and controls

144 lines (114 loc) · 5.79 KB
Raw

Upgrade guide

Emulsify WordPress is a parent theme. Generated child themes do not inherit later starter changes, so most upgrades have two parts: update the parent theme, then decide which starter changes to adopt in each generated project.

Upgrading from 1.x to 2.0.0

2.0.0 is a full rebuild of the WordPress theme around Timber, Emulsify Core 4, Vite, and Twig. Treat it as a theme-platform change rather than a version bump. Step-by-step guidance lives in docs/upgrading-1x-to-2x.md.

Requirements

  • WordPress 6.7 or newer.
  • PHP 8.3 or newer.
  • Timber 2.3 or newer, available to the parent theme.
  • Node.js 24 or newer for generated child theme frontend tooling. Root release tooling requires Node.js 24.10 or newer.
  • Generated child themes keep Template: emulsify in style.css so WordPress loads the parent runtime.

Known breaking changes

  • The theme is now Timber-first. Frontend rendering goes through Twig templates resolved by the parent theme rather than through PHP template parts.
  • The frontend build moved from Webpack to Vite, provided by Emulsify Core 4.
  • Generated child themes use Emulsify Core 4 and its Storybook, Jest, ESLint, Stylelint, and Prettier configuration under config/emulsify-core/.
  • whisk is a generation-only starter source. Do not activate it directly.
  • The starter no longer ships tokens.scss, foundation.scss, or layout.scss entrypoints, a component tree, or a child theme.json. Projects choose and install their own component library after generation.
  • Child theme generation is handled by the parent theme's WP-CLI command, wp emulsify, or by the standalone emulsify-wordpress-starter repository through Emulsify CLI.
  • Generation-only tooling is no longer copied into generated child themes. The .cli directory is excluded by the WP-CLI generator and removed by the standalone starter hook after it runs.
  • Generated child themes now include project documentation. See generated project documentation.

Package changes

  • Added: timber/timber ^2.3 as a parent theme requirement.
  • Added: @emulsify/core ^4.3.2 in generated child themes.
  • Added: PHPCS, PHPStan, WPCS, and WordPress/ACF/WP-CLI stubs as parent theme development requirements.
  • Removed: Webpack-era build dependencies from the starter.

Recommended upgrade path

  1. Confirm the site meets the requirements above.
  2. Update the Emulsify WordPress parent theme to 2.x.
  3. Generate a fresh child theme and port project templates, components, and styling into it rather than upgrading a 1.x child theme in place.
  4. Move frontend build docs, scripts, and team habits from Webpack terminology to the Vite workflow.
  5. Install a component library and rebuild assets so the parent theme can discover built output under dist/.
  6. Run the validation commands in docs/upgrading-1x-to-2x.md.

Generated project documentation

Child themes generated by 2.x include a project-specific README.md plus docs/development.md, docs/upgrading.md, and docs/support-information.md. Both generation paths resolve the same %%EMULSIFY_*%% tokens and fail generation if any token survives, so a generated project never ships template placeholders.

Existing generated child themes are not rewritten. To recover the documentation for an older project, generate a temporary comparison theme with a different machine name, copy the guides across, and delete the temporary theme. The guarantees are described in docs/generated-child-theme-contract.md.

Component inspector

The component inspector is a backward-compatible generated-theme feature available with Emulsify Core 4.3.0 or newer. It discovers components and reports metadata, dependencies, configuration issues, and orphaned files. The implementation remains in @emulsify/core; adopting projects only need to upgrade the dependency and expose its published binary.

Existing generated child themes can opt in with these package.json changes:

{
  "scripts": {
    "inspect:components": "emulsify-inspect-components"
  },
  "dependencies": {
    "@emulsify/core": "^4.3.0"
  }
}

After updating the dependency and lockfile, run the command from the generated theme root:

npm run inspect:components
npm run inspect:components -- --json
npm run inspect:components -- --help

The whisk/ update in this repository only affects WordPress child themes generated after the Emulsify WordPress release that contains it. Existing generated themes do not inherit later starter changes and must update their own package.json.

The same generation boundary applies to the Drupal sister project: Whisk changes only affect themes generated after the new Emulsify Drupal release. Existing Drupal themes must adopt the dependency and script explicitly.

Keep the coordinated release order:

  1. Publish the compatible @emulsify/core 4.3.0 release.
  2. Merge and release the consuming Emulsify WordPress or Emulsify Drupal change.

Project audit

Emulsify Core ships two audit commands that help a generated child theme move off legacy patterns. Run them from the generated theme root:

npm run audit
npm run audit:twig-stories

npm run audit reports Storybook discovery problems, unresolved Twig include() and source() references, Webpack-era patterns, imports that reach into Emulsify Core internals, and platform assumptions that will not hold on WordPress.

npm run audit:twig-stories focuses on legacy Twig stories: large Twig Storybook roots and story formats that predate Emulsify Core 4.

Both commands print a link to the relevant Emulsify Core migration documentation. They report findings only; they do not modify project files.