Compile-time Transform

Please read the guide for how to use these plugins.

Plugin Options

All compile-time transform plugins use the same options:

interface PluginOptions {
  /**
   * The .env file path to load
   *
   * You can out-out this by passing an empty string
   *
   * @default ".env"
   */
  env?: string;

  /**
   * The public .env example file path to load
   */
  example: string;

  /**
   * Compile-time: statically replace `import.meta.env.KEY` with `"value"`
   * Runtime: statically replace `import.meta.env` with a global accessor
   *
   * @default
   * Generally speaking, `process.env.NODE_ENV === "production" ? "runtime" : "compile-time"`
   */
  transformMode?: "compile-time" | "runtime";
}

Babel Plugin

Installation

$ npm i -D @import-meta-env/babel

Setup

{
  "plugins": [
    [
      "module:@import-meta-env/babel",
      pluginOptions
    ]
  ]
}

Related examples: babel, babel-loader, jest

SWC Plugin

Installation

$ npm i -D @import-meta-env/swc

Setup

.swcrc:

{
  "$schema": "https://json.schemastore.org/swcrc",
  "jsc": {
    "experimental": {
      "plugins": [
        [
          "@import-meta-env/swc",
          pluginOptions
        ]
      ]
    }
  }
}

Related examples: swc

Unplugin

Installation

$ npm i -D @import-meta-env/unplugin

Setup

ESbuild

// esbuild.config.js
const { build } = require("esbuild");
const importMetaEnv = require("@import-meta-env/unplugin");

build({
  plugins: [importMetaEnv.esbuild(pluginOptions)],
});

Related examples: esbuild

Farm

// farm.config.ts
import { defineConfig } from "@farmfe/core";
import importMetaEnv from "@import-meta-env/unplugin";

export default defineConfig({
  plugins: [importMetaEnv.farm(pluginOptions)],
});

Related examples: farm

Rollup

// rollup.config.js
import ImportMetaEnvPlugin from "@import-meta-env/unplugin";

export default {
  plugins: [ImportMetaEnvPlugin.rollup(pluginOptions)],
};

Related examples: rollup

Vite

// vite.config.ts
import ImportMetaEnvPlugin from "@import-meta-env/unplugin";

export default {
  plugins: [ImportMetaEnvPlugin.vite(pluginOptions)],
};

Related examples: vite

Webpack

// webpack.config.js
const ImportMetaEnvPlugin = require("@import-meta-env/unplugin");

module.exports = {
  plugins: [ImportMetaEnvPlugin.webpack(pluginOptions)],
};

Related examples: webpack

Rspack

// rspack.config.js
const ImportMetaEnvPlugin = require("@import-meta-env/unplugin");

module.exports = {
  plugins: [ImportMetaEnvPlugin.rspack(pluginOptions)],
};

Related examples: rspack

Compatibility

Currently we support Babel plugin, SWC plugin and Unplugin (an unified plugin system for Vite, Rollup, Webpack, and more) transforms. If your toolchain is not supported, please feel free to file an issue on GitHub.

You can choose one of these or combine multiple plugins, for example if you are using Webpack 5 and Jest:

1. You can use babel-loader + Babel plugin for development, testing and production.
2. Alternatively, you can use Unplugin for development and production, and babel-jest + Babel plugin for testing.
3. Alternatively, you can use the swc-loader and SWC plugin for development and production, and the babel-jest and Babel plugin for testing.

WARNING

There are some exceptions:

1. Vite is only compatible with Unplugin.
2. Webpack 4 is not compatible with Unplugin.