ライブラリとしての出力形態についての考察
ライブラリを作る際に構文の変換とponyfillをどこまでやるべきかで迷ったので、調べたり試した結果をまとめて考察してみる。
polyfillに関してはそもそも、そのメソッドやオブジェクトがコードで使われているかという静的に決定できる部分と、そのメソッドやオブジェクトが実行環境に存在するかという動的にしか決定できない部分とがあり、実行環境に存在しないもののみを読ませたいという場合は polyfill.io などを利用して動的に解決するしかないため、ここではpolyfillを含むライブラリを作る際にどの程度browserslistによるターゲットの指定に即した静的な出力が得られるのかについて見ていく。 構文の変換について
@rollup/plugin-babel にもあるように、アプリのビルドでは少なくとも構文の変換についてはアプリのコードのみを対象とするのが理想的で、ライブラリの作者は利用者がライブラリ中の .ts をコンパイルする必要がないようにすべきなのと同様に、esmを除くes6以上の構文を含む .js を配布すべきでないというのはおそらくかなり正しい主張だと思われる。
実際に babel-loader では基本的に exclude: /node_modules/ とするし、Reactも依存しているes6の Map や Set はpolyfillで補うこととしているが構文に関してはes5に変換して提供している。
microbundle や @babel/preset-modules の例のように、esm以降向けの形式も追加で配布しているライブラリもある。
この場合は main か browser にes5相当の形式を指定し、module にesm以降向けの形式を指定することが多い。
module は非標準のプロパティだが、webpackなど多くのバンドラはこれを考慮して扱うファイルを変えている。
ちなみにwebpack@5はNode.jsでもサポートされている exports プロパティによる指定にも対応している。
このあたりの設定は、microbundle の実装や preact の package.json を参考にするのがよさそう。
Node.js向けに main と exports.require を、ブラウザ向けに module と exports.browser を一致させる感じか。
ちなみに main などと違い exports に記述するパスは ./ から始める必要があるようだ。`
構文の変換は @babel/preset-modules の機能も bugfixes: true で有効にできる @babel/preset-env で行う。
対象は browserslist で設定し、例えば > 0.2%, not dead, not op_mini all, not ie 11 のようにする。
上述のように複数の形式で配布する場合は、babelもbrowserslistも NODE_ENV で設定を切り替えられるのでこれを利用する。
もしくは @babel/preset-env の targets で直接browserslistと同じ形式で対象を指定する。
アプリの場合は @babel/preset-env の useBuiltIns: "usage" と corejs でpolyfillを入れるが、これはグローバルスコープを汚染するためライブラリではまず設定せず、後述するようにグローバルスコープを汚染しないponyfillで考える。
@babel/plugin-transform-runtime と @babel/runtime でサイズを抑制でき、後述するがここでもponyfillを扱える。
@babel/preset-env が regenerator-runtime を必要とするコードを生成する場合は、microbundle でも使われている babel-plugin-transform-async-to-promises を使うと大抵は回避できる。
ponyfillの同梱について
しかしこれは理想論であり、後述するように無駄も多いため利用者にグローバルにpolyfillしてもらう方がよさそうに思える。
実際に core-js を dependencies に持つライブラリは稀で、前述したようにReactもponyfillまではやっていない。
ponyfillの同梱は @babel/plugin-transform-runtime と @babel/runtime-corejs3 の併用や babel-plugin-polyfill-corejs3 と core-js-pure@3 の併用などで実現できるが、前者は useBuiltIns: "usage" 相当の挙動はするもののbrowserslistの設定は無視するためこれを改善した後者を method: "usage-pure" で利用するのがよい。
しかしこれでもcore-jsのファイル構成の関係で new Promise(r => ...) などとしただけで Promise.allSettled() のponyfillも読み込まれてしまうため、browserslistの設定を見て可能なら exclude: ["es.promise"] のようにするとよい。
一応core-jsはネイティブのものが使える場合はそれを使うそうだが、例えば Object.fromEntries() を使うとbrowserslistの設定に関わらず array.keys() までponyfillされてしまったりと無駄が多く、気にしていてもサイズは簡単に増えてしまう。
まとめと考察
ここまでで構文に関してはes5相当に変換しpolyfillに関しては利用者に対応してもらうのがよさそうという結論になった。
これは構文の変換で問題が生じた場合はかなり手間だが、polyfillに関しては比較的対応しやすいという事実とも符号している。
ちなみにライブラリをバンドルすべきかについては、バンドルすると <script> で読ませやすくなるがアプリで利用する場合には最適化が効きにくくなるなど一長一短であり、両方の形式で配布している場合もある。
ついでにとりあえずこんな感じになると思いますという設定も貼っておく。
これで lib に型定義とesm形式の lib/index.module.js とcjs形式の lib/index.js が吐かれる。
code:package.json
{
"main": "lib/index.js",
"module": "lib/index.module.js",
"types": "lib/index.d.ts",
"exports": {
"browser": "./lib/index.module.js",
"require": "./lib/index.js"
},
"scripts": {
"build": "rollup -c",
},
"devDependencies": {
"@babel/core": "^7.12.3",
"@babel/preset-env": "^7.12.1",
"@rollup/plugin-babel": "^5.2.1",
"babel-plugin-transform-async-to-promises": "^0.8.15",
"rollup": "^2.33.2",
"rollup-plugin-typescript2": "^0.29.0",
"typescript": "^4.0.5"
},
}
code:rollup.config.js
import typescript from "rollup-plugin-typescript2";
import { getBabelOutputPlugin } from "@rollup/plugin-babel";
export default {
input: "src/index.ts",
output: [
{
file: "lib/index.module.js",
format: "es",
plugins: [
getBabelOutputPlugin({
presets: "@babel/env", { bugfixes: true },
}),
],
},
{
file: "lib/index.js",
format: "cjs",
plugins: [
getBabelOutputPlugin({
presets: "@babel/env", { ignoreBrowserslistConfig: true },
}),
],
},
],
};
code:tsconfig.json
{
"compilerOptions": {
"target": "esnext",
"module": "esnext",
"declaration": true,
"strict": true,
"esModuleInterop": true,
"skipLibCheck": true,
"forceConsistentCasingInFileNames": true,
"newLine": "lf" // for rollup-plugin-typescript2
},
"include": "src/**/*", // for rollup-plugin-typescript2 }
おまけ
browserslistでは supports es6-module でesmに対応している環境を指定できる
@babel/preset-env は ignoreBrowserslistConfig: true でbrowserslistの設定を無視し単純にes5に変換できる
メソッドやオブジェクトがpolyfillの対象かは eslint-plugin-compat で確認できる
browserslistの設定も読み、互換性については caniuse-db と mdn-browser-compat-data の両方を見る
@babel/plugin-transform-runtime と @babel/runtime によるサイズの抑制は、tsc でビルドしている場合も tslib と "importHelpers": true で同様の効果が得られる。
@rollup/plugin-typescript は型定義を作らないため microbundle も rollup-plugin-typescript2 を使っている
rollup-plugin-typescript2 も import type は無視するが "include": ["src/**/*"] などで回避できる
tsc は --declaration --emitDeclarationOnly --declarationDir で指定した場所に型定義だけを吐ける
制約がありバンドラの対応状況もまちまちだが package.json の sideEffects である程度Tree Shakingを制御できる