Emulsify Core

An open-source toolset for creating and implementing design systems.

Emulsify Core provides shared Vite build configuration and a Storybook component library setup for component-driven development. Twig-based components and React components are both supported authoring models. A project can be Twig-first, React-first, or intentionally mixed.

How Emulsify Core Works

• Vite builds project JavaScript, Sass/CSS, Twig templates, component metadata, and static component assets.
• Storybook uses the React/Vite framework.
• Twig files can render in React-based Storybook through renderTwig().
• React components render through Storybook's React/Vite support.
• Twig and React stories can coexist in the same Storybook instance.
• project.emulsify.json is the source of truth for platform and structure configuration.
• Platform-specific behavior is controlled by adapters instead of being assumed globally.
• Node.js 24 or later is required.

Project Evolution

Emulsify Core has grown through each major release while keeping the same practical goal: make component-library tooling easier to share across real projects.

• 1.x established Emulsify Core as a reusable package for Storybook, Webpack, linting, a11y checks, project overrides, and asset handling.
• 2.x expanded component structure support, improved Drupal SDC compatibility, upgraded Storybook, and made more project files configurable from consuming projects.
• 3.x modernized the runtime around ESM and Node 24, continued Storybook and dependency upgrades, improved component asset copying, and strengthened compatibility for existing Drupal-oriented builds.
• The current release moves the build system to Vite, runs Storybook on React/Vite, supports Twig and React stories side by side, and normalizes platform and project-structure behavior through project.emulsify.json.

The latest version is the next evolution of that work: faster builds, clearer public APIs, less global Drupal assumption, and a broader foundation for CMS themes, standalone UI libraries, and mixed component systems.

See Version Evolution for more release history.

Authoring Models

Twig and React are equally valid ways to build component libraries with Emulsify Core. The right authoring model depends on the consuming project:

• Use Twig for CMS themes and server-rendered template systems. Drupal has a dedicated adapter today; Craft CMS and WordPress + Timber can use the generic adapter unless a project adds platform-specific behavior.
• Use React for standalone UI libraries, application components, or projects that already use React.
• Use mixed Twig and React when a design system needs to document both CMS-rendered and JavaScript-rendered components in the same Storybook instance.

See Component Authoring for Twig, React, mixed Storybook, and shared Sass examples.

Basic Usage

Installation and project scripts are usually provided by a starter or platform integration. Manual setup starts with:

npm install @emulsify/core

Every project should provide a project.emulsify.json file at the project root:

{
  "project": {
    "platform": "generic",
    "name": "example",
    "machineName": "example"
  }
}

Common project scripts call the shared Emulsify Core Vite and Storybook config:

• storybook: starts Storybook development.
• storybook-build: builds static Storybook output.
• build: runs the Vite build for JS, CSS, copied Twig templates, component metadata, and static component assets.
• lint: lints maintained project source.

Documentation

The documentation is split by task:

Topic	Use This When
Version Evolution	Understanding how Emulsify Core has evolved across major releases.
Component Authoring	Choosing Twig, React, or mixed Storybook authoring and comparing component examples.
Storybook	Rendering Twig stories, using renderTwig(), understanding Twig runtime helpers, and mixing Twig with React stories.
Project Structure And Output	Configuring src/components, root ./components, variant.structureImplementations, and expected output paths.
Platform Adapters	Understanding generic, drupal, platform resolution order, and Drupal SDC behavior.
Extension Points	Adding Vite plugins, Tailwind CSS, Storybook preview overrides, and other framework tooling.
Performance	Understanding sourcemaps, eager Twig imports, Tailwind scanning, copied files, and fixture validation.
Native Twig Extensions	Using bem(), add_attributes(), and switch/case/default/endswitch in Twig.js.
Release Verification	Running 4.x release checks, tarball smoke tests, and semantic-release dry runs before publishing.
Migration	Upgrading from earlier versions while preserving existing structures.

Known Limitations

• Implemented platform adapters are currently generic and drupal. WordPress + Timber and Craft CMS are supported as Twig-oriented use cases through the generic adapter today; dedicated adapters are future opportunities. See Platform Adapters.
• Storybook's Twig resolver eagerly imports Twig modules and raw Twig source. This is reliable for include() and source(), but large Twig libraries should keep Storybook source roots intentional. See Performance.
• Production sourcemaps are enabled by default unless a project overrides Vite config through config/emulsify-core/vite/plugins.*. See Performance.
• Project extensions use the public config/emulsify-core directory: config/emulsify-core/vite/plugins.* for Vite, config/emulsify-core/storybook/... for Storybook, and config/emulsify-core/a11y.config.js for a11y. See Extension Points.
• Webpack-specific customizations must be migrated manually to Vite plugins or extendConfig(). See Migration.
• Drupal SDC mirroring only applies when the Drupal adapter and SDC settings are enabled. Generic projects should expect output to remain in dist/. See Platform Adapters.

Supported Project Shapes

Release-readiness coverage validates:

• Drupal SDC projects using src/components.
• Generic Twig projects using src/components.
• Root ./components projects.
• Projects using multiple variant.structureImplementations.
• Mixed Twig + React Storybook projects.

WordPress + Timber and Craft CMS are Twig-based project use cases that can use the generic adapter today. Dedicated adapters for those platforms are future opportunities. The implemented adapters in this package are currently generic and drupal.

Public Imports

Emulsify Core exposes stable public package paths:

import { renderTwig } from '@emulsify/core/storybook';
import { registerTwigExtensions } from '@emulsify/core/extensions/twig';
import { defineReactExtension } from '@emulsify/core/extensions/react';

defineReactExtension is reserved for future React extension support. It currently returns the input unchanged. Adopting the import path is safe; the runtime is intentionally a no-op until the registry lands. See Extension Points.

Vite consumers can import the shared config from @emulsify/core/vite and public Vite plugin helpers from @emulsify/core/vite/plugins.

Contributing

Maintained JavaScript source, config, scripts, and tests should use consistent comments:

• Start each maintained JS file with a short JSDoc file block that explains the file's responsibility.
• Use JSDoc blocks for exported functions, complex helpers, and public contracts.
• Use // comments for local intent, compatibility behavior, and non-obvious edge cases.
• Keep comments concise and factual. Prefer explaining why behavior exists instead of restating the code.
• Use YAML or shell comments in workflow, hook, and fixture files where the format supports comments.

Do not add comments to JSON files, lockfiles, binary assets, generated output, legal documents, or dependency files. Those formats either do not support comments or should remain exact artifacts.

Please also follow the issue template and pull request templates provided. See below for the correct places to post issues:

1. Emulsify Drupal
2. Emulsify Tools (Drupal module)

Links

• Emulsify Homepage
• Storybook Demo
• Code of Conduct

Author

Emulsify® is a product of Four Kitchens.