# @emulsify/core 中文文档

规范地址：https://npmcn.com/package/%40emulsify/core/

版本：4\.5\.2
npm 元数据更新时间：2026-11-04T16:25:35.129Z
中文译文更新时间：2026-11-13T16:37:52.506Z
软件包许可：GPL-2\.0

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40emulsify/core
原文对照：https://npmcn.com/package/%40emulsify/core/?lang=original
项目主页：https://github.com/emulsify-ds/emulsify-core#readme
源码仓库：https://github.com/emulsify-ds/emulsify-core

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：1.3 MB，140 个文件
- 模块格式：ES Module
- TypeScript 类型：未声明
- Node.js 要求：\>=24\.13\.0
- 运行依赖：42 个
- peer 依赖：react ^18\.0\.0 \|\| ^19\.0\.0，react-dom ^18\.0\.0 \|\| ^19\.0\.0
- 首次发布：2024-06-07T20:54:30.613Z
- 最新版本发布：2026-11-04T16:25:34.717Z
- 近 30 天下载量：5711（2026-10-14 至 2026-11-12，npm 官方下载统计）
- 已发布版本数：53（近 12 个月 18 个）

## 中文简介

装订用于故事本开发+Vite 构建的工具

## 安装

```sh
npm install @emulsify/core
```

也可以使用：`pnpm add @emulsify/core`、`yarn add @emulsify/core`、`bun add @emulsify/core`

## README

