SuperAPI AI Directory

package-linter

General & other

View repository

Updated 10-16 08:10

About this skill

Package Linter - Monorepo package specification validation

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.json complies 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/* and tests/* 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:

  1. name
  2. version
  3. description
  4. type
  5. main
  6. types
  7. homepage
  8. bugs
  9. repository
  10. bin(CLI package)
  11. scripts
  12. exports
  13. keywords
  14. author
  15. license
  16. publishConfig
  17. files
  18. dependencies
  19. devDependencies
  20. peerDependencies
  21. peerDependenciesMeta

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.top
  • https://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, types is 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"] → .cjs
  • format: ["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 thebuild script (must be declared locally)
  • automd: automatic documentation generation, required by theprebuild script (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"] → bin field points to ./dist/cli.js(ESM) or ./dist/cli.cjs(CJS), depending on format
  • entry: ["./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

  1. Create the package directory in an appropriate workspace directory
  2. Create package.json(fill in all required fields according to the above spec)
  3. Create tsconfig.json(inherit tsconfig.base.json)
  4. Create tsup.config.ts(choose an appropriate config mode)
  5. Create src/index.ts main entry file
  6. Create README.md
  7. In the root package.json 's devDependencies add workspace:^ reference
  8. Run pnpm install link workspace packages
  9. Run pnpm build validate the build