浓缩核心
整个组成部分建筑设计系统的开源基础 图书馆、CMS主题、故事书以及设计和 发展.
浓缩核心 提供共享 维特 构建配置 (单位:千美元) 故事书 组件驱动的工作空间 与 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-pattern5,需要补丁. - 贡献者应使用节点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, 反应,和自定义元素"故事书"工作空间.
见 版本进化 主要版本历史 编辑 4.3.0 释放说明 兼容性 修改和增加的版本.
这个 兼容性和支助政策 将当前要求和现有的4.x兼容规则与 维护承诺。 待决决定生活在 维护者登记册。 。 。 .
作者模式
Emulsify Core 支持 Twig 和 React 作者工作流程加焦点 使用自定义元素所建的网络组件的故事书适配器. 这个 正确的选择取决于如何使用设计系统.
- 使用 Twig 用于 CMS 主题和服务器的模板系统. 德鲁帕尔有一个
Drupal 特定适配器, WordPress/ Timber 工程可以使用
故意中立
wordpress适配器. WordPress 运行时集成 属于emulsify-wordpress-theme。 。 。 . - 对独立的UI库、应用程序组件或项目使用React 已经使用 React .
- 使用自定义元素构建的网页组件 符合适配器所记录的框架中性浏览器组件 属性、属性、默认位置和本地事件边界.
- 当设计系统需要记录 CMS 时使用混合写作, 框架和框架中立的组件 举个例子.
见 组件撰写 用于 Twig, React,自定义 元素,混合故事书,以及共享 Sass 实例.
安装和工程设置
Emulsify Core可以通过两种共同的方式进入一个项目. 两者都得到支持,两者都得到支持 无效。 正确的设置路径取决于您是否将 Core 连接到 投影或从 Emulsify 启动器开始.
手动设置 与 npm 关系
要将 Emulsify Core 添加到一个已有的工程, 即自定义时使用 npm 启动器,或拥有自身设置决定的项目.
npm install @emulsify/core
每个项目都应提供 project.emulsify.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 当你 想要由启动器驱动的设置, 并带有项目脚手架、启动钩、 系统 安装和组件生成.
在全球安装CLI:
npm install -g @emulsify/cli
然后从启动器初始化一个项目 :
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 仍然提供共享构建和
故事书基础下面.
文档
文件按任务分列:
| 专题 | 使用此选项时 |
|---|---|
| 版本进化 | 了解Emulsy Core如何在主要释放中演变. |
| 组件撰写 | 选择twig,React,自定义元素,或混合故事书编写和比较组件示例. |
| 故事书 | 渲染出特维格和自定义元素故事,使用"故事书"帮助,并混合了编剧模型. |
| 项目结构和输出 | 配置 src/components词根 ./components, (中文(简体) ), variant.structureImplementations,和预期输出路径. |
| 平台适配器 | 谅解 none, (中文(简体) ), wordpress, (中文(简体) ), drupal,平台解析令,以及Drupal SDC行为. |
| 扩展点 | 添加 Vite 插件, Tailwind CSS, Storybook 预览功能,以及其他框架工具. |
| 扶养合同 | 理解为什么生成的主题依赖于 Core 运行时的依赖和 npm 升起 . |
| 业绩 | 了解源图,急切地Twig导入,Tailwind扫描,复制文件,以及固定验证. |
| 原生树枝扩展 | 使用 bem(), (中文(简体) ), add_attributes(),以及 switch/case/default/endswitch 在Twig.js (英语). |
| 构成部分检查员 | 确认列名 Twig 组件模板,精确的引用,短手相撞,以及预期的输出路径. |
| 项目审计 | 运行人机或版本JSON项目审计并配置CI故障阈值. |
| 释放核查 | 运行4.x放行检查,柏油丸烟检测,和语义放行干行后再发布. |
| 释放拉动请求审查 | 审查独立的API的大型放出拉取请求,运行时间,消费者,可访问性和放出风险. |
| 迁移到 4.x | 在保留现有结构的同时,提升一个预-4.x/Webpack项目. |
| 4.3.0 发布说明 | 审查4.3.0范围、兼容性变化、公共API、限制和核查证据. |
| 4.3.1 发布说明 | 审查 4.3.1 开发记者的变化、动词控制以及范围限制. |
| 4.4.0 发布说明 | 审查资产分辨率、更安全的审计修正、增量产出、记者变动和公布证据. |
已知的限制
Emulsify Core有意专注于共享的建筑和故事书层. 一些集成工作仍然属于项目、启动器、主题或平台 软件包.
- 已执行的平台适配器为:
none, (中文(简体) ),wordpress,以及drupal编辑wordpress适配器是有意中性的: 它支持 Core Twig 编写, 故事书,维特,bem(), (中文(简体) ),add_attributes(), (中文(简体) ),include(),以及source()不过 它不会模仿 WordPress 或 Timber PHP 运行时的行为 。 运行时间 集成属于emulsify-wordpress-theme。见 平台适配器。 。 。 . - Storybook 急切地导入编译出用于同步渲染的 Twig 模块,
原始 Twig 和文本资产来源在
source()请求 他们。 大块 Twig 图书馆仍应保留 Storybook 源代码 有意为之. 见 业绩。 。 。 . - 项目扩展使用公众
config/emulsify-core目录 :config/emulsify-core/vite/plugins.*对于维特,config/emulsify-core/storybook/...故事书config/emulsify-core/a11y.config.js为11y。 见 扩展点。 。 。 . - Webpack 特定定制必须手动迁移到 Vite 插件或
extendConfig()。见 移徙。 。 。 . - Drupal SDC 镜像只在 Drupal 适配器和 SDC 设置时适用
启用 .
none财务报告和审定财务报表wordpress项目应预期产出将留在dist/。见 平台适配器。 。 。 . - 生成仅依赖于的主题
@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 不支持此单依赖性 生成主题模式,除非耗用项目宣布每个工具 软件包本身。 见 扶养合同。 。 。 . - 用于自定义元素的故事手册渲染器支持自定义元素, 用于未命名的默认插槽的轻度 DOM 儿童, 并明确绘制本地地图 事件。 它不提供命名槽构成 API 或支持 定制内置元素. 见 故事书。 。 。 .
支持的工程形状
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。 。 。 .
公共进口
浓缩核心暴露了稳定的公共软件包路径,因此不消耗项目 需要访问内部文件 :
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 用于未来的反应扩展支持。 这个
目前返回输入时没有改变。 采用导入路径是安全的
在登记之前,运行时间是故意不开放的。 见
扩展点。 。 。 .
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 文件、 锁文件、 二进制资产、 生成输出中添加注释 , 法律文件或依赖文件。 这些格式也不支持 评论或应保留确切的文物.
还请遵循所提供的问题模板和拉动请求模板. 下面的问题链接是针对普通错误和特性请求的,而不是 机密弱点细节。 见 安全报告情况 在编制安全报告之前.
链接
作者
Emulsify 是一个产品,由 四个厨房。 。 。 .