NPM 包开发与优化全面指南

前言

  • Hey, 我是 Immerse
  • 系列文章首发于【Immerse】，更多内容请关注该网站
  • 转载说明：转载请注明原文出处及版权声明！

1. 理解 NPM 包的结构

1.1 package.json 文件：包的核心

package.json文件是 NPM 包的中央配置，定义了包的各个方面，从基本元数据到复杂的发布配置。

{
    "name": "my-awesome-package",
    "version": "1.0.0",
    "description": "一个令人惊叹的包",
    "main": "./dist/index.js",
    "module": "./dist/index.mjs",
    "types": "./dist/index.d.ts",
    "files": ["dist"],
    "scripts": {
        "build": "tsup src/index.ts --format cjs,esm --dts",
        "test": "jest"
    },
    "keywords": ["awesome", "package"],
    "author": "Your Name <you@example.com>",
    "license": "MIT",
    "dependencies": {
        "lodash": "^4.17.21"
    },
    "devDependencies": {
        "typescript": "^4.5.5",
        "tsup": "^5.11.13",
        "jest": "^27.4.7"
    }
}

让我们详细解析一些关键字段：

  • name和version：这两个字段组成了包在 NPM 注册表中的唯一标识符。
  • main，module和types：这些指定了不同模块系统和 TypeScript 支持的入口点。
  • files：这个数组指定了发布包时应该包含哪些文件和目录。
  • scripts：这些是常见任务（如构建和测试）的命令快捷方式。

1.2 理解包的入口点

现代 JavaScript 生态系统支持多种模块格式。您的包应该通过提供多个入口点来适应不同的环境。

  1. main：主要入口点，通常用于 CommonJS (CJS)模块。
  2. module：用于 ECMAScript (ESM)模块的入口点。
  3. browser：用于浏览器环境的入口点。
  4. types：TypeScript 类型声明的入口点。

以下是一个包结构的示例：

my-awesome-package/
├── src/
│   ├── index.ts
│   └── utils.ts
├── dist/
│   ├── index.js        (CJS构建)
│   ├── index.mjs       (ESM构建)
│   ├── index.d.ts      (TypeScript声明)
│   └── browser.js      (浏览器特定构建)
├── package.json
└── tsconfig.json

对应的package.json配置：

{
    "name": "my-awesome-package",
    "version": "1.0.0",
    "main": "./dist/index.js",
    "module": "./dist/index.mjs",
    "browser": "./dist/browser.js",
    "types": "./dist/index.d.ts",
    "exports": {
        ".": {
            "require": "./dist/index.js",
            "import": "./dist/index.mjs",
            "types": "./dist/index.d.ts"
        }
    }
}

2. 深入理解模块格式

2.1 CommonJS (CJS)

CommonJS 是 Node.js 的传统模块格式。它使用require()进行导入，使用module.exports进行导出。

// mathUtils.js
function add(a, b) {
    return a + b;
}

function subtract(a, b) {
    return a - b;
}

module.exports = {
    add,
    subtract,
};

// main.js
const mathUtils = require('./mathUtils');
console.log(mathUtils.add(5, 3)); // 输出: 8

2.2 ECMAScript 模块 (ESM)

ESM 是 JavaScript 模块的现代标准，使用import和export语句。

// mathUtils.mjs
export function add(a, b) {
    return a + b;
}

export function subtract(a, b) {
    return a - b;
}

// main.mjs
import { add, subtract } from './mathUtils.mjs';
console.log(add(5, 3)); // 输出: 8

2.3 通用模块定义 (UMD)

UMD 是一种允许模块在多种环境（CommonJS、AMD、全局变量）中工作的模式。

(function (root, factory) {
    if (typeof define === 'function' && define.amd) {
        // AMD
        define(['exports'], factory);
    } else if (typeof exports === 'object' && typeof exports.nodeName !== 'string') {
        // CommonJS
        factory(exports);
    } else {
        // 浏览器全局变量
        factory((root.mathUtils = {}));
    }
})(typeof self !== 'undefined' ? self : this, function (exports) {
    exports.add = function (a, b) {
        return a + b;
    };
    exports.subtract = function (a, b) {
        return a - b;
    };
});

3. 高级包优化技术

3.1 Tree Shaking 和副作用

