🐢 Node Emulation

¶ 🌳 Environment Variables

Parcel uses dotenv to support loading environment variables from .env files.

.env files are to be stored alongside the package.json that contains your parcel-bundler dependency.

Parcel loads .env files with these specific names for the following NODE_ENV values:

Notably:

• NODE_ENV defaults to development.
• .env.local is not loaded when NODE_ENV=test since tests should produce the same results for everyone
• Sometimes introducing a new .env file will not work immediately. Try deleting the .cache/ directory in this case.
• Accessing the process.env object directly is not supported, but accessing specific variables on it like process.env.API_KEY will provide the expected value.
• Use the built-in process Node.js global, i.e. don't do import process from "process". If you use TypeScript, you probably want to install @types/node for it to compile.

¶ 🕳️ Polyfilling & Excluding Builtin Node Modules

When (or more likely a dependency) importing packages such as crypto, fs or process, Parcel will either automatically use one of the listed polyfills and otherwise exclude that module. You can use the aliases field in your package.json

¶ 📄 Inlining fs.readFileSync

Calls to fs.readFileSync are replaced with the file's contents if the filepath is statically determinable and inside the project root

• fs.readFileSync(..., "utf8"): with the contants as string with (or any other valid encoding)
• fs.readFileSync(...): a Buffer object (e.g. Buffer.from(....) together with the an potentionally necessary polyfill)

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

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

{
  "foo": "bar"
}

¶ 🔧 Disabling These Features

Inlining of environment variables and readFileSync calls can be disabled via a @parcel/transformer-js key in package.json:

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

inlineEnvironment can also be an array of glob strings:

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

inlineFS applies to readFileSync calls and inlineEnvironment to process.env.SOMETHING:

{
  inlineFS: boolean,
  inlineEnvironment: boolean | Array<Glob>
}

(This functionality is provided by @parcel/transformer-js and @parcel/resolver-default.)