![Emulsify Core Design System](https://github.com/emulsify-ds/.github/blob/6bd435be881bd820bddfa05d88905efe29176a0a/assets/images/header.png)

# 浓缩核心

整个组成部分建筑设计系统的开源基础 图书馆、CMS主题、故事书以及设计和 发展.

**浓缩核心** 提供共享 [维特](https://vite.dev/) 构建配置 (单位:千美元) [故事书](https://storybook.js.org/) 组件驱动的工作空间 与 Twig 、 React 和 自主自定义元素一起开发.

## 如何浓缩核心工作

Emulsify Core是Emulsify项目的共享前端层. 它给团队 用于构建、记录和测试组件,同时离开特定平台 具体执行方式属于何处.

-   Vite 构建项目 JavaScript, Sass/CSS, Twig 模板, 组件元数据, 和静态组件资产.
-   故事书运行在React/Vite框架上.
-   Twig 文件通过基于 React 的 Story Book 渲染 `renderTwig()`。 。 。 .
-   反应组件通过Storybook的标准反应支持渲染.
-   在故事书中通过 `renderWebComponent()`。 。 。 .
-   Twig, React, 和自定义元素故事可以一起生活在一个故事书中 工作空间.
-   `project.emulsify.json` 是平台和结构的真相来源 配置 .
-   平台适配器控制CMS的特定行为而不是假设 在全球.

## 节点.js 运行时政策

-   消费者在"节点"(Node.js 24.13.0)或后期得到支持. 最严格的出版 工具链依赖, `stylelint-selector-bem-pattern` 5,需要补丁.
-   贡献者应使用节点24.18.0,准确的版本被钉入 `.nvmrc`。 。 。 .
-   释放准备情况调查在公众24.13.0层和建议的层上进行 24.1.8.0版本. 其他 CI 和发布任务从 `.nvmrc`。 。 。 .

## 项目演变

Emulsify Core最初是作为共享的Webpack和故事书工具而开始的,采用无害环境管理方法的 3.x,并改用"Vite and React"/"Vite Story Book"在4.x. 目前的项目 模型支持 CMS 主题,独立组件库,以及混合 Twig, 反应,和自定义元素"故事书"工作空间.

见 [版本进化](https://npmcn.com/package/%40emulsify/core/docs/version-evolution.md) 主要版本历史 编辑 [4.3.0 释放说明](https://npmcn.com/package/%40emulsify/core/docs/releases/4.3.0.md) 兼容性 修改和增加的版本.

这个 [兼容性和支助政策](https://npmcn.com/package/%40emulsify/core/docs/version-evolution.md#compatibility-and-support-policy) 将当前要求和现有的4.x兼容规则与 维护承诺。 待决决定生活在 [维护者登记册](https://npmcn.com/package/%40emulsify/core/docs/maintainer-decisions.md)。 。 。 .

## 作者模式

Emulsify Core 支持 Twig 和 React 作者工作流程加焦点 使用自定义元素所建的网络组件的故事书适配器. 这个 正确的选择取决于如何使用设计系统.

-   使用 Twig 用于 CMS 主题和服务器的模板系统. 德鲁帕尔有一个 Drupal 特定适配器, WordPress/ Timber 工程可以使用 故意中立 `wordpress` 适配器. WordPress 运行时集成 属于 `emulsify-wordpress-theme`。 。 。 .
-   对独立的UI库、应用程序组件或项目使用React 已经使用 React .
-   使用自定义元素构建的网页组件 符合适配器所记录的框架中性浏览器组件 属性、属性、默认位置和本地事件边界.
-   当设计系统需要记录 CMS 时使用混合写作, 框架和框架中立的组件 举个例子.

见 [组件撰写](https://npmcn.com/package/%40emulsify/core/docs/component-authoring.md) 用于 Twig, React,自定义 元素,混合故事书,以及共享 Sass 实例.

## 安装和工程设置

Emulsify Core可以通过两种共同的方式进入一个项目. 两者都得到支持,两者都得到支持 无效。 正确的设置路径取决于您是否将 Core 连接到 投影或从 Emulsify 启动器开始.

### 手动设置 与 npm 关系

要将 Emulsify Core 添加到一个已有的工程, 即自定义时使用 npm 启动器,或拥有自身设置决定的项目.

```sh
npm install @emulsify/core
```

每个项目都应提供 `project.emulsify.json` 在工程根处的文件 :

```json
{
  "project": {
    "platform": "none",
    "name": "example",
    "machineName": "example"
  },
  "assets": {
    "roots": ["./design/assets"]
  }
}
```

从默认资产根和任何额外的根中发现资产文件 配置于 `project.emulsify.json`项目存储时使用资产根 字体、图像、图标或其他默认位置外的静态文件.

常见的项目脚本将共享的 Emulsify Core Vite 和 故事本配置 :

-   `storybook`:开始故事书的开发.
-   `storybook-build`:构建静态故事书输出.
-   `build`:运行 JS, CSS 的 Vite 构建, 复制 Twig 模板, 组件 元数据和静态组件资产.
-   `lint`: lints 维护了项目源.

### 以乳化 CLI 精简设置

使用 [放大CLI](https://github.com/emulsify-ds/emulsify-cli) 当你 想要由启动器驱动的设置, 并带有项目脚手架、启动钩、 系统 安装和组件生成.

在全球安装CLI:

```sh
npm install -g @emulsify/cli
```

然后从启动器初始化一个项目 :

```sh
emulsify init "My Project" ./path/to/projects --platform none
```

全球或直接的 CLI 安装仍然是支持运行的方式 `emulsify init` 在项目存在之前。 对于核心4.x兼容性,项目 安装 `@emulsify/core` 还接受当地项目 `emulsify` 二进制 通过核心 `@emulsify/cli` 依赖性。 本地二进制可以用 `npx --no-install emulsify --help`; 它是现有兼容桥 核心消费者,而不是选择明确的CLI安装的替代品 当脚手架 一个新的项目.

CLI 支持内置 `drupal`, (中文(简体) ), `wordpress`,以及 `none` 平台。 它会 创建启动项目,安装组件系统,列出可用的组件, 安装系统组件,并生成本地组件。 启动者拥有 项目结构和脚本; Emulsify Core 仍然提供共享构建和 故事书基础下面.

## 文档

文件按任务分列:

| 专题 | 使用此选项时 |
| --- | --- |
| [版本进化](https://npmcn.com/package/%40emulsify/core/docs/version-evolution.md) | 了解Emulsy Core如何在主要释放中演变. |
| [组件撰写](https://npmcn.com/package/%40emulsify/core/docs/component-authoring.md) | 选择twig,React,自定义元素,或混合故事书编写和比较组件示例. |
| [故事书](https://npmcn.com/package/%40emulsify/core/docs/storybook.md) | 渲染出特维格和自定义元素故事,使用"故事书"帮助,并混合了编剧模型. |
| [项目结构和输出](https://npmcn.com/package/%40emulsify/core/docs/project-structure.md) | 配置 `src/components`词根 `./components`, (中文(简体) ), `variant.structureImplementations`,和预期输出路径. |
| [平台适配器](https://npmcn.com/package/%40emulsify/core/docs/platform-adapters.md) | 谅解 `none`, (中文(简体) ), `wordpress`, (中文(简体) ), `drupal`,平台解析令,以及Drupal SDC行为. |
| [扩展点](https://npmcn.com/package/%40emulsify/core/docs/extension-points.md) | 添加 Vite 插件, Tailwind CSS, Storybook 预览功能,以及其他框架工具. |
| [扶养合同](https://npmcn.com/package/%40emulsify/core/docs/dependency-contract.md) | 理解为什么生成的主题依赖于 Core 运行时的依赖和 npm 升起 . |
| [业绩](https://npmcn.com/package/%40emulsify/core/docs/performance.md) | 了解源图,急切地Twig导入,Tailwind扫描,复制文件,以及固定验证. |
| [原生树枝扩展](https://npmcn.com/package/%40emulsify/core/docs/native-twig-extensions.md) | 使用 `bem()`, (中文(简体) ), `add_attributes()`,以及 `switch/case/default/endswitch` 在Twig.js (英语). |
| [构成部分检查员](https://npmcn.com/package/%40emulsify/core/docs/component-inspector.md) | 确认列名 Twig 组件模板,精确的引用,短手相撞,以及预期的输出路径. |
| [项目审计](https://npmcn.com/package/%40emulsify/core/docs/audit.md) | 运行人机或版本JSON项目审计并配置CI故障阈值. |
| [释放核查](https://npmcn.com/package/%40emulsify/core/docs/release.md) | 运行4.x放行检查,柏油丸烟检测,和语义放行干行后再发布. |
| [释放拉动请求审查](https://npmcn.com/package/%40emulsify/core/docs/release-review.md) | 审查独立的API的大型放出拉取请求,运行时间,消费者,可访问性和放出风险. |
| [迁移到 4.x](https://npmcn.com/package/%40emulsify/core/docs/migration-4x.md) | 在保留现有结构的同时,提升一个预-4.x/Webpack项目. |
| [4.3.0 发布说明](https://npmcn.com/package/%40emulsify/core/docs/releases/4.3.0.md) | 审查4.3.0范围、兼容性变化、公共API、限制和核查证据. |
| [4.3.1 发布说明](https://npmcn.com/package/%40emulsify/core/docs/releases/4.3.1.md) | 审查 4.3.1 开发记者的变化、动词控制以及范围限制. |
| [4.4.0 发布说明](https://npmcn.com/package/%40emulsify/core/docs/releases/4.4.0.md) | 审查资产分辨率、更安全的审计修正、增量产出、记者变动和公布证据. |

## 已知的限制

Emulsify Core有意专注于共享的建筑和故事书层. 一些集成工作仍然属于项目、启动器、主题或平台 软件包.

-   已执行的平台适配器为: `none`, (中文(简体) ), `wordpress`,以及 `drupal`编辑 `wordpress` 适配器是有意中性的: 它支持 Core Twig 编写, 故事书,维特, `bem()`, (中文(简体) ), `add_attributes()`, (中文(简体) ), `include()`,以及 `source()`不过 它不会模仿 WordPress 或 Timber PHP 运行时的行为 。 运行时间 集成属于 `emulsify-wordpress-theme`。见 [平台适配器](https://npmcn.com/package/%40emulsify/core/docs/platform-adapters.md)。 。 。 .
-   Storybook 急切地导入编译出用于同步渲染的 Twig 模块, 原始 Twig 和文本资产来源在 `source()` 请求 他们。 大块 Twig 图书馆仍应保留 Storybook 源代码 有意为之. 见 [业绩](https://npmcn.com/package/%40emulsify/core/docs/performance.md)。 。 。 .
-   项目扩展使用公众 `config/emulsify-core` 目录 : `config/emulsify-core/vite/plugins.*` 对于维特, `config/emulsify-core/storybook/...` 故事书 `config/emulsify-core/a11y.config.js` 为11y。 见 [扩展点](https://npmcn.com/package/%40emulsify/core/docs/extension-points.md)。 。 。 .
-   Webpack 特定定制必须手动迁移到 Vite 插件或 `extendConfig()`。见 [移徙](https://npmcn.com/package/%40emulsify/core/docs/migration-4x.md)。 。 。 .
-   Drupal SDC 镜像只在 Drupal 适配器和 SDC 设置时适用 启用 . `none` 财务报告和审定财务报表 `wordpress` 项目应预期产出将留在 `dist/`。见 [平台适配器](https://npmcn.com/package/%40emulsify/core/docs/platform-adapters.md)。 。 。 .
-   生成仅依赖于的主题 `@emulsify/core` 假设 npm 的平地 `node_modules` 为脚本二进制和共享配置套件而起. {\\fn黑体\\fs22\\bord1\\shad0\\3ahbe\\4ah00\\fscx67\\fscy66\\2chffffff\\3ch808080}嗯 不错 {\\fn黑体\\fs22\\bord1\\shad0\\3ahbe\\4ah00\\fscx67\\fscy66\\2chffffff\\3ch808080}嗯 孤立的链接器和 Yarn Plug'n'Play 不支持此单依赖性 生成主题模式,除非耗用项目宣布每个工具 软件包本身。 见 [扶养合同](https://npmcn.com/package/%40emulsify/core/docs/dependency-contract.md)。 。 。 .
-   用于自定义元素的故事手册渲染器支持自定义元素, 用于未命名的默认插槽的轻度 DOM 儿童, 并明确绘制本地地图 事件。 它不提供命名槽构成 API 或支持 定制内置元素. 见 [故事书](https://npmcn.com/package/%40emulsify/core/docs/storybook.md#known-limitations)。 。 。 .

## 支持的工程形状

Emulsify Core旨在满足项目所在位置. 这些项目形状 已支持:

-   利用 `src/components`。 。 。 .
-   `none` 平台 使用 `src/components`。 。 。 .
-   `wordpress` 平台 使用 `src/components`。 。 。 .
-   根号 `./components` 项目.
-   使用多个项目 `variant.structureImplementations`。 。 。 .
-   与Twig,React,以及自定义元素的混合故事书项目.

WordPress和木材项目应使用 `platform: "wordpress"` 当他们想要 核心的中性WordPress适配器. 适配器保持输出 `dist/`,负载 故事本 CSS 来自 `dist/**/*.css`,然后将 WordPress 运行时的行为留给 `emulsify-wordpress-theme`。 。 。 .

## 公共进口

浓缩核心暴露了稳定的公共软件包路径,因此不消耗项目 需要访问内部文件 :

```js
import { renderTwig } from '@emulsify/core/storybook';
import {
  defineCustomElement,
  renderWebComponent,
} from '@emulsify/core/storybook';
import { registerTwigExtensions } from '@emulsify/core/extensions/twig';
import { defineReactExtension } from '@emulsify/core/extensions/react';
```

`defineReactExtension` 用于未来的反应扩展支持。 这个 目前返回输入时没有改变。 采用导入路径是安全的 在登记之前,运行时间是故意不开放的。 见 [扩展点](https://npmcn.com/package/%40emulsify/core/docs/extension-points.md#public-imports)。 。 。 .

Vite 消费者可以从 `@emulsify/core/vite`公开 来自 Vite 插件助手 `@emulsify/core/vite/plugins`,和平台适配器 帮助者来自 `@emulsify/core/vite/platforms`。 。 。 .

`defineCustomElement()` 财务报告和审定财务报表 `renderWebComponent()` 使用现有的 `@emulsify/core/storybook` 切入点;不需要专用包 子路径。 生成的 Twig 资产源运行时间是内部的,不是 公共软件包导出 .

## 捐款

捐款应使下一个在其中工作的人的代码库保持清晰. 维护的 JavaScript 源、 配置、 脚本和测试应当使用一致 注释 :

-   以一个简短的JSDoc文件块启动每个维护的JS文件,以解释文件的责任.
-   使用 JSDoc 块进行输出功能、复杂的帮助者和公共合同.
-   使用 `//` 用于本地意图,相容行为,以及非明显边缘大小写的评论.
-   评论要简明扼要。 更倾向于解释为什么存在行为而不是重述代码.
-   在工作流程,钩子中使用YAML或 shell注释,在格式支持注释的地方使用固定文件.

不在 JSON 文件、 锁文件、 二进制资产、 生成输出中添加注释 , 法律文件或依赖文件。 这些格式也不支持 评论或应保留确切的文物.

还请遵循所提供的问题模板和拉动请求模板. 下面的问题链接是针对普通错误和特性请求的,而不是 机密弱点细节。 见 [安全报告情况](https://npmcn.com/package/%40emulsify/core/docs/maintainer-decisions.md#security-reporting-for-older-lines) 在编制安全报告之前.

1.  [乳化德鲁帕尔](https://github.com/emulsify-ds/emulsify-drupal/issues)
2.  [乳化工具( Drupal 模块)](https://www.drupal.org/project/issues/emulsify_tools)

## 链接

-   [放大主页](https://www.emulsify.info/)
-   [故事书Demo](http://storybook.emulsify.info/)
-   [行为守则](https://github.com/emulsify-ds/emulsify-drupal/blob/master/CODE_OF_CONDUCT.md)

## 作者

Emulsify 是一个产品,由 [四个厨房](https://fourkitchens.com/)。 。 。 .

## 常见问题

### @emulsify/core 是什么？

装订用于故事本开发\+Vite 构建的工具

### 如何安装 @emulsify/core？

在项目目录运行 npm install @emulsify/core，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：react（^18\.0\.0 \|\| ^19\.0\.0）、react-dom（^18\.0\.0 \|\| ^19\.0\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。它还提供命令行工具 emulsify-audit、emulsify-audit-twig-stories、emulsify-inspect-components，可以用 npx emulsify-audit 直接运行。

### @emulsify/core 支持 TypeScript 吗？

该包的 package\.json 没有声明类型入口。需要类型提示时，可以在 npm 上查找社区维护的 @types/emulsify\_\_core 是否存在。

### @emulsify/core 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @emulsify/core 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=24\.13\.0。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @emulsify/core 可以商用吗？

@emulsify/core 使用 GPL-2\.0 许可。强 Copyleft：分发包含该代码的软件时，整个作品需以兼容的 GPL 许可开源。仅在内部使用、不对外分发时不触发此义务。以上为概括，不构成法律意见，请以许可原文为准。

### @emulsify/core 的下载量有多少？

根据 npm 官方下载统计，@emulsify/core 在 2026/10/14 – 2026/11/12 这 30 天内被下载 5,711 次，日均约 190 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @emulsify/core 还在维护吗？

最新版本 4\.5\.2 发布于 2026/11/05（9 天前）；至今共发布 53 个版本，其中过去 12 个月发布了 18 个；首次发布于 2024/06/08。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。