制作npm包目錄
本文是系列文章， 作者一個橙子pro，本系列文章大綱如下。轉載或者商業修改必須注明文章出處
一、申請npm賬號、個人包和組織包區別
二、了解 package.json 相關配置
三、 了解 tsconfig.json 相關配置
四、 api-extractor 學習
五、npm包制作完整教程，我的第一個npm包
本文涉及知識較多，建議認真閱讀前面的文章。
認識node_modules
我們打開任意一個項目的node_modules文件夾
這里.bin是一些可執行文件，npm run xxx之所以能運行，是這里面的bin文件發揮了作用。.cache 是一個緩存文件夾，通常是打包工具為了提高項目再次啟動的效率創建的。vite 搭建的項目還可以看到 .vite 文件夾，這個是.vite是它的緩存。有時候在包升級或者降級時，發現并沒有更新，可能就是這里的緩存出了問題，刪除緩存，重新啟動即可。而無需刪除整個node_modules文件夾。
找到我們熟悉的vue，看到他的所有文件。
這個項目包含了dist，是vue官方打包文件
LICENSE是證書文件
README.md是文檔說明
package.json 是配置文件
這幾個項目通常是一個npm包當中必須存在的一些配置。
點開他的package.json, 如下配置
"main": "dist/vue.runtime.common.js","module": "dist/vue.runtime.esm.js","name": "vue","typings": "types/index.d.ts", // typings 有時寫成 types
可以看得到分別導出了commonjs，es，ts類型這幾個配置。當我們在一個項目當中執行import { xxx } from "vue" 的時候，實際上是從package.json文件當中找到他的name這個屬性，這里 from “vue”這個vue就是配置文件當中的名字。
制作第一個npm包
在制作包之前，強烈建議將前幾部分的文章鞏固一下。
初始化package.json配置
這里以制作組織安裝包為例，由于普通安裝包和組織包在外觀上只有包名上的區別。所以學會制作組織包，就等于學會了制作一般的安裝包。
-
找個合適的文件夾，我這里取名叫做
npm-pkg-by-vite。 -
在文件夾打開
cmd命令行輸入npm init --yes
用vscode打開當前文件夾，可以看到package.json文件如下，按如下描述，對這個包進行一定的修改。
{"name": "npm-pkg-by-vite","version": "1.0.0", // 暫且修改為0.0.0"description": "", // 修改為自己合適的描述"main": "index.js", "scripts": {"test": "echo \"Error: no test specified\" && exit 1"},"keywords": [],"author": "", // 修改為自己的名字"license": "ISC"
}
-
申請一個
git倉庫，我這里github為例。用途在這篇文章《【制作npm包2】了解 package.json 相關配置》進行了詳細描述 -
初始化倉庫
- 在
cmd輸入命令npm init --scope=v3p，這里的v3p是我申請的組織的名稱，這里需要更換成自己申請的名字。 - package name：首先看到控制臺提示
@組織/npm-pkg-by-vite的字樣，如果需要修改，輸入自定義名字就可以了。無需修改，直接回車鍵。 - version：版本號提示
1.0.0，看心情，我這里直接回車即可 - description：輸入描述，我這里輸入
我的第一個npm包 - git repository：
git分支，我這里輸入https://github.com/vue3plugin/npm-pkg-by-vite - author：我這里輸入，
一個橙子pro - license：我這里輸入，
MIT - Is this OK? ：直接回車就行。
再打開package.json文件查看，這里，在main下方加一個type參數
{"name": "@v3p/npm-pkg-by-vite","version": "1.0.0","description": "我的第一個npm包","main": "index.js","type": "module", // 修改為module，我們的目標包文件使用`ts`語法。"scripts": {"test": "echo \"Error: no test specified\" && exit 1"},"keywords": [],"author": "一個橙子pro","license": "MIT","repository": {"type": "git","url": "git+https://github.com/vue3plugin/npm-pkg-by-vite.git"},"bugs": {"url": "https://github.com/vue3plugin/npm-pkg-by-vite/issues"},"homepage": "https://github.com/vue3plugin/npm-pkg-by-vite#readme"
}
- 安裝依賴，我這里使用
vite這個打包工具，同時插件需要打包.vue的文件。直接上命令
npm i vite vue vue-tsc typescript tslib howtools @vitejs/plugin-vue @types/node @tsconfig/node18 @microsoft/api-extractor -D
配置ts環境
創建tsconfig.json 以及tsconfig.types.json文件。將第章節【制作npm包3】了解 tsconfig.json 相關配置中相關配置復制進去。
配置api-extractor
參照章節【制作npm包4】api-extractor 學習
創建scripts文件夾，創建cleanup.js文件
內容如下
// This file is executed from npm script with project root as cwd.
import fs from 'node:fs'// 這個是我們在tsconfig.types.json設置的輸出目錄
fs.rmSync('dist/types', { recursive: true }) // 這個操作是把npm-pkg-by-vite.d.ts 換成 index.d.ts 便于package.json通用設置
fs.renameSync('dist/npm-pkg-by-vite.d.ts', 'dist/index.d.ts')
初始化vite配置
創建vite.config.ts，將以下內容復制進去，vite更多配置參照官網。
import { defineConfig } from "vite";
import vue from '@vitejs/plugin-vue';export default defineConfig({build: {lib: {entry: "./src/index.ts", // 入口文件fileName: (format) => `index.${format}.js`,formats: ['es', "cjs"], // 打包同時支持`es`和`commonjs`},rollupOptions: {external: ['vue'], // 這里表示不進行打包的文件},cssCodeSplit: false, // css 文件不分割outDir: "dist", // 打包輸出目錄minify: "esbuild", // 壓縮模式},plugins: [vue(), // 支持`.vue`文件]
})
項目相關文件創建
- 創建src文件夾并創建
index.ts文件，隨意寫入文件內容即可。創建demo文件夾，寫一個簡單的vue項目即可。 - package.json文件
scripts設置如下
"scripts": {"dev:demo": "cd example && vite", // 運行demo"build:demo": "cd example && vite build", // 創建demo"build": "vite build", // 庫打包// 打包類型文件，vue-tsc 相當于 ts的 `tsc`命令，效果相同"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" },
執行npm run build-all，dist目錄輸出文件。
項目發布
一個完整的npm包至少包含，main入口文件配置，dist打包的文件包，README.md文件。這樣才能保證我們的項目發布到npm之后可以被正常使用。
這個時候，用到前邊章節的內容。在package.json文件當中增加files配置。
"files": ["dist"],
表示只有dist文件夾上傳到npm，其他的會忽略。這里不必擔心的是，我們的開源證書、README.md文件、package.json 文件不會因為這個設置，而不進行上傳。這個也是合理的，畢竟這些文件都是npm包必須的文件。
由于經過上述打包之后，我們生成了commonjs、es、ts類型這幾類文件，可以像vue項目那樣進行配置。
除了這幾個配置，還好細細說下exports這個配置。這個在前面章節有提及，還有一些細節需要在這里進行補充。有時我們打包之后的文件是需要分模塊導出的，而不是全部直接導出。這里舉個例子：
https://www.npmjs.com/package/howuse?activeTab=code
在這個文件夾當中看到很多的子包，從名稱來看，每個子包都有自己的依賴，如果從index.js直接導出，未免這個包會很重。如果只想使用pdf這個包，無緣無故的把其他的項目也會打包到我們項目當中，對treeshaking優化十分不利。
它的package.json 文件是這樣配置的
"exports": {"./axios": {"import": "./axios/axios.es.js","require": "./axios/axios.cjs.js","types": "./axios/index.d.ts"},"./echarts": {"import": "./echarts/echarts.es.js","require": "./echarts/echarts.cjs.js","types": "./echarts/index.d.ts"},// ... },
那么在使用的時候，可以這樣使用了import { xx } from 'howuse/echarts'或者require('howuse/echarts')，項目名加上子路徑的名稱，就可以直接識別到項目下面的文件目錄了。這樣以來，就比上邊main、module、typings這種散裝的配置靈活不少。
【完結】
)
