由来
最近在弄新的npm依赖,但是发现没有都从头创建项目 实属有点儿麻烦 ,然后我找了之前开发的依赖,将多余代码删除了作为初始化的项目。于是~为什么不弄个模版 ,每次只需要初始化模版 即可,所以就有了这个模版,为了方便,我还发布到了npm 上,只需要简单的执行命令即可初始化npm依赖开发的项目。
特性
- 🚀 快速创建: 一行命令即可创建完整的TypeScript NPM库项目
- 💪 TypeScript: 内置TypeScript支持与类型声明生成
- 📦 多格式输出: 支持CommonJS、ES Module、UMD和IIFE格式
- 🎨 CSS/SCSS支持: 可以将样式文件打包到JS中或提取为单独文件
- 🧪 测试环境: 内置Node.js和浏览器测试环境
- 🔄 灵活配置: 模块化且易于自定义的构建配置
快速开始
无需安装,直接运行:
bash
# 使用npx(推荐)
npx create-ts-npm my-lib
# 或使用npm init
npm init ts-npm my-lib
# 或使用yarn create
yarn create ts-npm my-lib
然后按照提示操作,输入包名称、描述和作者信息。
手动安装
如果你需要多次使用,也可以选择全局安装:
bash
# 全局安装
npm install -g create-ts-npm
# 然后使用
create-ts-npm my-lib
生成的项目内容
生成的项目包含以下内容:
.
├── src/ # 源代码目录
│ ├── index.ts # 主入口文件
│ └── styles/ # 样式文件
├── build/ # 构建配置
├── dist/ # 打包输出目录(构建后生成)
├── types/ # 类型声明文件(构建后生成)
├── test-project/ # 测试项目
├── tsconfig.json # TypeScript配置
└── rollup.config.js # Rollup配置
生成的项目构建配置说明
本模板采用模块化的构建配置,主要配置文件已被拆分到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标签使用 | 需要定义 |
常见配置示例
-
添加UMD和IIFE格式:
javascript// build/config.js exports.OUTPUT_FORMATS = ['cjs', 'es', 'umd', 'iife'];
-
配置外部依赖:
javascript// build/config.js exports.EXTERNAL = ['lodash', 'react', 'react-dom'];
-
提取CSS为单独文件:
javascript// build/config.js exports.CSS_CONFIG.extract = true; exports.CSS_CONFIG.fileName = 'your-style.css';
-
启用CSS模块化:
javascript// build/config.js exports.CSS_CONFIG.modules = true;
-
禁用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;
使用生成的项目
生成项目后,你可以:
bash
# 安装依赖
cd my-lib
npm install
# 开发模式(构建并在Node.js中测试)
npm run dev
# 在浏览器中测试
npm run test:browser
# 构建生产版本
npm run build:pro
# 发布到NPM
npm run toPublish