pika-plugin-inline-env

Note: this plugin in intended to be used with @pika/plugin-ts-standard-pkg. If you're using @pika/plugin-standard-pkg see that section for more details.

A really simple, tiny pika plugin to inline process.env environment variables in dist-src so downstream builds don't become bloated with extra rollup plugins or custom solutions.

Problem

Using the standard ts plugin from pika, there's no way to inline/inject environment variables in the generated dist-src folder. For example:

// some other code...
export const VERSION = process.env.VERSION;

after tsc generates the bundle used by the node/web/umd builder, we're left with dist-src/index.js containing something like:

// some other code...
export const VERSION = process.env.VERSION;

There are two issues here:

1. App authors using bundlers like Webpack have no way of knowing the version of your library
2. If a UMD distribution exists for your library, rollup doesn't replace the variable for free

How it Works

This plugin works by reading your dist-src/index.js (or other configured file) file using node fs, performing a simple search and replace and writing the file back to disk. All operations are blocking so make sure there are no other operations on the same file while the plugin is executing.

Install

npm i @pika/pack pika-plugin-inline-env --save-dev

Usage

Note: All items under the env array are considered to live on process.env therefore you can omit process.env if you wish.

{
    "name": "example-package-json",
    "version": "1.0.0",
    "@pika/pack": {
        "pipeline": [
            ["@pika/plugin-ts-standard-pkg"],
            [
                "pika-plugin-inline-env",
                {
                    "env": ["npm_package_version", "process.env.DEBUG"]
                }
            ]
        ]
    }
}

and to build:

DEBUG=false && npx pika build

Tip: use cross-env to ensure this works on windows too

cross-env MY_VERSION=1.2.3 && npx pika build

At the env of the build, we'll be left with a clean, inline environment variable in dist-src/index.js:

// other code...
export const VERSION = '1.2.3';

For more information about @pika/pack & help getting started, check out the main project repo.

Options

All options are optional.

| Option | Type | Default Value | Description | | ------------ | ------------------------------------------------------------------------------------------- | ------------- | ----------------------------------------------------------------------------------------------- | | "env" | string[] | [] | An array of env variables to replace. If it does not exist an empty string will be used instead | | "debug" | boolean | 'trace' | false | Set true to enable debugging info on build failures | | "encoding" | BufferEncoding | 'utf-8' | Override the file read and write encoding | | "bail" | boolean | false | If an environment variable is missing, fail the build | | "file" | string | 'index.js' | Override the file to read and write to |

Using with @pika/plugin-standard-pkg

This is not intended to be used with @pika/plugin-standard-pkg, use babel-plugin-transform-inline-environment-variables to inline environment variables using the standard packager.

Gotchas

Passing environment variables from NPM scripts has some issues. Considering the following:

{
    "scripts": {
        "build": "pika build",
        "pretest": "MY_VAR=1.2.3 npm run build",
        "test": "node test/assert.js"
    }
}

I suspect npm run is launched in a new child process. The solution is to place the env vars on the same line:

{
    "scripts": {
-        "build": "pika build",
+        "build": "MY_VAR=1.2.3 pika build",
-        "pretest": "MY_VAR=1.2.3 npm run build",
+        "pretest": "npm run build",
        "test": "node test/assert.js"
    }
}

or, cross-env-shell can be used:

{
    "scripts": {
-        "build": "pika build",
+        "build": "cross-env-shell pika build",
-        "pretest": "MY_VAR=1.2.3 npm run build",
+        "pretest": "cross-env MY_VAR=1.2.3 npm run build",
        "test": "node test/assert.js"
    }
}