# npm-dependent-template

**Repository Path**: jl15988/npm-dependent-template

## Basic Information

- **Project Name**: npm-dependent-template
- **Description**: 一个用于开发NPM依赖包的模板项目，提供了基本的项目结构和配置，帮助开发者快速开始创建自己的NPM包。该模板使用TypeScript作为开发语言，使用Rollup作为打包工具，支持生成CommonJS、ES Module、UMD和IIFE等多种格式的输出。同时还提供了CSS/SCSS的打包支持，可以将样式文件打包到JS中或提取为单独的文件。
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-03-27
- **Last Updated**: 2025-03-27

## Categories & Tags

**Categories**: Uncategorized

**Tags**: template, npm, rollup

## README

# NPM依赖开发模板

一个用于开发NPM包/库的TypeScript模板项目

## 简介

这是一个用于开发NPM依赖包的模板项目，提供了基本的项目结构和配置，帮助开发者快速开始创建自己的NPM包。该模板使用TypeScript作为开发语言，使用Rollup作为打包工具，支持生成CommonJS、ES Module、UMD和IIFE等多种格式的输出。同时还提供了CSS/SCSS的打包支持，可以将样式文件打包到JS中或提取为单独的文件。

## 特性

- 💪 **TypeScript支持**: 内置TypeScript配置
- 📦 **多格式输出**: 支持CommonJS、ES Module、UMD和IIFE格式
- 🔍 **轻量打包**: 使用Rollup进行高效打包
- 🧩 **模块化导出**: 支持多种导入方式
- 🛠️ **开发/生产环境**: 内置开发和生产环境配置
- 🔄 **灵活配置**: 易于自定义的构建配置
- 🎨 **CSS/SCSS支持**: 支持样式文件的处理和打包

## 开发流程

### 1. 准备工作

1. 复制此模板到你的项目中
2. 修改`package.json`中的基本信息（名称、描述、版本、作者等）
3. 安装依赖:

```bash
npm install
# 或
yarn
# 或
pnpm install
```

### 2. 开发你的库

1. 编辑`src/index.ts`，实现你的库的主要功能
2. 如果需要，添加更多的源文件并在`index.ts`中导出它们
3. 编写文档和示例

### 3. 构建

```bash
# 开发环境构建（不压缩，带sourcemap）
npm run build:dev

# 生产环境构建（压缩，不带sourcemap）
npm run build:pro

# 构建特定格式（如UMD格式，用于浏览器中使用）
npm run build:umd
```

### 4. 测试

开发过程中，可以使用内置的测试项目快速验证：

```bash
# 快速开发测试（构建并在Node.js中测试）
npm run dev

# 在浏览器中测试
npm run test:browser
```

另外，也可以通过本地链接的方式测试你的包:

```bash
# 在你的包目录中
npm link

# 在其他测试项目中
npm link your-package-name
```

### 5. 发布

准备好发布时，更新版本号并执行：

```bash
npm run toPublish
```

## 项目结构

```
├── build/                      # 构建配置目录
│   ├── config.js               # 主要配置文件（修改此文件自定义配置）
│   ├── create-config.js        # 配置生成函数
│   └── plugins/                # 插件配置目录
│       ├── css.js              # CSS/SCSS处理插件配置
│       ├── terser.js           # 代码压缩插件配置
│       └── typescript.js       # TypeScript插件配置
├── dist/                       # 构建输出目录
│   ├── index.js                # CommonJS格式输出
│   ├── index.mjs               # ES Module格式输出
│   ├── index.umd.js            # UMD格式输出（可选）
│   ├── index.min.js            # IIFE格式输出（可选）
│   └── styles.css              # 提取的CSS文件（可选）
├── src/                        # 源代码目录
│   ├── index.ts                # 入口文件
│   └── styles/                 # 样式文件目录
│       ├── style.css           # CSS样式示例
│       └── style.scss          # SCSS样式示例
├── test-project/               # 测试项目目录
│   ├── src/                    # 测试项目源代码
│   │   └── index.js            # Node.js测试入口文件
│   ├── public/                 # 浏览器测试文件
│   │   └── index.html          # 浏览器测试页面
│   └── package.json            # 测试项目配置文件
├── types/                      # 类型定义输出目录
│   └── index.d.ts              # 类型声明文件
├── LICENSE                     # 开源许可证文件（需替换为您自己的）
├── package.json                # 包配置文件
├── tsconfig.json               # TypeScript配置
├── rollup.config.js            # Rollup主配置文件（入口点）
└── README.md                   # 文档
```

