jit-env-webpack-plugin

Injects .env.json files into the web application for development and adds an injection point for just-in-time injection when used in production.

Install

npm i @weavedev/jit-env-webpack-plugin

Why‽

The reason we created this plugin is that we want our staging containers to be used in production without having to rebuild them. This plugin adds a bit of code that allows you to inject a JSON env into your project with minimal effort when used in production. It also allows you to inject your local env files while developing locally.

Usage

webpack.config.js

1const HtmlWebpackPlugin = require('html-webpack-plugin');
2const JitEnvWebpackPlugin = require('@weavedev/jit-env-webpack-plugin');
3
4module.exports = {
5  plugins: [
6    new HtmlWebpackPlugin(),
7    new JitEnvWebpackPlugin(),
8  ],
9};

Options

JitEnvWebpackPlugin provides the following options.

1new JitEnvWebpackPlugin({
2    /**
3     * The default env file to use. This is usefull if you want to provide an
4     * example structure or provide a default config to a testing environment.
5     * This config is also used when generating type definitions with the
6     * `emitTypes` option.
7     */
8    defaultEnv: "./default.env.json",
9
10    /**
11     * The path to a local env file to use. If the file can not be found the
12     * `defaultEnv` file is used and a warning is shown in the browser's
13     * console.
14     *
15     * Add this path to your .gitignore to prevent developers from adding their
16     * local env file to the repository.
17     */
18    userEnv: "./user.env.json",
19
20    /**
21     * Generate a simple TypeScript types file from the `defaultEnv` file. You
22     * may need to import this file somewhere (depending on your TypeScript
23     * configuration) for TypeScript to find the types.
24     *
25     * This file will also export an env object to use if you don't want to use
26     * `window.env` in your project.
27     */
28    emitTypes: "./src/myEnv.ts",
29
30    /**
31     * If the emitted TypeScript types file causes linting issues you can
32     * provide a prefix string that will be added to the `emitTypes` file
33     * before it is emitted.
34     *
35     * You probably don't need this because most linters allow you to exclude
36     * files in the linter's configuration, but it is here if you need it.
37     */
38    emitTypesPrefix: "/* tslint:disable */",
39});

NOTE

These options should really only be used while developing your application. See the full config example below for more details on using JitEnvWebpackPlugin in production.

Usage in code

If we have an env file...

1{
2    "baseUrl": "http://localhost:8001",
3    "devMode": true
4}

...we can use the variables in our code like this:

1if (window.env.devMode) {
2    console.log(`Using dev mode with API: ${window.env.baseUrl}`);
3}

...and in TypeScript like this:

1// Configure this path in the `emitTypes` option
2import { env } from './myEnv.ts';
3
4if (env.devMode) {
5    console.log(`Using dev mode with API: ${env.baseUrl}`);
6}

Emit TypeScript types

You can configure a target path to emit a TypeScript types file that will be generated from the default env file.

By configuring JitEnvWebpackPlugin like this:

1new JitEnvWebpackPlugin({
2    defaultEnv: "./default.env.json",
3    emitTypes: "./src/myEnv.ts",
4});

If your default env file looks like this...

1{
2    "baseUrl": "http://localhost:8001",
3    "devMode": true,
4    "retry": 3,
5    "servers": {
6        "cdn": "http://localhost:8002",
7        "s3": "http://localhost:9000"
8    },
9    "users": [
10        {
11            "name": "Will",
12            "id": 1
13        },
14        {
15            "name": "Matt",
16            "id": 2
17        }
18    ]
19}

...JitEnvWebpackPlugin will generate a TypeScript types file that looks like this:

1// This file was generated by JitEnvWebpackPlugin.
2//
3// If this file causes linting issues, you can pass a linting disable string
4// with the emitTypesPrefix option.
5
6if (window.env === undefined) {
7  throw new Error("[JIT-ENV] Missing env");
8}
9
10export const env: Window['env'] = window.env;
11
12declare global {
13  interface Window {
14    env: {
15      "baseUrl"?: string;
16      "devMode"?: boolean;
17      "retry"?: number;
18      "servers"?: {
19        "cdn"?: string;
20        "s3"?: string;
21      };
22      "users"?: {
23        "name"?: string;
24        "id"?: number;
25      }[];
26    };
27  }
28}
29

Full webpack.config.js example

1const HtmlWebpackPlugin = require('html-webpack-plugin');
2const JitEnvWebpackPlugin = require('@weavedev/jit-env-webpack-plugin');
3
4/**
5 * When building for production you use:
6 * 
7 * webpack --env.production
8 */
9const PROD = env.production;
10
11const jitEnvWebpackPlugin = PROD ? new JitEnvWebpackPlugin() : new JitEnvWebpackPlugin({
12    defaultEnv: "./default.env.json",
13    userEnv: "./user.env.json",
14    emitTypes: "./src/myEnv.ts",
15});
16
17module.exports = {
18  plugins: [
19    new HtmlWebpackPlugin(),
20    jitEnvWebpackPlugin,
21  ],
22};

Replacing in CI/CD or in containers

1# Load path to your env file
2export REPLACE_CONFIG=/path/to/config.env.json
3
4# Load env file contents
5CONFIG=$(cat $REPLACE_CONFIG | tr -d '\n' | tr -d '\r' | sed 's/"/\\"/g' | sed "s/\//\\\\\//g");
6
7# Inject env file contents into your index.html
8sed -i "s/\"___INJECT_ENV___\"/$CONFIG/g" /path/to/index.html;

We use a Dockerfile that mounts a JSON file and uses a script with the above as entrypoint to handle this step.

License

MIT

Made by Paul Gerarts and Weave