Merge pull request #2 from expatfile/development

chore: 🔖 release stable version

Author: HofmannZ

.eslintrc.js

@@ -1,49 +1,49 @@
 module.exports = {
   root: true,
-  parser: "@typescript-eslint/parser",
+  parser: '@typescript-eslint/parser',
   extends: [
-    "airbnb-base",
-    "plugin:@typescript-eslint/recommended",
-    "prettier",
-    "plugin:prettier/recommended",
+    'airbnb-base',
+    'plugin:@typescript-eslint/recommended',
+    'prettier',
+    'plugin:prettier/recommended',
   ],
   parserOptions: {
     ecmaVersion: 2020,
-    sourceType: "module",
+    sourceType: 'module',
   },
   env: {
     node: true,
     jest: true,
   },
   rules: {
-    "eol-last": ["error", "always"],
-    "no-plusplus": ["error", { allowForLoopAfterthoughts: true }],
-    "import/extensions": ["off"],
-    "import/prefer-default-export": ["off"],
-    "simple-import-sort/imports": "warn",
-    "simple-import-sort/exports": "warn",
-    "@typescript-eslint/no-empty-interface": ["off"],
-    "@typescript-eslint/explicit-function-return-type": ["off"],
+    'eol-last': ['error', 'always'],
+    'no-plusplus': ['error', { allowForLoopAfterthoughts: true }],
+    'import/extensions': ['off'],
+    'import/prefer-default-export': ['off'],
+    'simple-import-sort/imports': 'warn',
+    'simple-import-sort/exports': 'warn',
+    '@typescript-eslint/no-empty-interface': ['off'],
+    '@typescript-eslint/explicit-function-return-type': ['off'],
   },
   overrides: [
     {
-      files: ["src/__mocks__/.*", "**/*.spec.ts"],
+      files: ['src/__mocks__/.*', '**/*.spec.ts'],
       rules: {
-        "import/no-extraneous-dependencies": [
-          "error",
+        'import/no-extraneous-dependencies': [
+          'error',
           { devDependencies: true },
         ],
-        "@typescript-eslint/no-empty-function": ["off"],
-        "@typescript-eslint/no-non-null-assertion": ["off"],
+        '@typescript-eslint/no-empty-function': ['off'],
+        '@typescript-eslint/no-non-null-assertion': ['off'],
       },
     },
   ],
   settings: {
-    "import/resolver": {
+    'import/resolver': {
       node: {
-        extensions: [".js", ".ts"],
+        extensions: ['.js', '.ts'],
       },
     },
   },
-  plugins: ["simple-import-sort"],
+  plugins: ['simple-import-sort'],
 };

.releaserc.yaml

@@ -1,29 +1,29 @@
 branches:
-  - main
-  - name: development
-    prerelease: alpha
-    channel: alpha
+- main
+- name: development
+  prerelease: alpha
+  channel: alpha
 
 plugins:
-  - - "@semantic-release/commit-analyzer"
-    - preset: angular
-      releaseRules:
-        - scope: no-release
-          release: false
-        - type: build
-          release: patch
-        - type: chore
-          release: patch
-        - type: ci
-          release: false
-        - type: docs
-          release: false
-        - type: style
-          release: patch
-        - type: refactor
-          release: patch
-        - type: test
-          release: patch
-  - - "@semantic-release/release-notes-generator"
-  - - "@semantic-release/npm"
-  - - "@semantic-release/github"
+- - "@semantic-release/commit-analyzer"
+  - preset: angular
+    releaseRules:
+    - scope: no-release
+      release: false
+    - type: build
+      release: patch
+    - type: chore
+      release: patch
+    - type: ci
+      release: false
+    - type: docs
+      release: false
+    - type: style
+      release: patch
+    - type: refactor
+      release: patch
+    - type: test
+      release: patch
+- - "@semantic-release/release-notes-generator"
+- - "@semantic-release/npm"
+- - "@semantic-release/github"

README.md

@@ -1,28 +1,34 @@
 # next-runtime-env - Runtime Environment Configuration
 
-[![codecov](https://codecov.io/gh/expatfile/next-runtime-env/branch/main/graph/badge.svg?token=mbGgsweFuP)](https://codecov.io/gh/expatfile/next-runtime-env)
+![GitHub branch checks state][build-url] [![codecov][cov-img]][cov-url]
 
 Populates your environment at **run-time** rather than **build-time**.
 
 - Isomorphic - Server, browser and middleware compatible.
 - Supports static site generation.
-- Supports `.env`, just like [Next.js](https://nextjs.org/docs/basic-features/environment-variables).
+- Supports `.env`, just like [Next.js][nextjs-env-vars].
 
-Runtime environment variables are used in common best-practice patterns for building modern apps deployed via Docker. A big selling point of using Docker to begin with is to be able to build one image and have it work everywhere - dev, test, staging, production, etc - and having to "bake" in environment-specific configuration at build-time is antithetical to that goal. `next-runtime-env` aims to remove this hurdle by adding support for runtime environment variables to Next.js without sacrificing static site generation support.
+Runtime environment variables are used in common best-practice patterns for
+building modern apps deployed via Docker. A big selling point of using Docker to
+begin with is to be able to build one image and have it work everywhere - dev,
+test, staging, production, etc - and having to "bake" in environment-specific
+configuration at build-time is antithetical to that goal. `next-runtime-env`
+aims to remove this hurdle by adding support for runtime environment variables
+to Next.js without sacrificing static site generation support.
 
 ### Getting started 🚀
 
 1. Add the following lines to your `next.config.js`:
 
 ```js
-const {
-  configureRuntimeEnv,
-} = require('next-runtime-env/build/configure-runtime-env');
+const { configureRuntimeEnv } = require('next-runtime-env/build/configure');
 
 configureRuntimeEnv();
 ```
 
-This will generates a `__ENV.js` file that contains allow-listed environment variables that have a `NEXT_PUBLIC_` prefix.
+When the server starts this will generates a `__ENV.js` file in the `public`
+folder that contains allow-listed environment variables that have a
+`NEXT_PUBLIC_` prefix.
 
 2. Add the following to the head section fo your `pages/_document.js`:
 
@@ -35,43 +41,80 @@ Done!
 
 ### Usage 🧑‍💻
 
-In the browser your variables will be available at `window.__ENV.NEXT_PUBLIC_FOO` and on the server `process.env.NEXT_PUBLIC_FOO`.
+In the browser your variables will be available at
+`window.__ENV.NEXT_PUBLIC_FOO` and on the server `process.env.NEXT_PUBLIC_FOO`.
 
 #### Helper 😉
 
 We have included a helper function to make retrieving a value easier:
 
 ```bash
 # .env
-NEXT_PUBLIC_NEXT="Next.js"
-NEXT_PUBLIC_CRA="Create React App"
-NEXT_PUBLIC_NOT_SECRET_CODE="1234"
+NEXT_PUBLIC_FOO="foo"
+BAR="bar"
+```
+
+```jsx
+type Props = {
+  bar: string,
+};
+
+export default function SomePage({ bar }: Props) {
+  return (
+    <div>
+      {window.__ENV.NEXT_PUBLIC_FOO} {bar}
+    </div>
+  );
+}
+
+export const getStaticProps: GetStaticProps = async (context) => {
+  return {
+    props: {
+      bar: process.env.BAR,
+    },
+  };
+};
 ```
 
 Becomes...
 
 ```jsx
 import { env } from 'next-runtime-env';
 
-export default (props) => (
-  <div>
-    <small>
-      Works in the browser: <b>{env('NEXT_PUBLIC_CRA')}</b>.
-    </small>
-    <small>
-      Also works for server side rendering: <b>{env('NEXT_PUBLIC_NEXT')}</b>.
-    </small>
-    <form>
-      <input type="hidden" defaultValue={env('NEXT_PUBLIC_NOT_SECRET_CODE')} />
-    </form>
-  </div>
-);
+type Props = {
+  bar: string,
+};
+
+export default function SomePage({ bar }: Props) {
+  return (
+    <div>
+      {env('NEXT_PUBLIC_FOO')} {bar}
+    </div>
+  );
+}
+
+export const getStaticProps: GetStaticProps = async (context) => {
+  return {
+    props: {
+      bar: env('BAR'),
+    },
+  };
+};
 ```
 
 ### Maintenance 👷
 
-This package is maintained and used by [Expatfile.tax](https://expatfile.tax). The #1 US expat tax e-filing software. 🇺🇸
+This package is maintained and used by [Expatfile.tax][expatfile-site].
+The #1 US expat tax e-filing software. 🇺🇸
 
 ### Other work 📚
 
-Big thanks to the [react-env](https://github.com/andrewmclagan/react-env) project, which inspired us. 🙏
+Big thanks to the [react-env][react-env-repo]
+project, which inspired us. 🙏
+
+[build-url]: https://img.shields.io/github/checks-status/expatfile/next-runtime-env/main
+[cov-img]: https://codecov.io/gh/expatfile/next-runtime-env/branch/main/graph/badge.svg?token=mbGgsweFuP
+[cov-url]: https://codecov.io/gh/expatfile/next-runtime-env
+[nextjs-env-vars]: https://nextjs.org/docs/basic-features/environment-variables
+[react-env-repo]: https://github.com/andrewmclagan/react-env
+[expatfile-site]: https://expatfile.tax

package.json

@@ -14,7 +14,13 @@
     "audit-ci": "audit-ci",
     "semantic-release": "semantic-release"
   },
-  "keywords": [],
+  "keywords": [
+    "nextjs",
+    "runtime",
+    "env",
+    "runtime env",
+    "next-runtime-env"
+  ],
   "author": "Expatfile.tax LLC",
   "license": "MIT",
   "repository": {

src/configure.spec.ts

@@ -0,0 +1,33 @@
+import { configureRuntimeEnv } from './configure';
+import { getPublicEnv } from './helpers/get-public-env';
+import { writeBrowserEnv } from './helpers/write-browser-env';
+
+jest.mock('./helpers/get-public-env', () => ({
+  getPublicEnv: jest.fn(() => ({
+    NEXT_PUBLIC_FOO: 'foo',
+  })),
+}));
+jest.mock('./helpers/write-browser-env', () => ({
+  writeBrowserEnv: jest.fn(),
+}));
+
+// See: https://www.bam.tech/article/fix-jest-mock-cannot-access-before-initialization-error
+const mockGetPublicEnv = getPublicEnv as jest.MockedFunction<
+  typeof getPublicEnv
+>;
+const mockWriteBrowserEnv = writeBrowserEnv as jest.MockedFunction<
+  typeof writeBrowserEnv
+>;
+
+describe('configureRuntimeEnv()', () => {
+  it('should call the helper methods', () => {
+    configureRuntimeEnv();
+
+    expect(mockGetPublicEnv).toHaveBeenCalledTimes(1);
+
+    expect(mockWriteBrowserEnv).toHaveBeenCalledTimes(1);
+    expect(mockWriteBrowserEnv).toHaveBeenCalledWith({
+      NEXT_PUBLIC_FOO: 'foo',
+    });
+  });
+});

src/configure-runtime-env.ts renamed to src/configure.ts

@@ -1,6 +1,6 @@
 import { env } from './env';
 
-describe('env', () => {
+describe('env()', () => {
   afterEach(() => {
     delete process.env.FOO;
 
@@ -9,22 +9,22 @@ describe('env', () => {
   });
 
   it('should return a value from the server', () => {
-    process.env.FOO = 'bar';
+    process.env.FOO = 'foo';
 
-    expect(env('FOO')).toBe('bar');
+    expect(env('FOO')).toBe('foo');
   });
 
   it('should return a value from the browser', () => {
     Object.defineProperty(global, 'window', {
       value: {
         __ENV: {
-          NEXT_PUBLIC_FOO: 'bar',
+          NEXT_PUBLIC_FOO: 'foo',
         },
       },
       writable: true,
     });
 
-    expect(env('NEXT_PUBLIC_FOO')).toBe('bar');
+    expect(env('NEXT_PUBLIC_FOO')).toBe('foo');
   });
 
   it('should return undefined when variable does not exist on the server', () => {
@@ -35,7 +35,7 @@ describe('env', () => {
     Object.defineProperty(global, 'window', {
       value: {
         __ENV: {
-          NEXT_PUBLIC_FOO: 'bar',
+          NEXT_PUBLIC_FOO: 'foo',
         },
       },
       writable: true,

src/env.spec.ts

@@ -1,7 +1,8 @@
 import { isBrowser } from './utils/is-browser';
 
 /**
- * Reads an environment variable from the server or the browser.
+ * Reads a safe environment variable from the browser or any environment
+ * variable from the server (process.env).
  */
 export function env(key: string) {
   if (isBrowser()) {

src/env.ts

@@ -1,6 +1,6 @@
 import { getPublicEnv } from './get-public-env';
 
-describe('getPublicEnv', () => {
+describe('getPublicEnv()', () => {
   afterEach(() => {
     delete process.env.FOO;
     delete process.env.BAR;

src/helpers/get-public-env.spec.ts

@@ -20,7 +20,7 @@ afterAll(() => {
   fs.rmdirSync(path);
 });
 
-describe('writeBrowserEnv', () => {
+describe('writeBrowserEnv()', () => {
   afterEach(() => {
     fs.rmSync(file);
   });