【制作npm包2】了解 package.json 相关配置

制作npm包目录

本文是系列文章, 作者一个橙子pro,本系列文章大纲如下。转载或者商业修改必须注明文章出处

一、申请npm账号、个人包和组织包区别
二、了解 package.json 相关配置
三、 了解 tsconfig.json 相关配置
四、 api-extractor 学习
五、npm包制作完整教程,我的第一个npm包


学习 package.json

各大项目的根目录都可以看到package.json这个文件,这个文件到底有什么作用了。对于这个文件的配置项很多,其中最常配置的nameversion,在平时开发种,大多数配置项可能非常没用。但是对于制作一个安装包而言,太重要了,这里必须解释一番。

这个json 大致是我的npm项目当中用到的配置,其它的

{
  "name": "@v3p/npm-pkg-by-vite",
  "version": "1.0.5-0",
  "description": "基于vite的npm包模板",
  "type": "module",
  "files": [
    "dist"
  ],
  "main": "./dist/index.cjs",
  "module": "./dist/index.mjs",
  "types": "./dist/index.d.ts",
  "exports": {
    ".": {
      "import": "./dist/index.mjs",
      "require": "./dist/index.cjs",
      "types": "./dist/index.d.ts"
    }
  },
  "scripts": {
    "dev:demo": "cd example && vite",
    "build:demo": "cd example && vite build",
    "build": "vite build",
    "build-types": "vue-tsc -p ./tsconfig.types.json && api-extractor run -c api-extractor.json && node scripts/cleanup.js",
    "build-all": "npm run build && npm run build-types"
  },
  "keywords": [
    "一个橙子pro",
    "vue",
    "vite",
    "typescript"
  ],
  "repository": {
    "type": "git",
    "url": "git+https://github.com/vue3plugin/npm-pkg-by-rollup.git"
  },
  "author": "biancangming",
  "license": "MIT",
  "bugs": {
    "url": "https://github.com/vue3plugin/npm-pkg-by-rollup/issues"
  },
  "homepage": "https://github.com/vue3plugin/npm-pkg-by-rollup#readme",
  "devDependencies": {
    "@microsoft/api-extractor": "^7.36.4",
    "@types/node": "^20.4.8",
    "@vitejs/plugin-vue": "^4.2.3",
    "tslib": "^2.6.1",
    "typescript": "^5.1.6",
    "vite": "^4.4.9",
    "vue": "^3.3.4",
    "vue-tsc": "^1.8.8"
  },
  "dependencies": {
    "@tsconfig/node18": "^18.2.0",
    "@vue/tsconfig": "^0.4.0"
  }
}

name

仓库的名字,这个名字可能在开发项目的时候没放在心上。对于npm包而言,当我们发布一个插件之后,使用npm install xx命令时,npm网站就会查找这个名字,下载到本地的node_modules文件夹里面。

@开头的就是组织的命名方式了。

一般在项目使用第三方包的时候,无论是require还是import实际上是调用的这里的名字。这点,在制作包的章节会重点介绍。

version

当我们在项目根目录执行npm version xxx命令时,这个版本号会随之变动。这块建议反复练习,自行观察。

version 的格式是major.minor.patch-prerelease, 并且需要遵循该规则。这个字段是一个包当中十分必要的字段,该字段由四位组成,分别是主要版本号、次要版本号、补丁版本号、最后存在短杠连接的表示预览版本,且存在一个预览的版本号

版本号的主要操作命令是,npm version,我们可以直接执行类似,npm version 1.0.0的命令修改当前的版本号,如果只是这样的话,还不如在 package.json文件当中手动修改。

在官方的解释当中,它的命令是这样的。

npm version [ | major | minor | patch | premajor | preminor | prepatch | prerelease | from-git]

下面是对该命令用法上的一些举例

npm version major 执行该命令修改主要版本号+1,同时清除预览版本号(如果存在)
npm version minor执行该命令修改次要版本号+1,同时清除预览版本号(如果存在)
npm version patch 执行该命令修改补丁版本号+1,同时清除预览版本号(如果存在)
npm version premajor 执行该命令修改主要版本号+1,同时添加预览版本号(如果不存在)
npm version preminor 执行该命令修改次要版本号+1,同时添加预览版本号(如果不存在)
npm version prepatch 执行该命令修改补丁版本号+1,同时添加预览版本号(如果不存在)
npm version prerelease 执行该命令预览版本号+1
npm version from-git 执行该命令拉取git版本号,同步为npm版本

在使用一个安装包的时候,通常会看到安装包的每个版本前有类似^~这种符号。

 "vue": "^3.3.4" // 