## package.json 关键字段说明

| 字段 | 描述 |
|------|------|
| `name` | NPM包的名称，请使用唯一的名称 |
| `version` | 版本号，遵循语义化版本规范 |
| `description` | 包的简短描述 |
| `main` | CommonJS格式的入口文件路径 |
| `module` | ES Module格式的入口文件路径 |
| `typings` | TypeScript类型定义文件路径 |
| `exports` | 提供更精确的模块导出映射 |
| `files` | 发布到NPM仓库的文件列表 |
| `scripts` | 定义npm命令脚本 |
| `keywords` | 包的关键词，有助于在npm搜索时被找到 |
| `author` | 包的作者信息 |
| `license` | 开源许可证类型 |
| `devDependencies` | 开发时依赖的包列表 |

## 构建配置说明

本模板采用模块化的构建配置，主要配置文件已被拆分到`build/`目录下，使配置更清晰、易于维护。

### 配置文件结构

- `rollup.config.js`: 主配置文件入口点，通常不需要修改
- `build/config.js`: 集中管理所有可配置选项的地方，**修改此文件来自定义配置**
- `build/create-config.js`: 创建Rollup配置对象的函数
- `build/plugins/`: 包含各种插件配置的目录

### 主要配置项

要自定义构建配置，只需编辑`build/config.js`文件中的选项：

```javascript
// 要生成的输出格式，可以根据需要添加或删除
// 可选值: 'cjs', 'es', 'umd', 'iife'
exports.OUTPUT_FORMATS = ['cjs', 'es'];

// 是否生成类型声明文件
exports.GENERATE_TYPES = true;

// UMD/IIFE格式下的全局变量名
exports.GLOBAL_NAME = pkg.name.replace(/-([a-z])/g, (_, letter) => letter.toUpperCase());

// 外部依赖，这些依赖不会被打包
exports.EXTERNAL = [];

// 入口文件路径
exports.INPUT_FILE = './src/index.ts';

// CSS/SCSS配置
exports.CSS_CONFIG = {
    // 是否启用CSS/SCSS处理
    enabled: true,
    // 是否将CSS提取为单独的文件，false表示注入到JS中
    extract: false,
    // 是否压缩CSS
    minimize: true,
    // CSS模块化，设为true会将类名转换为哈希值，避免样式冲突
    modules: false,
    // 是否使用Sass预处理器
    sass: true,
    // 自动添加浏览器前缀
    autoPrefix: true,
    // 提取的CSS文件名
    fileName: 'styles.css'
};
```

### 输出格式及其适用场景

| 格式 | 文件扩展名 | 适用场景 | 全局变量 |
|------|-----------|---------|---------|
| CJS (CommonJS) | `.js` | Node.js环境、webpack等打包工具 | 不适用 |
| ESM (ES Module) | `.mjs` | 现代浏览器、支持ES模块的打包工具、支持tree-shaking | 不适用 |
| UMD (Universal) | `.umd.js` | 通用格式，同时支持Node.js、AMD和浏览器 | 需要定义 |
| IIFE (自执行函数) | `.min.js` | 直接在浏览器中通过script标签使用 | 需要定义 |

### 常见配置示例

1. **添加UMD和IIFE格式**:
   ```javascript
   // build/config.js
   exports.OUTPUT_FORMATS = ['cjs', 'es', 'umd', 'iife'];
   ```

2. **配置外部依赖**:
   ```javascript
   // build/config.js
   exports.EXTERNAL = ['lodash', 'react', 'react-dom'];
   ```

3. **提取CSS为单独文件**:
   ```javascript
   // build/config.js
   exports.CSS_CONFIG.extract = true;
   exports.CSS_CONFIG.fileName = 'your-style.css';
   ```

4. **启用CSS模块化**:
   ```javascript
   // build/config.js
   exports.CSS_CONFIG.modules = true;
   ```

5. **禁用TypeScript类型声明生成**:
   ```javascript
   // build/config.js
   exports.GENERATE_TYPES = false;
   ```

### 在项目中使用CSS/SCSS

要在项目中使用CSS或SCSS文件，只需要在TypeScript文件中导入它们：

```typescript
// 导入CSS文件
import './styles/style.css';

// 导入SCSS文件
import './styles/style.scss';
```

如果启用了CSS模块化（`CSS_CONFIG.modules = true`），可以这样导入和使用：

```typescript
// 导入CSS模块
import styles from './styles/style.css';

// 使用CSS类
element.className = styles.exampleClass;
```

