@hyperse/hyper-env

Runtime Environment Configuration

Populates your environment from .env files at run-time rather than build-time.

• Supports multiple .env files.

README

• Examples

• Getting started

• .env file order of priority

• Common use cases

  • Environment specific config
  • Specifing an env file
  • Specifing an prefix for white-listed environment variables
  • Docker for next.js

• Arguments and parameters

Examples

• Example using Next.js (see file)

Getting started

1# .env
2NEXT_APP_NEXT="Next.js"
3NEXT_APP_CRA="Create React App"
4NEXT_APP_NOT_SECRET_CODE="1234"

.env file order of priority

We have implemented some sane defaults that have the following order of priority:

1. {path-to-file} // from the --path, -p argument
2. .env.{key} // from the --env, -e argument
3. .env.local
4. .env

Your config is available in process.env on the server. We suggest you add .env.local to .gitignore.

Common use cases

Environment specific config

Frameworks such as Next allow for some nice defaults such as .env.local, .env.production, .env. This has the limitation where you may want to run your app in different environments such as "staging, integration, qa" but still build a "production" app with NODE_ENV=production. With hyper-env this is possible:

1# .env.staging
2NEXT_APP_API_HOST="api.staging.com"
3# .env.production
4NEXT_APP_API_HOST="api.production.com"
5# .env.qa
6NEXT_APP_API_HOST="api.qa.com"
7# .env.integration
8NEXT_APP_API_HOST="api.integration.com"
9# .env.local
10NEXT_APP_API_HOST="api.example.dev"
11# .env
12NEXT_APP_API_HOST="localhost"

for staging you would simply set APP_ENV=staging where you run your app:

{
  ...
  "scripts": {
    "start": "hyper-env --env APP_ENV -- next start" // where .env.${APP_ENV}
  }
  ...
}

Thus NEXT_APP_API_HOST=api.staging.com in your staging environment.

Please keep in mind that you have to pass the name of an environment variable to --env, not the value of it.

• ✔ valid usage (macOS): APP_ENV=staging hyper-env --env APP_ENV -- next start
• ❌ common mistake: hyper-env --env staging -- next start

Specifing an env file

You are also able to specify the path to a specific env file:

{
  ...
  "scripts": {
    "start": "hyper-env --path config/.env.defaults -- next start"
  }
  ...
}

You can use any combination of these two arguments along with the default .env, .env.local to build your runtime config.

Specifing an prefix for white-listed environment variables

You are also able to specify the prefix of white-listed environment variables:

{
  ...
  "scripts": {
    "start": "hyper-env -- next start"
  }
  ...
}

1# .env
2NEXT_APP_NEXT="Next.js"
3NEXT_APP_CRA="Create React App"
4NEXT_APP_NOT_SECRET_CODE="1234"

Arguments and parameters

1$ hyper-env <args> -- <command>

• <command>

You may pass a command, such as a nodejs entry file to the hyper-env cli tool. For example hyper-scripts, next dev, next start

• --env, -e (default: APP_ENV)

Specify the name of an existing environment variable, whose value is the name of an environment you want, to make hyper-env parse an environment specific env-file. For example, you may set APP_ENV=staging first and then apply --env APP_ENV flag. hyper-env would load .env.staging, .env.local, .env in that order with the latter taking priority.

• --path, -p (default: '')

As a significant breaking change we have dropped the ability to specify specific files via the --env argument. This argument now specifies environment file to be parsed depending on the running environment. For example --env APP_ENV or -e APP_ENV where APP_ENV=staging reads in .env.staging. It is very common for platforms to have staging, qa, integration environments that are still built in "production" mode with NODE_ENV=production. This allows for that usecase and many others.

Depandand command is now in the format hyper-env <args> -- <command>

docker next.js examples

Dockerfile

