Membina pakej NPM untuk CommonJS dengan kebergantungan ESM

TLDR

Anda perlu menggunakan pengikat seperti esbuild yang akan menyusun projek anda dan menggabungkan semua kebergantungan itu bersama-sama dengannya supaya ia tidak diimport. Ini memintas isu ketidakserasian ESM/CommonJS.

Jika anda tidak sabar, anda boleh pergi terus ke kod dengan contoh pelaksanaan ini.

Konteks

Semasa bersiap untuk mengeluarkan projek baharu saya Token.js pada hujung minggu, saya menghadapi masalah yang agak mengecewakan. Saya mahu pakej saya menyokong CommonJS sebagai tambahan kepada ESM, tetapi saya mempunyai kebergantungan ESM tulen. Pasukan salib ESM tulen di luar sana mungkin agak tidak berpuas hati dengan saya mengatakannya, tetapi jika anda sedang membina pakej NPM dan mahu ia digunakan secara meluas, anda masih perlu menyokong CommonJS pada tahun 2024.

Token.js ialah TypeScript SDK ringkas yang membolehkan anda menyepadukan 60+ LLM daripada 9 pembekal berbeza (OpenAI, Anthropic, Cohere, dll). Palam yang tidak tahu malu, lihat dan beritahu saya pendapat anda jika anda suka ai generatif.

Kini terdapat beberapa sumber dalam talian yang membincangkan cara membina projek Javascript untuk ESM, CommonJS atau kedua-duanya. Walau bagaimanapun, saya secara khusus menghadapi masalah menangani hakikat bahawa saya mempunyai kebergantungan yang ESM tulen. Saya mendapati perkara ini agak sukar untuk ditangani kerana saya tidak biasa dengan pengikat (kebanyakan saya bekerja pada bahagian belakang aplikasi web), dan tidak dapat mencari panduan yang baik tentang topik tersebut.

Jadi jika ada orang lain yang menghadapi masalah ini, inilah penyelesaiannya.

Panduan

Pasang esbuild

Kami akan menggunakan esbuild untuk pengikat.

yarn add esbuild --save-dev

Buat skrip binaan

Kami memerlukan skrip binaan ringkas untuk menjalankan esbuild dan mengeluarkan hasilnya.

import esbuild from 'esbuild'

const entrypoint = "<your entrypoint here>"
const tsconfig = "<your tsconfig path here>"

const build = async () => {
  await Promise.all([
    // bundle for commonjs
    esbuild.build({
      entryPoints: [entrypoint],
      bundle: true,
      minify: true,
      format: 'cjs',
      outfile: `./dist/index.cjs`,
      platform: 'node',
      treeShaking: true,
      tsconfig,
    }),
  ])
}

build()

Tambahkan skrip binaan pada package.json anda

Jalankan dengan masa jalan pilihan anda.

"scripts": {
  "build": "vite-node ./scripts/build.ts",
}

Saya secara peribadi suka vite-node. Jadi, jika anda mahu mengikutinya dengan tepat, anda perlu memasangnya:

yarn add vite-node --save-dev

Bina projek anda

yarn build

Ini akan menyebabkan membina projek anda dengan esbuild dan anda akan melihat fail baharu, dist/index.cjs, iaitu binaan CommonJS bagi pakej anda.

Konfigurasi titik masuk

Kemas kini package.json anda untuk menunjuk ke titik masuk CommonJS anda.

"main": "dist/index.cjs",

Bam! Begitulah, anda kini telah membina pakej anda untuk CommonJS. Ini akan berfungsi walaupun anda mempunyai kebergantungan ESM kerana kebergantungan akan digabungkan
bersama pakej anda.

Kebergantungan disertakan dalam output kerana himpunan medan: benar apabila esbuild dipanggil.

Pengisytiharan TypeScript

Walaupun secara teknikalnya tidak diperlukan, anda berkemungkinan besar juga mahukan pengisytiharan TypeScript yang malangnya esbuild tidak dikeluarkan pada masa ini. Jadi untuk menjana
itu, anda akan mahu menggunakan tsc biasa.

Kemas kini tsconfig.json anda

Menambah pilihan ini pada fail tsconfig.json anda akan menyebabkan hanya pengisytiharan TypeScript dikeluarkan. Inilah yang kami mahukan sejak pakej yang lain
sedang dibina dengan esbuild.

"declaration": true,
"declarationDir": "./dist",
"emitDeclarationOnly": true

Kemas kini skrip binaan anda

"scripts": {
  "build:tsc": "yarn tsc -p tsconfig.json",
  "build": "vite-node ./scripts/build.ts && yarn build:tsc",
}

Dwi Titik Masuk

Panduan ini mengesyorkan hanya mengeluarkan satu titik masuk CommonJS tunggal untuk pakej anda. Secara peribadi, saya rasa ini adalah pilihan terbaik untuk dua sebab:

• Meminimumkan saiz berkas
• Mengelakkan bahaya dwi pakej

Walau bagaimanapun, ini bukan satu-satunya pilihan. Anda juga boleh menerbitkan pakej anda dengan dwi titik masuk untuk CommonJS dan ESM.

Kemas kini skrip binaan anda untuk memasukkan binaan ESM

import esbuild from 'esbuild'

const entrypoint = "<your entrypoint here>"
const tsconfig = "<your tsconfig path here>"

const build = async () => {
  await Promise.all([
    // bundle for commonjs
    esbuild.build({
      entryPoints: [entrypoint],
      bundle: true,
      minify: true,
      format: 'cjs',
      outfile: `./dist/index.cjs`,
      platform: 'node',
      treeShaking: true,
      tsconfig,
    }),
    // bundle for ESM
    esbuild.build({
      entryPoints: [entrypoint],
      bundle: true,
      minify: true,
      format: 'esm',
      outfile: `./dist/index.js`,
      platform: 'node',
      treeShaking: true,
      tsconfig,
    }),
  ])
}

build()

Kemas kini fail package.json anda untuk memasukkan dwi titik masuk

"main": "dist/index.cjs",
"module": "dist/index.js",
"type": "module",
"exports": {
  ".": {
    "import": "./dist/index.js",
    "require": "./dist/index.cjs",
    "types": "./dist/index.d.ts"
  }
},

Kod sumber

Atas ialah kandungan terperinci Membina pakej NPM untuk CommonJS dengan kebergantungan ESM. Untuk maklumat lanjut, sila ikut artikel berkaitan lain di laman web China PHP!