## 自定义开发

以下是开发自己的NPM包时需要修改的关键文件：

### 1. package.json

修改以下字段：
- `name`: 你的包名
- `description`: 包的描述
- `version`: 版本号
- `author`: 作者信息
- `keywords`: 关键词
- `repository`: 代码仓库地址

### 2. src/index.ts

这是你的包的主入口，实现你的核心功能并导出：

```typescript
// 导出你的类、函数或常量
export class YourClass { ... }
export function yourFunction() { ... }
export const YOUR_CONSTANT = ...

// 默认导出
export default YourMainExport;
```

### 3. README.md

编写良好的文档，说明你的包的使用方法、API和示例。

## 最佳实践

1. **保持专注**: 每个包应该只做一件事，并做好
2. **编写测试**: 确保你的代码可靠且按预期工作
3. **版本控制**: 遵循语义化版本规范
4. **文档完善**: 提供清晰的使用说明和API文档
5. **类型安全**: 利用TypeScript的类型系统提供良好的开发体验

## 许可证

本模板默认使用MIT许可证。**请注意**：在使用此模板创建自己的NPM包时，您应该：

1. 检查`LICENSE`文件并将其替换为您自己的许可证
2. 确保在`package.json`中更新`license`字段以匹配您选择的许可证类型
3. 更新您的个人或组织信息

常见的开源许可证选项：

- **MIT**: 非常宽松，允许几乎任何形式的使用、修改和分发
- **Apache 2.0**: 类似MIT但提供专利授权条款
- **GPL**: 强制要求衍生作品也必须使用相同许可证开源
- **BSD**: 类似MIT的宽松许可证，有多种变体

选择许可证时请考虑您项目的需求和目标。如果您不确定应该选择哪种许可证，可以参考[choosealicense.com](https://choosealicense.com/)获取建议。

## 依赖包说明

本模板使用的主要依赖包及其作用：

### 核心依赖

| 依赖 | 描述 |
|------|------|
| `typescript` | TypeScript编译器，用于将TypeScript代码编译为JavaScript |
| `rollup` | 下一代ES模块打包器，专注于性能和代码优化 |

### Rollup插件

| 插件 | 描述 |
|------|------|
| `rollup-plugin-typescript2` | Rollup的TypeScript插件，让Rollup能够处理TypeScript文件 |
| `@rollup/plugin-terser` | 使用Terser压缩JavaScript代码，减小包体积 |

### CSS/SCSS处理

| 依赖 | 描述 |
|------|------|
| `rollup-plugin-postcss` | 使Rollup能够处理CSS、SCSS等样式文件 |
| `autoprefixer` | 自动添加浏览器厂商前缀到CSS属性中 |
| `cssnano` | CSS压缩工具，优化和减小CSS文件体积 |
| `sass` | Sass编译器的纯JavaScript实现，处理SCSS文件 |
| `node-sass` | Sass编译器的Node.js绑定，提供更好的性能（可选） |

### 其他工具

| 依赖 | 描述 |
|------|------|
| `ts-loader` | Webpack的TypeScript加载器，如果需要与Webpack集成时使用 |
| `babel-loader` | Webpack的Babel加载器，用于JavaScript的转译 |

## 测试项目

本模板内置了一个测试项目，用于快速验证开发的NPM包功能。测试项目位于`test-project`目录下，包含了Node.js环境和浏览器环境的测试示例。

### 测试命令

以下命令可用于测试开发中的NPM包：

```bash
# 准备测试环境：构建包并安装到测试项目中
npm run prepare:test

# 在Node.js环境中测试
npm run test:node

# 在浏览器环境中测试（会自动打开测试页面）
npm run test:browser

# 快速开发命令：构建、安装并在Node.js中测试
npm run dev
```

### 测试项目结构

```
test-project/
├── src/                # Node.js测试源代码
│   └── index.js        # Node.js测试入口文件
├── public/             # 浏览器测试文件
│   └── index.html      # 浏览器测试页面
└── package.json        # 测试项目配置文件
```

### 自定义测试

1. 修改`test-project/src/index.js`添加Node.js环境下的测试代码
2. 修改`test-project/public/index.html`添加浏览器环境下的测试代码
3. 执行相应的测试命令查看结果

### 注意事项

- 使用`npm run prepare:test`会自动构建包并安装到测试项目中
- 浏览器测试需要UMD格式的包，该命令会自动构建UMD格式
- 若要更改测试项目依赖，需要修改`test-project/package.json`文件