1FROM node:18-alpine AS base
2
3# Install dependencies only when needed
4FROM base AS deps
5# Check https://github.com/nodejs/docker-node/tree/b4117f9333da4138b03a546ec926ef50a31506c3#nodealpine to understand why libc6-compat might be needed.
6# RUN apk add --no-cache libc6-compat --repository https://mirrors.aliyun.com/ubuntu/
7RUN apk add --no-cache libc6-compat
8
9ENV LC_ALL zh_CN.UTF-8
10
11WORKDIR /opt
12
13RUN npm config set registry  https://registry.npmmirror.com
14
15# Install dependencies based on the preferred package manager
16COPY package.json yarn.lock* .yarnrc.yml package-lock.json* pnpm-lock.yaml* ./
17COPY .yarn/releases/ ./.yarn/releases/
18
19RUN \
20  if [ -f yarn.lock ]; then yarn --immutable; \
21  elif [ -f package-lock.json ]; then npm ci; \
22  elif [ -f pnpm-lock.yaml ]; then yarn global add pnpm && pnpm i --frozen-lockfile; \
23  else echo "Lockfile not found." && exit 1; \
24  fi
25
26
27# Rebuild the source code only when needed
28FROM base AS builder
29WORKDIR /opt
30COPY --from=deps /opt/node_modules ./node_modules
31COPY . .
32
33# Next.js collects completely anonymous telemetry data about general usage.
34# Learn more here: https://nextjs.org/telemetry
35# Uncomment the following line in case you want to disable telemetry during the build.
36# ENV NEXT_TELEMETRY_DISABLED 1
37# RUN yarn generate
38
39RUN yarn build-docker
40# If using npm comment out above and use below instead
41# RUN npm run build
42
43# Production image, copy all the files and run next
44FROM base AS runner
45RUN apk add --no-cache curl
46WORKDIR /opt
47
48ENV NODE_ENV production
49# Uncomment the following line in case you want to disable telemetry during runtime.
50# ENV NEXT_TELEMETRY_DISABLED 1
51
52# RUN addgroup --system --gid 1001 nodejs
53# RUN adduser --system --uid 1001 nextjs
54RUN addgroup --system --gid 700 op
55RUN adduser --system --uid 700 op
56
57# COPY --from=builder /opt/public ./public
58
59# Set the correct permission for prerender cache
60RUN mkdir .next
61RUN chown op:op .next
62
63# Automatically leverage output traces to reduce image size
64# https://nextjs.org/docs/advanced-features/output-file-tracing
65COPY --from=builder --chown=op:op /opt/.next/standalone ./
66COPY --from=builder --chown=op:op /opt/.next/static ./.next/static
67
68USER op
69
70# 无需修改
71EXPOSE 8080
72
73ENV PORT 8080
74# set hostname to localhost
75ENV HOSTNAME "0.0.0.0"
76COPY start.sh /opt/start.sh
77USER root
78RUN chmod +x /opt/start.sh
79USER op
80# server.js is created by next build from the standalone output
81# https://nextjs.org/docs/pages/api-reference/next-config-js/output
82CMD sh start.sh

packages.json scripts

1"scripts": {
2    "dev": "APP_ENV=rc hyper-env -- next dev",
3    "build": "next build",
4    "build-docker": "cross-env NEXT_BUILD_ENV_OUTPUT=standalone next build && hyper-next-standalone",
5    "g:changeset": "changeset",
6    "g:cz": "cz",
7    "g:fix-all-files": "eslint . --ext .ts,.tsx,.js,.jsx,.cjs,.mjs,.mdx,.graphql --fix",
8    "g:lint-staged-files": "lint-staged --allow-empty",
9    "g:version": "changeset version",
10    "postinstall": "is-ci || yarn husky install",
11    "localbuild": "next build",
12    "start": "APP_ENV=prod hyper-env -- next start",
13    "start:integration": "APP_ENV=integration hyper-env -- next start",
14    "start:prod": "APP_ENV=prod hyper-env -- next start",
15    "start:rc": "APP_ENV=rc hyper-env -- next start",
16    "docker": "APP_ENV=prod ./node_modules/@hyperse/hyper-env/bin/hyper-env.mjs -- node server.js",
17    "docker:integration": "APP_ENV=integration ./node_modules/@hyperse/hyper-env/bin/hyper-env.mjs -- node server.js",
18    "docker:prod": "APP_ENV=prod ./node_modules/@hyperse/hyper-env/bin/hyper-env.mjs -- node server.js",
19    "docker:rc": "APP_ENV=rc ./node_modules/@hyperse/hyper-env/bin/hyper-env.mjs -- node server.js"
20  },

start.sh

1# sleep 100000
2exec npm run docker:${DeployEnv}
3

Next runtime env

packages.json

1"next-runtime-env": "^3.2.2",

Note Environment Variables of next.js

next.js Bundling Environment Variables for the Browser at build time

• https://nextjs.org/docs/pages/building-your-application/configuring/environment-variables
• hyper-env only attach Environment Variables on processs.env
• we need to expose runtime env variables via next-runtime-env, otherwise we can not correct use these env variables in browser
• If you use _pages router you must be use SSR mode.

1import { GetServerSideProps } from 'next';
2import { HealthClient } from './client';
3
4// Must be declared as SSR for 'next-runtime-env';
5export const getServerSideProps: GetServerSideProps = async () => {
6  return {
7    props: {},
8  };
9};
10
11export default function EnvPage() {
12  return (
13    <div>
14      <HealthClient />
15    </div>
16  );
17}

1// client.tsx
2'use client';
3
4import { env } from 'next-runtime-env';
5
6export default () => {
7  return (
8    <div>
9      <p>Client env:</p>
10      <div>
11        <p>NEXT_PUBLIC_ENV(env): {env('NEXT_PUBLIC_ENV')}</p>
12        <p>NEXT_PUBLIC_TEXT(process): {process.env.NEXT_PUBLIC_TEXT}</p>
13      </div>
14    </div>
15  );
16};

1// _app.tsx
2
3import { PublicEnvScript } from 'next-runtime-env';
4
5<PublicEnvScript />;