Tree shaking 是现代打包工具用来消除死代码的技术。要使您的包可以进行 tree shaking：

  1. 使用 ES 模块
  2. 避免副作用
  3. 在package.json中使用"sideEffects"字段
{
    "name": "my-utils",
    "version": "1.0.0",
    "sideEffects": false
}

如果某些文件确实有副作用：

{
    "name": "my-utils",
    "version": "1.0.0",
    "sideEffects": ["./src/polyfills.js", "*.css"]
}

3.2 代码分割和动态导入

对于大型包，考虑使用代码分割，允许用户只导入他们需要的部分：

// heavyFunction.js
export function heavyFunction() {
    // ... 一些计算密集型操作
}

// main.js
async function doHeavyWork() {
    const { heavyFunction } = await import('./heavyFunction.js');
    heavyFunction();
}

3.3 条件导出

使用条件导出为不同的环境或导入条件提供不同的入口点：

{
    "name": "my-package",
    "exports": {
        ".": {
            "import": "./dist/index.mjs",
            "require": "./dist/index.cjs",
            "browser": "./dist/browser.js"
        },
        "./utils": {
            "import": "./dist/utils.mjs",
            "require": "./dist/utils.cjs"
        }
    }
}

4. 版本管理和发布

4.1 语义化版本控制 (SemVer)

语义化版本使用三部分版本号：主版本号.次版本号.修订号

  • 主版本号：进行不兼容的 API 更改时
  • 次版本号：以向后兼容的方式添加功能时
  • 修订号：进行向后兼容的 bug 修复时
npm version patch -m "版本更新到 %s - 修复文档中的拼写错误"
npm version minor -m "版本更新到 %s - 添加新的实用函数"
npm version major -m "版本更新到 %s - 更改API结构"

4.2 预发布版本

对于预发布版本，使用带连字符的标签：

  • latest: 最新线上版本
  • alpha: 内部测试版本
  • beta: 公开测试版本
  • rc: 发行候选版本
    • Tips: 可以将这些标识符添加到版本号中，同时也可以添加额外版本：如：1.0.0-alpha.0 和 1.0.0-beta.1 和 1.0.0-rc.1
npm version prerelease --preid=alpha
# 1.0.0 -> 1.0.1-alpha.0

npm version prerelease --preid=beta
# 1.0.1-alpha.0 -> 1.0.1-beta.0

npm version prerelease --preid=rc
# 1.0.1-beta.0 -> 1.0.1-rc.0

4.3 使用标签发布

使用标签发布不同版本或预发布版本：

npm publish --tag next
npm publish --tag beta

用户可以安装特定版本：

npm install my-package@next
npm install my-package@beta

5. 持续集成和部署 (CI/CD)

5.1 使用 GitHub Actions 进行自动发布

创建一个.github/workflows/publish.yml文件：

name: 发布包

on:
    release:
        types: [created]

jobs:
    build:
        runs-on: ubuntu-latest
        steps:
            - uses: actions/checkout@v2
            - uses: actions/setup-node@v2
              with:
                  node-version: '14'
                  registry-url: 'https://registry.npmjs.org'
            - run: npm ci
            - run: npm test
            - run: npm run build
            - run: npm publish
              env:
                  NODE_AUTH_TOKEN: ${{secrets.NPM_TOKEN}}

    publish-gpr:
        needs: build
        runs-on: ubuntu-latest
        steps:
            - uses: actions/checkout@v2
            - uses: actions/setup-node@v2
              with:
                  node-version: '14'
                  registry-url: 'https://npm.pkg.github.com'
            - run: npm ci
            - run: npm publish
              env:
                  NODE_AUTH_TOKEN: ${{secrets.GITHUB_TOKEN}}

这个工作流程将在您创建新版本时自动将您的包发布到 NPM 和 GitHub Packages。

5.2 自动化版本更新

您可以在 CI/CD 管道中自动化版本更新。以下是使用 GitHub Action 的示例：

name: 更新版本

on:
    push:
        branches:
            - main

jobs:
    bump-version:
        runs-on: ubuntu-latest
        steps:
            - uses: actions/checkout@v2
              with:
                  fetch-depth: 0
            - uses: actions/setup-node@v2
              with:
                  node-version: '14'
            - name: 更新版本
              run: |
                  git config --local user.email "action@github.com"
                  git config --local user.name "GitHub Action"
                  npm version patch -m "更新版本到 %s [skip ci]"
            - name: 推送更改
              uses: ad-m/github-push-action@master
              with:
                  github_token: ${{ secrets.GITHUB_TOKEN }}
                  branch: ${{ github.ref }}

