Node エミュレーション

Parcel には、Node.js API をエミュレートする機能がいくつか含まれています。 これにより、元々 Node 用に書かれた npm 上の多くのモジュールをブラウザでも動作させることができます。 さらに、多くのブラウザモジュールも、環境変数など、Node.js ベースの API を採用しています。

環境変数

Parcel は、JavaScript での環境変数のインライン化をサポートしています。 これは、ビルド環境 (例: 開発、ステージング、本番) の判別、API キーの挿入などに使用できます。

環境変数にアクセスするには、process.env オブジェクトから対応するプロパティを読み取ります。

if (process.env.NODE_ENV === 'development') {
  console.log('Happy developing!');
}

分割代入構文を使用して、一度に複数のプロパティにアクセスすることもできます。

let {NODE_ENV, API_TOKEN} = process.env;

process.env に対する非静的なアクセス方法 (例: 動的なプロパティルックアップ) はサポートされていません。

NODE_ENV

NODE_ENV 環境変数は、Parcel によってモードに応じて自動的に設定されます。 parcel build を実行すると、NODE_ENV はデフォルトで production に設定されます。それ以外の場合は development に設定されます。 これは、NODE_ENV を自分で設定することで上書きできます (例: シェルで)。

.env ファイル

Parcel は、プロジェクトルートの .env ファイルで定義された環境変数の読み込みをサポートしています。 これは、改行で区切られた NAME=value のペアをサポートしています。 # で始まる行はコメントとして扱われます。 詳細については、dotenv を参照してください。

APP_NAME=test
API_KEY=12345

.env に加えて、.env.production や .env.development などの環境固有の上書きも作成できます。 これらは、NODE_ENV 環境変数に基づいて適用されます (Parcel によって自動的に設定される場合も含む)。 環境固有の上書きで設定されていない変数は、ベースの .env ファイルで定義された値にフォールバックします。

.env.local ファイルは、環境変数のローカル上書きにも対応していますが、NODE_ENV=test の場合は使用されません。そのため、テストはすべての人にとって同じ結果を生成します。 これは、.env.production.local などの環境固有の上書きでもサポートされています。

組み込み Node モジュールのポリフィルと除外

ブラウザをターゲットにしていて、コード、または依存関係が crypto、fs、process などの組み込み Node モジュールをインポートする場合、Parcel は自動的に次のポリフィルのいずれかを使用します。 ポリフィルが利用できない場合は、代わりに空のモジュールが使用されます。 エイリアス を使用して、これらを上書きすることもできます。

組み込み Node グローバルのシミング

ブラウザをターゲットにしている場合、Node で利用可能なグローバル変数の使用は、Node 用に書かれたコードを壊さないように置き換えられます。

• process は、process モジュールから自動的にインポートされます。ただし、process.browser または process.env.FOO 式の一部である場合は、ブール値または環境変数の値に置き換えられます。

• Buffer は、buffer モジュールから自動的にインポートされます。

• __filename と dirname は、プロジェクトルートを基準としたアセットのファイルパス (または親フォルダ) の文字列リテラルに置き換えられます。

• global は、グローバル変数への参照に置き換えられます (新しい globalThis のように動作します)。

fs.readFileSync のインライン化

fs.readFileSync への呼び出しは、ファイルパスが静的に決定可能で、プロジェクトルート内にある場合、ファイルの内容に置き換えられます。

• fs.readFileSync(__dirname + "/file", "utf8") – ファイルの内容を文字列として。 "utf8"、 "utf-8"、 "hex"、 "base64" のエンコーディングがサポートされています。
• fs.readFileSync(__dirname + "/file") – Buffer オブジェクト。 Buffer ポリフィルはかなり大きいので、これは望ましくない場合があります。

__dirname 変数と __filename 変数は、ファイル名引数で使用できます。 + 演算子と path.join 関数による文字列連結を使用できます。 他の関数、変数、または動的な計算はサポートされていません。 計算されたパスは常に絶対パスであり、現在の作業ディレクトリに依存しないようにする必要があります。

import fs from "fs";
import path from "path";

const data = fs.readFileSync(path.join(__dirname, "data.json"), "utf8");
console.log(data);

{
  "foo": "bar"
}

これらの機能の無効化

環境変数 と readFileSync 呼び出し のインライン化は、package.json に @parcel/transformer-js キーを作成することで無効にできます。

{
  "name": "my-project",
  "dependencies": {
    ...
  },
  "@parcel/transformer-js": {
    "inlineFS": false,
    "inlineEnvironment": false
  }
}

inlineEnvironment は、許可された環境変数をフィルタリングできる glob 文字列の配列にすることもできます。 これは、node_modules のサードパーティコードも環境変数を読み取ることができるため、セキュリティを確保するための良い方法です。

{
  "name": "my-project",
  "dependencies": {
    ...
  },
  "@parcel/transformer-js": {
    "inlineEnvironment": ["SENTRY_*"]
  }
}