从 0 开始创建一个前端使用的 npm 包

特别说明

本文将以 @boltdoggy/scroll-paging 包举例, 以下涉及命名请在个人实践时根据实际情况修改, 所有源码在 github:BoltDoggy/scroll-paging.

源码仓库: github[1]

TIP

一个优秀的 npm 包应当注明它的 github 仓库, 所以在一个新的 npm 包发布到 npm 仓库前, 都将是在 github 仓库下的操作

起步

首先在自己的 github 账号下创建一个共有仓库[2], 起名为 scroll-paging, 创建一个 README.md 文件以初始化.

以 ssh 地址 clone 到本地[3], 生成 scroll-paging 目录, 以下将此目录简称为 @.

@ 目录下执行 npm init[4], name 字段填写为 @boltdoggy/scroll-paging, 其它选项根据个人喜好随意, 将会自动生成 package.json 文件.

编码

@ 下创建 src 目录, 用于存放核心代码源文件.

我们期望使用 docs 目录作为 github pages[5] 源, 以用来展示示例, 因此创建 docs-src 目录用来存放示例代码源文件.

在这里推荐一款开箱即用的打包工具 parcel-bundler[6], 可以用来编译示例代码, 顺便使用示例代码在开发过程中调试核心代码, 执行 npm i parcel-bundler -D 以安装.

package.json 文件中添加 script 子属性

...
"script": {
    "dev": "cd docs-src && parcel index.html"
    ...
}
...
1
2
3
4
5
6

这时, 我们只需要执行 npm run dev, 即可以在浏览器中看到效果.

请自行完成编写 docs-src 目录与 src 目录下的代码.

编译

作为一个纯 js 项目, 我们可以直接使用 babel-cli[7] 编译, 而不需要复杂的流程工具, 执行 npm i babel-cli -D 以安装.

创建 .babelrc 并写入

{
    "presets": [
        [
            "env",
            {
                "modules": false
            }
        ]
    ]
}
1
2
3
4
5
6
7
8
9
10

特别注意

modules[8] 设为 false, 将保留 ES6 modules 而不转化为 commonjs 规范.

是因为我们这个包只为前端 webpack[9] 项目工作.

package.json 文件中添加 script 子属性

...
"script": {
    "build": "rm -rf lib && babel src --out-dir lib",
    ...
}
...
1
2
3
4
5
6

这时, 我们只需要执行 npm run build, 即可以看到生成后的 lib 目录.

发布

创建 .npmignore[10] 文件, 以排除不需要发布到 npm 仓库的文件.

然后, 一般来说, 直接执行 npm publish[11] 就是发布成功了.

但是首先你需要 npm adduser[12] 命令注册或登录.

特别注意

然而因为我们的 npm 包拥有一个特殊的前缀 @boltdoggy/[13], 将会默认以私有包发布, 因此我们需要添加属性特别说明发布为共有

npm publish --access public
1

后续工作

编译示例代码

package.json 文件中添加 script 子属性

...
"script": {
    "build:docs": "rm -rf docs && cd docs-src && parcel build index.html -d ../docs --public-url ./ && npm run build:docs:optimize",
    "build:docs:optimize": "cd docs && touch .nojekyll",
    ...
}
...
1
2
3
4
5
6
7

这时, 我们只需要执行 npm run build:docs, 即可以看到生成后的 lib 目录.

TIP

使用 .nojekyll 文件, 可以使得 github pages 服务使用 index.html 而不是 README.md 作为默认页面.

提交源码到 github

.npmignore 一样, 我们需要创建 .gitignore 文件, 以排除不需要提交到 git 仓库的文件.

依次执行 git 相关命令提交代码

git add -A
git commit -m 'init code'
git pull
git push
1
2
3
4

初始化 github pages 服务

在设置中, 找到 GitHub Pages, 选择 master branch /docs folder 并保存, 即可看到提示

TIP

Your site is published at https://boltdoggy.github.io/scroll-paging/


  1. 访问 github.com ↩︎

  2. 创建 github 仓库 ↩︎

  3. 选择 ssh 方式 clone ↩︎

  4. 创建 package.json 文件 ↩︎

  5. 使用 github pages 做静态资源服务 ↩︎

  6. parcle: 极速零配置Web应用打包工具 ↩︎

  7. babel-cli ↩︎

  8. babel-presets-env ↩︎

  9. webpack ↩︎

  10. Keeping files out of your package ↩︎

  11. npm publish ↩︎

  12. npm adduser ↩︎

  13. Publishing public scoped packages to the primary npm registry ↩︎