这个动作将在每次向主分支推送更改时自动更新包的修订版本号。

6. 包开发最佳实践

6.1 文档

良好的文档对于包的采用至关重要。考虑使用像 JSDoc 这样的工具进行内联文档：

/**
 * 将两个数字相加。
 * @param {number} a - 第一个数字。
 * @param {number} b - 第二个数字。
 * @returns {number} a和b的和。
 */
function add(a, b) {
    return a + b;
}

6.2 测试

使用像 Jest 这样的框架实现全面的测试：

// math.js
export function add(a, b) {
    return a + b;
}

// math.test.js
import { add } from './math';

test('1 + 2 应该等于 3', () => {
    expect(add(1, 2)).toBe(3);
});

6.3 代码检查和格式化

使用 ESLint 进行代码检查，使用 Prettier 进行代码格式化。以下是一个示例.eslintrc.js：

module.exports = {
    env: {
        browser: true,
        es2021: true,
        node: true,
    },
    extends: ['eslint:recommended', 'plugin:@typescript-eslint/recommended', 'prettier'],
    parser: '@typescript-eslint/parser',
    parserOptions: {
        ecmaVersion: 12,
        sourceType: 'module',
    },
    plugins: ['@typescript-eslint'],
    rules: {
        // 在这里添加自定义规则
    },
};

以及一个.prettierrc文件：

{
    "singleQuote": true,
    "trailingComma": "es5",
    "tabWidth": 2,
    "semi": true,
    "printWidth": 100
}

info.jpg

本文来自互联网用户投稿，该文观点仅代表作者本人，不代表本站立场。本站仅提供信息存储空间服务，不拥有所有权，不承担相关法律责任。如若转载，请注明出处：/a/905924.html

如若内容造成侵权/违法违规/事实不符，请联系我们进行投诉反馈qq邮箱809451989@qq.com，一经查实，立即删除！

相关文章

基于redis实现延迟队列

基于redis实现延迟队列

Redis实现延时队列 延时队列里装的主要是延时任务&#xff0c;用延时队列来维护延时任务的执行时间。 1、延时队列有哪些使用情景&#xff1f; 1、如果请求加锁没加成功 可以将这个请求扔到延时队列里&#xff0c;延后处理。 2、业务中有延时任务的需要 比如说&#xff0…
阅读更多...
探索Python安全字符串处理的奥秘：MarkupSafe库揭秘

探索Python安全字符串处理的奥秘：MarkupSafe库揭秘

文章目录 探索Python安全字符串处理的奥秘&#xff1a;MarkupSafe库揭秘第一部分&#xff1a;背景介绍第二部分&#xff1a;MarkupSafe是什么&#xff1f;第三部分&#xff1a;如何安装MarkupSafe&#xff1f;第四部分&#xff1a;MarkupSafe的简单使用方法1. 使用escape函数2.…
阅读更多...
Docker（一）：Docker简介及安装

Docker（一）：Docker简介及安装

目录 1 Docker简介1.1 容器跟虚拟机的区别1、虚拟机是什么2、容器是什么3、容器和虚拟机的区别 1.2 为什么要学习容器1.3 Docker 是什么 2 Docker安装2.1 安装docker-centos71、环境初始化2、安装docker-ce3、配置docker镜像加速器 2.2 安装docker-ubuntu22.041、安装2、添加镜…
阅读更多...
scp免密传输教程

scp免密传输教程

scp免密传输教程 为了在使用 scp 命令时不需要输入密码&#xff0c;通常的做法是通过设置 SSH 公钥认证来实现。这种方法不仅避免了每次都要输入密码的麻烦&#xff0c;而且也更加安全。下面是如何设置 SSH 公钥认证的步骤&#xff1a; 1. 生成 SSH 密钥对&#xff08;如果你…
阅读更多...
使用Postman发送POST请求的指南

使用Postman发送POST请求的指南

