This skill is used to ensure that all Node packages in the monorepo follow unified configuration specifications. It is applicable to scenarios such as creating new packages, modifying existing package configurations, and reviewing package compliance.
Use cases
- Create a brand-new subpackage in the monorepo
- Review whether the existing package's
package.jsoncomplies with the specification - Modify the package's build configuration (tsup, tsconfig)
- Check whether workspace dependency declarations are correct
- Ensure consistency of publishing configuration
Validation process
When performing package validation, check according to the following steps:
Task Progress:
- [ ] Step 1: 确认包类型(发布包/私有包)
- [ ] Step 2: 校验 package.json 必填字段
- [ ] Step 3: 校验字段排序
- [ ] Step 4: 校验统一字段值(author/bugs/repo/publishConfig/files)
- [ ] Step 5: 校验 exports 和构建入口一致性
- [ ] Step 6: 校验 tsup.config.ts 配置
- [ ] Step 7: 校验 tsconfig.json 继承
- [ ] Step 8: 校验目录结构
- [ ] Step 9: 确认根 package.json 已声明工作区引用
Package type determination
Determine the type according to the directory where the package is located:
| Directory | Type | Naming format | private |
|---|---|---|---|
packages/* |
Core publishing package | @ruan-cat/<name> |
false |
configs-package/* |
Configuration package | @ruan-cat/<tool>-config |
false |
vite-plugins/* |
Vite plugin package | @ruan-cat/vite-plugin-<name> |
false |
demos/* |
Example application | Short name without namespace | true |
tests/* |
Test package | @test/<name> |
true |
docs/*、fork/*、learn-create-compoents-lib/* |
Auxiliary workspace | No fixed format | true |
New packages should usually only be created in the
packages/*、configs-package/*、vite-plugins/*three publishing workspaces.demos/*andtests/*are used for testing purposes. Other auxiliary workspaces are not used to create regular new packages.
package.json specification
Field ordering (publishing packages)
Arrange strictly in the following order:
nameversiondescriptiontypemaintypeshomepagebugsrepositorybin(CLI package)scriptsexportskeywordsauthorlicensepublishConfigfilesdependenciesdevDependenciespeerDependenciespeerDependenciesMeta
Required fields (publishing packages)
{
"name": "@ruan-cat/<package-name>",
"version": "0.1.0",
"description": "简体中文描述",
"type": "module",
"main": "./src/index.ts", // 纯 ESM 库包指向源码(见下方决策指南)
"types": "./src/index.ts", // 纯 ESM 库包指向源码(见下方决策指南)
"homepage": "https://github.com/ruan-cat/monorepo/tree/main/<workspace-dir>/<package-name>",
"bugs": {
"url": "https://github.com/ruan-cat/monorepo/issues",
},
"repository": {
"type": "git",
"url": "git+https://github.com/ruan-cat/monorepo.git",
"directory": "<workspace-dir>/<package-name>",
},
"scripts": {
"build": "tsup",
"prebuild": "automd",
},
"exports": {
".": {
"types": "./dist/index.d.ts",
"import": "./dist/index.js",
},
},
"keywords": ["至少一个关键词"],
"author": {
"name": "ruan-cat",
"email": "1219043956@qq.com",
"url": "https://github.com/ruan-cat",
},
"license": "MIT",
"publishConfig": {
"access": "public",
"registry": "https://registry.npmjs.org/",
"tag": "beta",
},
"files": [
"!**/.vercel/**",
"!**/.vitepress/**",
"src",
"dist/**",
"tsconfig.json",
"README.md",
"!src/**/docs/**",
"!src/**/tests/**",
"!*.test.*",
"!src/**/*.md",
],
}
Unified field values
The following fields remain consistent across all publishing packages,customization is not allowed:
author:
{ "name": "ruan-cat", "email": "1219043956@qq.com", "url": "https://github.com/ruan-cat" }
bugs:
{ "url": "https://github.com/ruan-cat/monorepo/issues" }
publishConfig:
{ "access": "public", "registry": "https://registry.npmjs.org/", "tag": "beta" }
license:"MIT"
type:"module"
main/types target decision guide
main and types fields can point to source code or build artifacts, depending on the package type:
Point to source code(./src/index.ts) — suitable for pure ESM library packages, where consumers are all inside the monorepo or use a bundler:
@ruan-cat/utils、@ruan-cat/release-toolkit、@ruan-cat/domains、@ruan-cat/generate-code-workspace
Point to dist(./dist/index.js + ./dist/index.d.ts) — suitable for the following scenarios:
- Packages with CJS output:
./dist/index.cjs+./dist/index.d.cts(such as commitlint-config, claude-notifier) - CLI tool packages: consumers directly use the build artifacts (such as vercel-deploy-tool)
- Vite plugin packages: do not expose source code (such as vite-plugin-ts-alias)
Default recommendation for new packages: if unsure,point to source code. Change to dist later when needed.
Two homepage modes
Custom subdomain(when the package has an independent documentation site):
https://utils.ruancat6312.tophttps://ccntf.ruan-cat.com
GitHub link(when there is no independent site):
https://github.com/ruan-cat/monorepo/tree/main/<workspace-dir>/<package-name>
repository.directory rules
directory The value must match the package's actual relative path in the monorepo:
packages/utils→"directory": "packages/utils"configs-package/commitlint-config→"directory": "configs-package/commitlint-config"vite-plugins/vite-plugin-ts-alias→"directory": "vite-plugins/vite-plugin-ts-alias"
files field variants
Basic mode(most packages):
[
"!**/.vercel/**",
"!**/.vitepress/**",
"src",
"dist/**",
"tsconfig.json",
"README.md",
"!src/**/docs/**",
"!src/**/tests/**",
"!*.test.*",
"!src/**/*.md"
]
Includes template files(CLI configuration tool packages, such as commitlint-config, taze-config, claude-notifier):
[
"!**/.vercel/**",
"!**/.vitepress/**",
"src",
"dist/**",
"tsconfig.json",
"README.md",
"!src/**/docs/**",
"!src/**/tests/**",
"!*.test.*",
"!src/**/*.md",
"templates/**"
]
Pure build artifacts(Vite plugin packages, excluding src):
[
"!**/.vercel/**",
"!**/.vitepress/**",
"dist/**",
"tsconfig.json",
"README.md",
"!src/**/docs/**",
"!src/**/tests/**",
"!*.test.*",
"!src/**/*.md"
]
VuePress packages(additionally exclude VuePress cache and build directories):
[
"!**/.vercel/**",
"!**/.vitepress/**",
"src",
"dist/**",
"tsconfig.json",
"README.md",
"!src/**/docs/**",
"!src/**/tests/**",
"!*.test.*",
"!src/**/*.md",
"!**/.vuepress/cache",
"!**/.vuepress/dist"
]
Workspace dependencies
Internal package references uniformly use the workspace:^ protocol:
{
"dependencies": { "@ruan-cat/utils": "workspace:^" },
"devDependencies": { "@ruan-cat/vitepress-preset-config": "workspace:^" }
}
exports field specification
In conditional exports, types is always placed first(the resolution order officially recommended by TypeScript, ensuring correct type matching).
Note: in the exports of some legacy packages,
typesis not placed first; this is a historical leftover to be fixed, and new packages must follow this rule.
Main entry (ESM only):
{ ".": { "types": "./dist/index.d.ts", "import": "./dist/index.js" } }
Main entry (ESM only, source export):
{ ".": { "types": "./src/index.ts", "import": "./src/index.ts" } }
Main entry (ESM + CJS):
{ ".": { "types": "./dist/index.d.ts", "import": "./dist/index.js", "require": "./dist/index.cjs" } }
Main entry (CJS only, used by config packages):
{ ".": { "types": "./dist/index.d.cts", "require": "./dist/index.cjs", "default": "./dist/index.cjs" } }
Subpath exports:
{ "./config": { "types": "./src/config.mts", "import": "./dist/config.mjs" } }
Source and build artifact access (optional, add as needed):
{ "./src/*": "./src/*", "./dist/*": "./dist/*" }
bin field (CLI packages)
The file extension pointed to by bin must match tsup's format configuration:
format: ["cjs"]→.cjsformat: ["esm"]→.js
CLI packages (CJS format, such as commitlint-config, claude-notifier):
{ "bin": { "@ruan-cat/<package-name>": "./dist/cli.cjs" } }
CLI packages (ESM format, such as taze-config):
{ "bin": { "@ruan-cat/<package-name>": "./dist/cli.js" } }
CLI tool packages (support shorthand aliases, such as vercel-deploy-tool):
{
"bin": {
"<short-name>": "./dist/cli.js",
"@ruan-cat/<package-name>": "./dist/cli.js"
}
}
scripts naming convention
| Script name | Purpose | Example |
|---|---|---|
build |
Build | tsup |
prebuild |
Pre-build processing | automd |
dev |
Development mode | tsup --watch |
test |
Run tests | vitest run |
test:watch |
Watch tests | vitest |
test:cli |
CLI tests | node dist/cli.cjs init |
docs:dev |
Documentation development | vitepress dev src/docs --port 8080 |
build:docs |
Documentation build | vitepress build src/docs |
Required devDependencies
For published packages built with tsup, the following development dependencies should be declared in the package'slocal devDependencies (do not rely solely on hoisting from the root package):
{
"devDependencies": {
"automd": "^0.4.3",
"tsup": "^8.5.0",
"typescript": "^5.9.3"
}
}
tsup: build tool, required by thebuildscript (must be declared locally)automd: automatic documentation generation, required by theprebuildscript (must be declared locally)typescript: type checking (optional; many packages rely on typescript hoisted from the root package, and it can be omitted if a specific version is not needed)
If the package has a documentation site, also add:
{
"devDependencies": {
"vitepress": "^1.6.4",
"@ruan-cat/vitepress-preset-config": "workspace:^"
}
}
Minimal fields for private packages (demo/test)
{
"name": "<name>",
"private": true,
"version": "0.0.0",
"type": "module",
"scripts": { "dev": "vite", "build": "vite build" },
"devDependencies": {}
}
tsup.config.ts specification
Basic template (ESM single entry)
import { defineConfig } from "tsup";
export default defineConfig({
entry: ["./src/index.ts"],
outDir: "dist",
format: ["esm"],
clean: true,
dts: true,
sourcemap: true,
});
Common configuration options
| Option | Default value | Description |
|---|---|---|
entry |
Required | Entry file array |
outDir |
"dist" |
Output directory, uniformly dist |
format |
Required | ["esm"] or ["esm", "cjs"] or ["cjs"] |
clean |
true |
Clean before build |
dts |
true |
Generate type declarations |
sourcemap |
true |
Generate sourcemap |
splitting |
false |
Code splitting (recommended to disable with multiple entries) |
shims |
- | Node.js environment shims (used by Node-specific packages) |
target |
- | Target environment (such as "node18") |
Configuration mode selection
Creating a new package? → use the "ESM single entry" template
Need CJS compatibility? → set format: ["esm", "cjs"]
Have a CLI entry? → add entry: ["./src/index.ts", "./src/cli.ts"], set splitting: false
Node.js-specific package? → add shims: true and target: "node18"
Vite plugin? → Add external: ["vite"] and skipNodeModulesBundle: true
entry and exports correspondence
tsup's entry each entry file in the array must have a corresponding export path in package.json 's exports exports.
Example correspondence:
entry: ["./src/index.ts"]→".": { "import": "./dist/index.js" }entry: ["./src/cli.ts"]→binfield points to./dist/cli.js(ESM) or./dist/cli.cjs(CJS), depending onformatentry: ["./src/plugins/foo.ts"]→"./plugins/foo": { "import": "./dist/plugins/foo.js" }
tsconfig.json spec
standard inheritance mode
{
"extends": "../../tsconfig.base.json",
"compilerOptions": {
"rootDir": "./src"
}
}
Root directory tsconfig.base.json is preset:composite、incremental、declaration、declarationMap、emitDeclarationOnly、strict、target: "ESNext"、module: "ESNext"、moduleResolution: "node"、allowImportingTsExtensions: true、allowJs: true。
standalone config mode
Some complex packages (such as @ruan-cat/utils) can use standalone configs, but must keep core options consistent with tsconfig.base.json .
Directory structure spec
standard package directory
<workspace-dir>/<package-name>/
├── src/ # 源代码(必需)
│ ├── index.ts # 主入口
│ ├── cli.ts # CLI 入口(如有)
│ ├── tests/ # 测试(可选,放 src 内)
│ └── docs/ # 文档站点(可选,如 claude-notifier、vercel-deploy-tool)
├── tests/ # 测试(可选,放根目录)
├── docs/ # 文档站点(可选,如 domains 放在根目录)
├── dist/ # 构建输出(.gitignore)
├── templates/ # 模板文件(CLI 配置工具包)
├── package.json # 必需
├── tsconfig.json # 必需
├── tsup.config.ts # 使用 tsup 构建时必需
└── README.md # 必需
Documentation sites have two locations:src/docs/(recommended, such as claude-notifier) or docs/(such as domains), and the corresponding scripts paths also differ:
src/docs/→"docs:dev": "vitepress dev src/docs --port 8080"docs/→"docs:dev": "vitepress dev docs"
Root package.json sync
After creating a new publishable package,mustin the root package.json 's devDependencies add a reference:
{
"devDependencies": {
"@ruan-cat/<new-package>": "workspace:^"
}
}
Complete process for creating a new package
- Create the package directory in an appropriate workspace directory
- Create
package.json(fill in all required fields according to the above spec) - Create
tsconfig.json(inherittsconfig.base.json) - Create
tsup.config.ts(choose an appropriate config mode) - Create
src/index.tsmain entry file - Create
README.md - In the root
package.json'sdevDependenciesaddworkspace:^reference - Run
pnpm installlink workspace packages - Run
pnpm buildvalidate the build