elements-new-package

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Creating a New Elements Package

创建新的Elements包

Use

scripts/new-package

to scaffold a new

@editframe/*

workspace package. It creates all required files and registers the package in

tsconfig.json

— the single source of truth for path aliases.

使用

scripts/new-package

来搭建一个新的

@editframe/*

工作区包。它会创建所有必需的文件，并在

tsconfig.json

中注册该包——这是路径别名的唯一可信来源。

Quick Start

快速开始

bash

undefined

bash

undefined

From the elements/ directory (or via the runner)

从elements/目录下执行（或通过运行器）

./scripts/new-package <name>

e.g. ./scripts/new-package captions

示例：./scripts/new-package captions

Then install to symlink the workspace package

然后安装以链接工作区包

./scripts/npm install

undefined

./scripts/npm install

undefined

What the Script Does

脚本功能说明

Creates

packages/<name>/

with:

```
src/index.ts
```
— empty export stub

package.json

— correct version, ESM exports,

publishConfig.access: "public"

```
tsconfig.json
```
— extends root config
```
tsdown.config.ts
```
— minimal build config

Inserts a path entry into

elements/tsconfig.json

json

"@editframe/<name>": ["./packages/<name>/src/index.ts"]

Both vitest configs (

vitest.config.ts

vitest.config.browser.ts

) derive their aliases from

tsconfig.json

automatically via

vitest.aliases.ts

— no manual updates needed there.

创建

packages/<name>/

目录，包含以下文件：

```
src/index.ts
```
—— 空导出占位文件
```
package.json
```
—— 正确的版本、ESM导出配置，
```
publishConfig.access: "public"
```
```
tsconfig.json
```
—— 继承根目录配置
```
tsdown.config.ts
```
—— 极简构建配置

在

elements/tsconfig.json

中插入路径条目：

json

"@editframe/<name>": ["./packages/<name>/src/index.ts"]

两个vitest配置文件（

vitest.config.ts

、

vitest.config.browser.ts

）会通过

vitest.aliases.ts

自动从

tsconfig.json

获取别名，无需手动更新。

Publishing a New Package to npm

将新包发布至npm

CI publishes via OIDC trusted publishing (no stored token). OIDC requires the package to exist on npm before trusted publishing can be configured, so the first publish is manual:

bash

undefined

CI通过OIDC可信发布机制进行发布（无需存储令牌）。OIDC要求包在npm上已存在才能配置可信发布，因此首次发布需要手动执行：

bash

undefined

One-time, run locally while logged in to npm

仅需一次，在本地登录npm后运行

npm publish --access public --workspace @editframe/<name>


After that first publish:
1. Go to npmjs.com → `@editframe/<name>` → Settings → Trusted Publisher
2. Add GitHub Actions: repo `editframe/elements`, workflow `release.yaml`, environment `npm-publish`

All subsequent releases publish automatically via CI.

npm publish --access public --workspace @editframe/<name>


首次发布完成后：
1. 访问npmjs.com → `@editframe/<name>` → 设置 → 可信发布者
2. 添加GitHub Actions：仓库`editframe/elements`，工作流`release.yaml`，环境`npm-publish`

后续所有版本发布将通过CI自动完成。

Path Alias Registration

路径别名注册

tsconfig.json

is the only file that needs a new entry. The script adds it automatically. Sub-path exports (e.g.

@editframe/foo/node

) must be added manually to

tsconfig.json

if needed — the base alias handles sub-path imports naturally via Vite prefix replacement, so explicit entries are only needed for files that don't follow the

src/<name>.ts

pattern.

仅需在

tsconfig.json

中添加新条目，脚本会自动完成此操作。如果需要子路径导出（如

@editframe/foo/node

），则必须手动在

tsconfig.json

中添加——基础别名会通过Vite前缀替换自然处理子路径导入，因此仅当文件不遵循

src/<name>.ts

模式时才需要显式添加条目。

Adding Dependencies on Other Workspace Packages

添加对其他工作区包的依赖

Add the sibling package to

dependencies

in the new package's

package.json

using the current workspace version (check the root

package.json

). Run

./scripts/npm install

to re-symlink. Run

./scripts/node scripts/deps.js update-dependencies

after a version bump to keep all cross-package pins in sync.

在新包的

package.json

的

dependencies

中添加同级包，并使用当前工作区版本（查看根目录

package.json

）。运行

./scripts/npm install

重新链接。版本更新后运行

./scripts/node scripts/deps.js update-dependencies

，以保持所有跨包依赖版本同步。