作为一名软件测试工程师&#xff0c;掌握如何使用Postman发送POST请求是非常重要的技能。POST请求通常用于向服务器发送数据&#xff0c;以创建或更新资源。本文将详细介绍如何在Postman中发送POST请求&#xff0c;帮助你高效地进行接口测试。 什么是POST请求&#xff1f; PO…
阅读更多...
＜项目代码＞YOLOv8 猫狗识别＜目标检测＞

＜项目代码＞YOLOv8 猫狗识别＜目标检测＞

YOLOv8是一种单阶段&#xff08;one-stage&#xff09;检测算法&#xff0c;它将目标检测问题转化为一个回归问题&#xff0c;能够在一次前向传播过程中同时完成目标的分类和定位任务。相较于两阶段检测算法&#xff08;如Faster R-CNN&#xff09;&#xff0c;YOLOv8具有更高的…
阅读更多...
auto占位符(C++11~C++17)

auto占位符(C++11~C++17)

文章目录 1. 定义1.1 注意事项 2. 推导规则3. 返回类型推导(C14)4. lambda表达式中使用auto类型推导5. 非类型模板形参占位符&#xff08;C17&#xff09; 1. 定义 在C11以前&#xff0c;auto关键字是用来声明自动变量的。从C11起auto被用来&#xff1a;声明变量时根据初始化表…
阅读更多...
栈虚拟机和寄存器虚拟机，有什么不同？

栈虚拟机和寄存器虚拟机，有什么不同？

本来这节内容是打算直接讲字节码指令的&#xff0c;但讲之前又必须得先讲指令集架构&#xff0c;而指令集架构又分为两种&#xff0c;一种是基于栈的&#xff0c;一种是基于寄存器的。 那不妨我们这节就单独来讲讲栈虚拟机和寄存器虚拟机&#xff0c;它们有什么不同&#xff0…
阅读更多...
Vision - 开源视觉分割算法框架 Grounded SAM2 配置与推理 教程 (1)

Vision - 开源视觉分割算法框架 Grounded SAM2 配置与推理 教程 (1)

欢迎关注我的CSDN&#xff1a;https://spike.blog.csdn.net/ 本文地址&#xff1a;https://spike.blog.csdn.net/article/details/143388189 免责声明&#xff1a;本文来源于个人知识与公开资料&#xff0c;仅用于学术交流&#xff0c;欢迎讨论&#xff0c;不支持转载。 Ground…
阅读更多...
vxe-table v4.8+ 与 v3.10+ 虚拟滚动支持动态行高，虚拟渲染更快了

vxe-table v4.8+ 与 v3.10+ 虚拟滚动支持动态行高，虚拟渲染更快了

Vxe UI vue vxe-table v4.8 与 v3.10 解决了老版本虚拟滚动不支持动态行高的问题&#xff0c;重构了虚拟渲染&#xff0c;渲染性能大幅提升了&#xff0c;行高自适应和列宽拖动都支持&#xff0c;大幅降低虚拟渲染过程中的滚动白屏&#xff0c;大量数据列表滚动更加流畅。 自适…
阅读更多...
Docker | 将本地项目发布到阿里云的实现流程

Docker | 将本地项目发布到阿里云的实现流程

发布到阿里云 本地镜像发布到阿里云流程具体流程1. docker commit 生成新镜像文件2. 查看镜像3. 阿里云开发者平台选择控制台&#xff0c;进入容器镜像服务&#xff0c;选择个人实例创建命名空间仓库名称进入管理界面获得脚本推送到阿里云 补充&#xff1a; docker tag 命令基本…
阅读更多...
龙迅#LT8668EX显示器图像处理芯片 适用于HDMI1.4+VGA转4PORT LVDS,支持4K30HZ分辨率,可做OSD菜单亮度调节!

龙迅#LT8668EX显示器图像处理芯片 适用于HDMI1.4+VGA转4PORT LVDS,支持4K30HZ分辨率,可做OSD菜单亮度调节!

1. 一般说明 LT8668EX 是 Lontium 的第二代 LCD 控制器&#xff0c;基于 ClearEdge 技术&#xff0c;支持 VGA 接口和 HDMI 接口&#xff0c;符合 HDMI 1.4 规范。它可以支持带 HDMI 接口的双模 DP。为了向后兼容&#xff0c;该 LCD 控制器还包括一个高性能模拟接口&#xff0…
阅读更多...
如何在Linux系统中使用Apache HTTP Server

如何在Linux系统中使用Apache HTTP Server

