https://github.com/emulsify-ds/emulsify-drupal
Drupal theme built with Storybook and Webpack
https://github.com/emulsify-ds/emulsify-drupal
Last synced: 21 days ago
JSON representation
Drupal theme built with Storybook and Webpack
- Host: GitHub
- URL: https://github.com/emulsify-ds/emulsify-drupal
- Owner: emulsify-ds
- License: gpl-3.0
- Created: 2019-06-17T16:34:25.000Z (about 7 years ago)
- Default Branch: main
- Last Pushed: 2026-05-25T20:10:11.000Z (about 1 month ago)
- Last Synced: 2026-05-25T21:29:23.503Z (about 1 month ago)
- Language: PHP
- Homepage:
- Size: 9.18 MB
- Stars: 96
- Watchers: 19
- Forks: 43
- Open Issues: 10
-
Metadata Files:
- Readme: README.md
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
Awesome Lists containing this project
- component-based-theming - Emulsify Drupal
README
# Emulsify Drupal
## Emulsify is an open-source toolset for creating and implementing design systems on your website
### Storybook, Emulsify Core 4, and a Vite-based build workflow for Drupal 11.3+
**Emulsify Drupal** provides a [Storybook](https://storybook.js.org/) component library, Emulsify Core 4 tooling, and a [Vite](https://vite.dev/)-based build workflow for Drupal 11.3+ with Drupal 12 forward compatibility. Until Drupal 12 beta or stable recommended-project releases are available, Drupal core development branch coverage is experimental.
The current 7.x series no longer depends on `stable9`; Emulsify now ships its own complete template layer instead of inheriting one from a Drupal parent theme.
## Documentation
[docs.emulsify.info](https://emulsify.info/docs)
### Quick Links
1. [Installation](https://www.emulsify.info/docs/emulsify-drupal)
2. [Usage](https://www.emulsify.info/docs/emulsify-drupal/basic-usage/commands)
3. [Upgrade guide](./UPGRADE.md)
4. [Template override map](./docs/template-map.md)
5. [Favicon generation lifecycle](./docs/favicon-generation.md)
## Demo
1. [Storybook](http://storybook.emulsify.info/)
## How To
### Generate a child theme
If `emulsify_tools` is installed, you can generate a child theme with the helper-module Drush command:
```bash
drush emulsify my_theme
```
The helper module also exposes the fully qualified command name:
```bash
drush emulsify_tools:bake my_theme
```
You can also generate the same child theme with Drupal core's standard Starterkit command from the root of your Drupal site:
```bash
php web/core/scripts/drupal generate-theme my_theme --starterkit whisk --path themes/custom
```
These generation methods should be treated as equivalent:
1. They generate the theme into `web/themes/custom/my_theme`.
2. They use the `whisk` starter source.
3. They keep `emulsify` as the runtime parent theme for the generated theme.
After generation:
1. Enable the theme:
```bash
drush theme:enable my_theme -y
drush config:set system.theme default my_theme -y
drush cr -y
```
2. Install the generated theme's frontend dependencies:
```bash
cd web/themes/custom/my_theme
npm install
```
3. Start the generated theme's local tooling:
```bash
npm run develop
```
Do not enable `whisk` directly. It is a generation-only starter source.
### Manage generated favicon packages
The generated favicon workflow is built around one portable SVG source stored in theme settings.
Emulsify Drupal owns the theme-facing parts of that workflow: the theme settings form, config defaults and schema, admin previews, frontend head tags, generated asset references in `.settings`, and sanitized SVG storage for config portability.
1. Configure the package in the theme settings form for `emulsify` or an Emulsify child theme.
2. Save the theme settings form to generate or update the package during normal admin changes.
3. Review package and portable-source diagnostics in the theme settings UI.
Emulsify Tools owns deployment-oriented Drush operations for those same
settings. After configuration import or deploy, use the Emulsify Tools favicon
commands to generate, inspect, or reset environment-local package files before
public traffic reaches the environment. See the Emulsify Tools README for the
full command documentation.
Runtime page requests never generate favicon files. If the configured package is missing, Emulsify skips favicon head tags until the theme settings form or the Emulsify Tools generate command creates the package.
Generated favicon packages require the PHP `gd` extension and the `Imagick` extension for SVG rasterization. If either extension is unavailable, the uploaded SVG can still be stored in configuration, but PNG and ICO package generation will fail until those extensions are installed.
The theme settings UI surfaces the current portable-source and package status. Portable SVG copies larger than 256 KB are flagged because very large config payloads are awkward to review and deploy.
See [docs/favicon-generation.md](./docs/favicon-generation.md) for generated files, package location, generator limits, and deployment expectations.
## Contributing
### [Code of Conduct](https://github.com/emulsify-ds/emulsify-drupal/blob/main/CODE_OF_CONDUCT.md)
The project maintainers have adopted a Code of Conduct that we expect project participants to adhere to. Please read the full text so that you can understand what actions will and will not be tolerated.
### Contribution Guide
Please also follow the issue template and pull request templates provided. See below for the correct places to post issues:
1. [Emulsify Drupal](https://www.drupal.org/project/issues/emulsify?categories=All)
2. [Emulsify Tools Drupal Module](https://www.drupal.org/project/issues/emulsify_tools?categories=All)
3. [Emulsify Twig Extensions](https://github.com/emulsify-ds/emulsify-twig-extensions/issues)
### Committing Changes
To facilitate automatic semantic release versioning, we utilize the [Conventional Changelog](https://github.com/conventional-changelog/conventional-changelog) standard through Commitizen. Follow these steps when commiting your work to ensure semantic release can version correctly.
1. Stage your changes, ensuring they encompass exactly what you wish to change, no more.
2. Create a [Conventional Commit](https://www.conventionalcommits.org/en/v1.0.0/) message, either manually or with your preferred commit helper.
3. Your commit message will be used to create the changelog for the next version that includes that commit.
### Release Readiness
Run the release guard before merging packaging, starterkit, favicon settings, or release metadata changes, and before preparing a 7.x release:
```bash
npm run release:check
```
Use `npm run release:check -- --skip-smoke` when you only want the static metadata, README, duplicate-script, and schema checks. The static checks verify that favicon settings stay aligned across `FaviconSettings::DEFAULTS`, `config/install/emulsify.settings.yml`, and `config/schema/emulsify.schema.yml`.
## Author
Emulsify® is a product of [Four Kitchens — We make BIG websites](https://fourkitchens.com).
## Contributors
Brian Lewis
💻 📖
Randy Oest
💻 📖
Callin Mullaney
💻 📖
Patrick Coffey
💻 📖
Luke Herrington
💻 📖
Aaron Couch
💻 📖
Marc Berger
💻 📖
James Todd
💻 📖
Kurt Trowbridge
💻 📖
Chris Martin
💻 📖
Adam Erickson
💻 📖
Chris Runo
💻 📖
Andy Carlberg
💻 📖
eatsmarter-benny
💻 📖
Brian Perry
💻 📖
Israel Shmueli
💻 📖
John Karahalis
💻 📖
Mihaic100
💻 📖
Paul Sebborn
💻 📖
This project follows the [all-contributors](https://github.com/all-contributors/all-contributors) specification. Contributions of any kind welcome!