釋出npm包流程

npm 釋出包流程

背景：假設你寫了一些 js 方法想釋出
參考：https://www.youtube.com/watch?v=xnfdm-s8adI、

1. 初始化環境

mkdir methodjs
cd methodjs
npm init -y
npm i -D tsup@5 typescript@4 # node <14 時的相容版本，tsup用於編譯打包ts程式碼

# 確保用的是npm地址
npm config set registry https://registry.npmjs.org

2. 配置

• package.json

  {
     "name": "@sanhuamao1/methodjs", // 包名
     "version": "1.0.0",
     "description": "",
     "main": "./dist/index.js", // 當使用者嘗試透過 require() 引入時，Node.js 會預設使用這個檔案
     "module": "./dist/index.mjs", // 當使用者使用 ES 模組匯入語法來引入時，Node.js 會使用這個檔案
     "types": "./dist/index.d.ts", // 指定型別宣告檔案的位置
     "homepage": "xxx", // 自定義倉庫主頁地址
     "repository": {
        "url": "xxx" // 自定義倉庫地址
     },
     "scripts": {
        "build": "tsup" // 使用tsup打包原始碼，讓它分別打包成cjs和esm格式，下面有配置說明
     },
     "keywords": [], // 關鍵詞，在npm搜尋時輸入什麼關鍵詞能搜到這個包
     "author": "",
     "license": "MIT",
     "devDependencies": {
        "tsup": "^5.12.9",
        "typescript": "^4.9.5"
     }
  }
  

• tsconfig.json

  {
     "compilerOptions": {
        "strict": true,
        "noImplicitAny": true, // 禁止在沒有型別註解的情況下使用 'any' 型別
        "strictNullChecks": true, // 嚴格檢查 null 和 undefined 的型別，不允許將 null 和 undefined 賦值給非 void 型別的變數
        "target": "ES2022",
        "moduleResolution": "Node", // 使用 Node.js 的模組解析策略
        "module": "CommonJS", // 將程式碼生成為 CommonJS 模組，適用於 Node.js 環境
        "declaration": true, // 生成相應的 '.d.ts' 宣告檔案
        "isolatedModules": true, // 將每個檔案作為隔離的模組，不進行專案範圍內的型別檢查
        "noEmit": true, // 不要生成輸出檔案（例如在隔離模組模式下，不生成宣告檔案）
        "outDir": "dist" // 指定輸出資料夾，編譯後的檔案將放置在這裡
     },
     "include": ["src"],
     "exclude": ["node_modules"]
  }
  

• tsup.config.ts

  import tsup from 'tsup';
  // 最新版本是匯入方式是： import { defineConfig } from 'tsup'
  
  export default tsup.defineConfig({
     format: ['cjs', 'esm'], // 打包為cjs 、esm 格式
     entry: ['./src/index.ts'],
     dts: true, // 生成型別宣告檔案
     shims: true, // 為 Node.js 核心模組生成 polyfill，在瀏覽器環境中，也可以使用 require 和 module.exports
     skipNodeModulesBundle: true, // 跳過對 node_modules 中的依賴進行打包
     clean: true,
  });
  

• .npmignore：釋出時不想包含以下檔案

  /src
  /node_modules
  
  tsconfig.json
  tsup.config.ts
  

• .gitignore：上庫時不想包含以下檔案

  /dist
  /node_modules
  

3. 建立要釋出的內容

- src
    - browser
        - download.ts  // 假設這是我想釋出的方法
        - index.ts
        - types.ts
    - index.ts

// src/browser/types.ts

export type DownloadMediaProps = {
   url: string;
   fileName?: string;
};

// src/browser/download.ts

import { DownloadMediaProps } from './types';

const downloadMedia = ({ url, fileName }: DownloadMediaProps) => {
   fetch(url)
      .then((response) => response.blob())
      .then((blob) => {
         const blobUrl = URL.createObjectURL(blob);
         const aElement = document.createElement('a');
         aElement.style.display = 'none';
         aElement.href = blobUrl;
         aElement.download = fileName || url.slice(url.lastIndexOf('/') + 1);
         document.body.appendChild(aElement);
         aElement.click();
         document.body.removeChild(aElement);
      });
};

export { downloadMedia };

// src/browser/index.ts

export * from './types'
export * from './download'

// src/index.ts

export * from './browser'

// 隨便寫一個方便測試的
export const test = () => {
    console.log('test')
}

5. 編譯打包

npm run build

之後會在根目錄中生成dist資料夾，裡面是編譯打包好的內容

6. 本地測試

• 在包的根目錄下建立連結

  cd path/to/your-package
  npm link
  

• 在另一個專案中，使用該連結

  cd path/to/your-project
  npm link your-package-name  # 例：npm link @sanhuamao1/methodjs
  

• 進行測試

  // path/to/your-project/index.js
  
  const { test } = require('@sanhuamao1/methodjs')
  test()
  

  node index.js
  

7. 釋出包

• 確保在npm中建立了賬號
• 登入

  npm login
  

• 釋出

  npm publish # 釋出私有包
  npm publish --access=public # 釋出公共包