一旦有了符号的存在,则表示我们在执行npm install的时候,安装的并非看到的版本。

^ 表示锁定主版本,后边的版本是不会锁定的,在执行npm i的时候,也可能安装的是3.4.x的版本。
~ 表示锁住主版本和次要版本,只更新补丁版本

之前就有vue从2.6 升级2.7直接支持了composition-api的语法,导致我司大量项目翻车,只好逐个把项目当中^改为~。如果项目长时间搁置的话,建议将package-lock.json文件甚至node_modules一直做保留,血泪教训

type

用于指定 npm 包的类型,这个字段比较特殊,它影响的是开发阶段。目前对于新版的node来说有两种导包方式,目前可取值 commonjsmodule。设置为module,在根目录的配置文件就可以直接使用import方式导入包,而不需要module.exports的形式

files

在发布包的时候特别有用,用于控制推送到npm仓库包不包含多余的文件。

files 的值是一个数组,值是文件名或者文件夹名,如果是文件夹名,则文件夹下所有的文件也会被包含进来(除非文件被另一些配置排除了)

根目录下创建一个.npmignore文件,这个文件当中可以写入文件名或者文件夹名,用于排除某些文件。

文件示例如下

.vscode
demo/
etc/

main

main 字段指定了模块的入口文件,它的值是一个相对于项目根目录的路径。一般提供给commonjs模块系统使用,在项目当中使用require导入则使用这个字段

module

这个字段指定了用于 ES6 模块的入口文件。如果你的模块使用了 ES6 模块语法,并且想要在支持该语法的环境中使用该模块,就需要指定 module 字段。
一般提供给es模块系统使用,在项目当中使用import .. from ..导入则使用这个字段

types

这个字段指定了 typeScript 类型定义文件的入口,用于ts项目当中类型推断使用

exports

package.json 中,exports 字段是一个对象。表示可以定义多种类型的导入形式。例如:

{
  "exports": {
    ".": "./index.js",
    "./utils": "./lib/utils.js"
  }
}

这种方式的导入默认是es的导出方式,下面还有一种写法

"exports": {
    ".": {
      "import": "./dist/mjs/index.mjs",
      "require": "./dist/cjs/index.cjs",
      "types": "./dist/npm-pkg-by-rollup.d.ts"
    }
  },

这种方式则支持多种方式导出,对我们来说更加通用。后边在介绍npm制作时,对这里会进行一些拓展。

exports 可以替代上边几种类型,但是我们一般这四个字段都需要定义。毕竟旧版的node并不是全部能够支持这些字段,例如node12版本,可能还不识别exports。如果了解前端的模块化历史,就知道前端的模块化统一有多艰难,不过目前来说,一直向es模块化归一了。

author

指明项目的作者,网站上在keywords 下方显示

keywords

这个关键词是一个字符串数组,描述安装包的关键词。关键字在搜索包的时候,随着搜索结果出现在列表下方。
【制作npm包2】了解 package.json 相关配置_第1张图片

description

一个描述当前项目的简短说明,描述同样显示在搜索结果当中。这个和keywords关键字一样重要,要不然别人在搜索包的时候没有任何描述,难免有些苍白。
【制作npm包2】了解 package.json 相关配置_第2张图片

scripts

可运行于命令行的脚本命令的对象,它们用来执行项目中特定的任务。

repository

指向项目代码的 Git 存储库的 URL 的对象。

homepage

当前项目的主页 URL,和上方的repository在网站显示在如图位置。
【制作npm包2】了解 package.json 相关配置_第3张图片

license

一个字符串,指明当前项目的开源许可证。

bugs

指定对项目有疑问时,去哪里进行提问。

dependencies

一个包含当前项目的生产环境所需的所有第三方包和模块的对象。

devDependencies

当前项目里面的开发依赖包,开发依赖包和上边的dependencies,很多人难以区分作用。的确,在日常开发的时候作用不是很明显,但是当制作安装包时就体现出作用了。当我们的依赖包被别人安装时, devDependencies里面的东西是不会被安装的。
通常使用npm i xx -D安装此类依赖包

peerDependencies

用于指导npm安装正确的依赖版本。

例如:某项目依赖vue 3.2.1这个版本,当我们安装当前包时,会根据peerDependencies的配置,寻找响应依赖版本是否已经被安装,如果依赖包没有被安装,或者安装版和已经安装的版本存在冲突,则会终止安装过程。

可以使用–legacy-peer-deps参数,绕过这种机制。

你可能感兴趣的:(制作npm包修炼指南,npm,json,前端)