1
 2
 3
 4
 5
 6
 7
 8
 9
10

// ✅ 推荐写法：types 在最前
{
  "exports": {
    ".": {
      "types": "./dist/index.d.ts",
      "import": "./dist/index.js",
      "require": "./dist/index.cjs"
    }
  }
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13

{
  "exports": {
    ".": {
      "types": "./dist/index.d.ts",
      "default": "./dist/index.js"
    },
    "./utils": {
      "types": "./dist/utils/index.d.ts",
      "default": "./dist/utils/index.js"
    },
    "./package.json": "./package.json"    // ✅ 允许读取，很多工具需要
  }
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12

// tsconfig.json（ESM）
{
  "compilerOptions": {
    "module": "nodenext",
    "moduleResolution": "nodenext",
    "outDir": "./dist/esm",
    "declaration": true,
    "declarationDir": "./dist/types",
    "rootDir": "./src"
  },
  "include": ["src"]
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

// tsconfig.cjs.json（CJS）
{
  "extends": "./tsconfig.json",
  "compilerOptions": {
    "module": "commonjs",
    "moduleResolution": "nodenext",
    "outDir": "./dist/cjs",
    "declaration": false          // 声明只产一份
  }
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13

// package.json
{
  "type": "module",
  "main": "./dist/cjs/index.js",
  "types": "./dist/types/index.d.ts",
  "exports": {
    ".": {
      "types": "./dist/types/index.d.ts",
      "import": "./dist/esm/index.js",
      "require": "./dist/cjs/index.js"
    }
  }
}

1
2

// dist/cjs/package.json ——构建脚本生成
{ "type": "commonjs" }

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

// tsup.config.ts
import { defineConfig } from "tsup";

export default defineConfig({
  entry: ["src/index.ts"],
  format: ["esm", "cjs"],
  dts: true,              // 生成声明
  clean: true,
  sourcemap: true,
});

1
2
3
4
5
6
7

// 🛑 报错：没有显式返回类型
export function publicApi(x: number) { return x * 2; }
//                 ~~~~~~~~~ error TS9007: Function must have an explicit return
//                           type annotation with --isolatedDeclarations.

export const arrow = (x: number) => x + 1;
//           ~~~~~ error TS9007

1
2
3

// ✅ 补上显式类型即可
export function publicApi(x: number): number { return x * 2; }
export const arrow = (x: number): number => x + 1;

1
2
3
4
5
6

{
  "compilerOptions": {
    "declaration": true,
    "isolatedDeclarations": true
  }
}

1
2
3
4

// src/index.ts
interface InternalOptions { retries: number; timeout: number }   // 没有 export

export function createClient(opts: InternalOptions): Client { /* ... */ }

1
2
3
4
5
6
7
8

// 生成的 index.d.ts
interface InternalOptions {          // ⚠️ 被带出来了
  retries: number;
  timeout: number;
}
declare function createClient(opts: InternalOptions): Client;
export { createClient };
// ⚠️ InternalOptions 出现在公开 API 上，但使用者无法导入它

1
2
3

// ✅ 显式导出，或给公开 API 用公开类型
export interface ClientOptions { retries: number; timeout: number }
export function createClient(opts: ClientOptions): Client { /* ... */ }

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14

// api-extractor.json
{
  "$schema": "https://developer.microsoft.com/json-schemas/api-extractor/v7/api-extractor.schema.json",
  "mainEntryPointFilePath": "<projectFolder>/dist/types/index.d.ts",
  "apiReport": {
    "enabled": true,
    "reportFolder": "<projectFolder>/etc/"
  },
  "docModel": { "enabled": true },
  "dtsRollup": {
    "enabled": true,
    "untrimmedFilePath": "<projectFolder>/dist/index.d.ts"
  }
}

1
2

npx api-extractor run --local        # 生成/对比 API 报告
npx api-extractor run                # CI 中检查是否有未声明的变更

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14

/**
 * 稳定 API，遵循语义化版本。
 * @public
 */
export function stableApi(): void {}

/**
 * 可能变更，不保证兼容。
 * @beta
 */
export function experimentalApi(): void {}

/** @internal */
export function privateHelper(): void {}

1
2
3
4
5
6
7

# 发布前的标准检查流程
npm run build
npx tsc --noEmit
npx tsd
npx publint
npx @arethetypeswrong/cli --pack .
npm pack --dry-run          # 看看到底会发布哪些文件

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16

// test-d/index.test-d.ts
import { expectType, expectError, expectAssignable } from "tsd";
import { createClient, type Client } from "../src/index.js";

// ① 返回值类型精确
expectType<Client>(createClient({ retries: 3, timeout: 1000 }));

// ② 参数缺字段应当报错
expectError(createClient({ retries: 3 }));

// ③ 推断位置正确
const client = createClient({ retries: 3, timeout: 1000 });
expectType<Promise<string>>(client.get("/x"));

// ④ 泛型推断
expectType<{ a: number }>(pick({ a: 1, b: "x" }, ["a"] as const));

1

npx tsd          # CI 里跑