使用 Rollup、TypeScript、Nodemon 和 @microsoft/api-extractor 构建高效的 Node.js 开发环境

在现代 JavaScript/TypeScript 开发中，工具链的选择对开发效率和项目质量至关重要。结合 Rollup 、TypeScript 、Nodemon 和 @microsoft/api-extractor，可以构建一个高效且具备完整文档生成能力的开发环境。本文将详细介绍如何将这些工具结合起来，构建一个现代化的开发环境。

1. 项目初始化

首先，创建一个新的项目目录并初始化项目：

perl 复制代码

mkdir my-node-api-project
cd my-node-api-project
npm init -y

2. 安装开发依赖

我们将使用 Rollup 作为打包工具，TypeScript 作为开发语言，Nodemon 用于自动重启开发服务器，同时使用 @microsoft/api-extractor 来生成 TypeScript API 文档。首先，安装这些依赖：

sql 复制代码

npm install -D typescript rollup rollup-plugin-typescript2 @rollup/plugin-node-resolve @rollup/plugin-commonjs rollup-plugin-terser nodemon @microsoft/api-extractor

typescript：TypeScript 编译器。
rollup：JavaScript 模块打包工具。
rollup-plugin-typescript2：Rollup 插件，处理 TypeScript 文件。
@rollup/plugin-node-resolve：Rollup 插件，解析 Node.js 模块。
@rollup/plugin-commonjs：Rollup 插件，转换 CommonJS 模块。
rollup-plugin-terser：Rollup 插件，压缩 JavaScript 代码。
nodemon：监视文件变化，自动重启应用的工具。
@microsoft/api-extractor：用于提取和生成 TypeScript API 文档。

3. 配置 TypeScript

初始化 TypeScript 配置文件：

csharp 复制代码

npx tsc --init

修改 tsconfig.json 文件，确保 TypeScript 编译器按需配置：

json 复制代码

{
  "compilerOptions": {
    "target": "ES2020",           // 更高的目标版本
    "module": "ESNext",           // 输出为 ES 模块
    "strict": true,               // 启用严格模式
    "outDir": "./dist",           // 编译输出目录
    "skipLibCheck": true,         // 跳过库检查
    "moduleResolution": "node",   // Node.js 模块解析
    "declaration": true,          // 生成声明文件
    "declarationDir": "./dist",
    "esModuleInterop": true,      // 支持 CommonJS 和 ES 模块互操作
    "allowSyntheticDefaultImports": true,    
  },
  "include": ["src/**/*"]
}

这里特别启用了 declaration 和 declarationDir，这意味着 TypeScript 将会生成 .d.ts 类型声明文件，这对于 API 文档生成非常重要。

4. 配置 Rollup

创建 rollup.config.js 配置文件：

yaml 复制代码

{
    input: 'src/index.ts',
    output: [
      { file: 'dist/index.cjs.js', format: 'cjs', sourcemap: false, inlineDynamicImports: true },
      { file: 'dist/index.mjs.js', format: 'esm', sourcemap: false, inlineDynamicImports: true },
    ],
    plugins: [
      resolve(),
      commonjs(),
      typescript({
        tsconfig: './tsconfig.json',
        useTsconfigDeclarationDir: true,
      }),
    ]
  },

主要配置说明：

input：入口文件。
output：打包后输出的文件格式和位置。
plugins：使用 resolve 解析模块，commonjs 转换 CommonJS 模块，typescript 处理 TypeScript 文件，terser 用于代码压缩。

5. 配置 API Extractor

@microsoft/api-extractor 是微软的一个工具，用于提取 TypeScript 项目的 API 信息，并生成 API 文档。创建一个 api-extractor.json 配置文件：

json 复制代码

{
  "extends": "./node_modules/@microsoft/api-extractor/share/api-extractor-base.json",
  "mainEntryPointFilePath": "<project-folder>/dist/index.d.ts",
  "dtsRollup": {
    "generateDeclarations": true,
    "suppressSomeErrors": true
  },
  "docModel": {
    "enabled": true
  }
}

主要配置说明：

mainEntryPointFilePath：指定生成文档的入口文件。
dtsRollup：生成 .d.ts 文件。
docModel：启用 API 文档模型生成。

7. 添加脚本到 `package.json`

编辑 package.json，添加以下脚本：

json 复制代码

{
  "scripts": {
    "build": "rimraf dist && rollup -c rollup.config.mjs && npm run build:dts",
    "build:watch": "rollup -c -w",
    "build:dts": "api-extractor run --local",
    "dev": "nodemon --watch dist --exec node dist/index.cjs.js",
    "start": "npm run build:watch"
  },
}

build：执行 Rollup 打包项目。
dev：使用 Nodemon 启动开发服务器。
build:dts：使用 API Extractor 生成 API 文档。

8. 开发流程

构建项目：首先使用 Rollup 打包 TypeScript 代码：
arduino 复制代码
```
npm run build
```
开发模式：启动 Nodemon 监视源代码的变化，并自动重启 Node.js 应用：
arduino 复制代码
```
npm run dev
```
生成 API 文档 ：在项目中运行 API Extractor，生成 API 文档和 .d.ts 文件：
arduino 复制代码
```
npm run build:dts
```
执行后，API Extractor 将分析项目中的 TypeScript 文件，生成 API 文档，并在 dist/temp 文件夹中输出。

9. 项目目录结构

在完成配置后，你的项目目录结构大致如下：

perl 复制代码

my-node-api-project/
├── dist/                 # 打包后的文件
│   ├── bundle.js
│   └── types/            # 生成的 TypeScript 类型声明文件
├── src/                  # 源代码
│   ├── index.ts
├── api-extractor.json    # API Extractor 配置文件
├── rollup.config.js      # Rollup 配置文件
└── package.json          # npm 脚本

10. 总结

通过结合使用 Rollup 、TypeScript 、Nodemon 和 @microsoft/api-extractor，我们构建了一个现代化的开发环境，能够高效地打包 TypeScript 代码、自动监视文件变化并重启应用，同时自动生成 API 文档和类型声明。

这种架构适用于需要高效构建、自动化文档生成以及快速开发迭代的 Node.js 项目，特别是在开发 TypeScript 库和 API 时，非常适合。

希望这篇文章能够帮助你搭建起高效的开发环境！

使用 Rollup、TypeScript、Nodemon 和 @microsoft/api-extractor 构建高效的 Node.js 开发环境