如何在Linux系统中使用Apache HTTP Server Apache简介 安装Apache 在Debian/Ubuntu系统中安装 在CentOS/RHEL系统中安装 启动Apache服务 验证Apache是否正在运行 访问Apache默认页面 配置Apache虚拟主机 创建虚拟主机配置文件 示例虚拟主机配置 创建网站根目录 准备静态网站内…
阅读更多...
【大模型开发指南】llamaindex配置deepseek、jina embedding及chromadb实现本地RAG及知识库（win系统、CPU适配）

【大模型开发指南】llamaindex配置deepseek、jina embedding及chromadb实现本地RAG及知识库（win系统、CPU适配）

说一些坑&#xff0c;本来之前准备用milvus&#xff0c;但是发现win搞不了&#xff08;docker都配好了&#xff09;。然后转头搞chromadb。这里面还有就是embedding一般都是本地部署&#xff0c;但我电脑是cpu的没法玩&#xff0c;我就选了jina的embedding性能较优&#xff08;…
阅读更多...
拔得头筹 | 怿星科技斩获第四届“乌镇杯”高层次人才创业创新大赛一等奖

拔得头筹 | 怿星科技斩获第四届“乌镇杯”高层次人才创业创新大赛一等奖

10月31日&#xff0c;第四届“乌镇杯”高层次人才创业创新大赛总决赛在桐乡市隆重举行&#xff0c;怿星科技“智能汽车软件研发测试工具链”项目成功入围总决赛&#xff0c;并荣获“人工智能”赛道一等奖。 本次大赛以“e城桐创智领未来”为主题&#xff0c;围绕桐乡市重点产业…
阅读更多...
鸢尾博客项目总结

鸢尾博客项目总结

1.博客介绍 鸢尾博客是一个基于Spring BootVue3 TypeScript ViteJavaFx的客户端和服务器端的博客系统。项目采用前端与后端分离&#xff0c;支持移动端自适应&#xff0c;配有完备的前台和后台管理功能。后端使用Sa-Token进行权限管理,支持动态菜单权限&#xff0c;服务健康…
阅读更多...
Installshield 总是跳出 Activation 激活对话框，而且创建项目失败

Installshield 总是跳出 Activation 激活对话框，而且创建项目失败

今天打开InstallShield &#xff0c;总是出现这个对话框&#xff0c;而且输入序列号后&#xff0c;虽然现实激活&#xff0c;但是无论打开原来的项目&#xff0c;还是新建项目都是失败。 解决方法&#xff1a; 一直没有思路&#xff0c;后来&#xff0c;使用管理员打开VS&#…
阅读更多...
TLV320AIC3104IRHBR 数据手册 一款低功耗立体声音频编解码器 立体声耳机放大器芯片麦克风

TLV320AIC3104IRHBR 数据手册 一款低功耗立体声音频编解码器 立体声耳机放大器芯片麦克风

TLV320AIC3104 是一款低功耗立体声音频编解码器&#xff0c;具有立体声耳机放大器以及在单端或全差分配置下可编程的多个输入和输出。该器件包括基于寄存器的全面电源控制&#xff0c;可实现立体声 48kHz DAC 回放&#xff0c;在 3.3V 模拟电源电压下的功耗低至 14mW&#xff0…
阅读更多...
11月第一篇新作，十一月对我好一点：C++之继承（2）

11月第一篇新作，十一月对我好一点：C++之继承（2）

C之继承&#xff08;2&#xff09; 虚继承 很多⼈说C语法复杂&#xff0c;其实多继承就是⼀个体现。有了多继承&#xff0c;就存在菱形继承&#xff0c;有了菱形继承就有 菱形虚拟继承&#xff0c;底层实现就很复杂&#xff0c;性能也会有⼀些损失&#xff0c;所以最好不要设计…
阅读更多...
uni-app 封装图表功能

uni-app 封装图表功能

文章目录 需求分析1. 秋云 uchars2. Echarts 需求 在 uni-app 中使用图表功能&#xff0c;两种推荐的图表工具 分析 在 Dcloud市场 搜索Echarts关键词&#xff0c;会出现几款图表工具&#xff0c;通过大家的下载量&#xff0c;可以看到秋云这个库是比较受欢迎的&#xff0c;其…
阅读更多...
最新文章

Copyright @ 2022~2023