From 41573c73eb58b24a6192da93e1367d40ce933e2c Mon Sep 17 00:00:00 2001 From: Jose V Sebastian Date: Wed, 14 Feb 2024 19:43:23 +0530 Subject: [PATCH] docs: add README.md and comments in cra example --- .eslintignore | 3 +- README.md | 89 ++++++++++++++++++++++++++++ examples/cra/.env | 1 + examples/cra/Dockerfile | 2 + examples/cra/docker-compose.yaml | 1 + examples/cra/scripts/start_server.sh | 2 +- examples/cra/src/App.tsx | 1 + examples/cra/src/index.tsx | 2 + examples/cra/src/react-app-env.d.ts | 1 + 9 files changed, 100 insertions(+), 2 deletions(-) create mode 100644 README.md diff --git a/.eslintignore b/.eslintignore index 413ed6d..f2645ef 100644 --- a/.eslintignore +++ b/.eslintignore @@ -5,4 +5,5 @@ *.html *.ico Dockerfile -*.json \ No newline at end of file +*.json +*.md \ No newline at end of file diff --git a/README.md b/README.md new file mode 100644 index 0000000..60de10a --- /dev/null +++ b/README.md @@ -0,0 +1,89 @@ +# runtime-env-cli + +[![npm](https://img.shields.io/npm/v/runtime-env-cli.svg)](https://www.npmjs.org/package/runtime-env-cli) +[![npm](https://img.shields.io/npm/dm/runtime-env-cli.svg)](https://www.npmjs.org/package/runtime-env-cli) +[![GitHub](https://img.shields.io/github/issues/JoseVSeb/runtime-env.svg)](https://github.com/JoseVSeb/runtime-env/issues) +[![release workflow](https://github.com/JoseVSeb/runtime-env/actions/workflows/release.yaml/badge.svg)](https://github.com/JoseVSeb/runtime-env/actions/workflows/release.yaml) +[![npm](https://img.shields.io/npm/l/runtime-env-cli.svg)](https://www.npmjs.org/package/runtime-env-cli) +[![semantic-release: conventional commit](https://img.shields.io/badge/semantic--release-conventionalcommit-e10079?logo=semantic-release)](https://github.com/semantic-release/semantic-release) + +## Overview + +`runtime-env-cli` is an NPM package that helps manage environment variables in web applications. It allows environment-agnostic build for frameworks like create-react-app and inject environment variables as `window.env` in html files during server startup. + +## Usage + +### Development Mode + +1. Install `runtime-env-cli` as development dependency. + + pnpm: + + ```bash + pnpm i -D runtime-env-cli + ``` + + npm: + + ```bash + npm i -D runtime-env-cli + ``` + + Yarn: + + ```bash + pnpm add -D runtime-env-cli + ``` + +2. Import `runtime-env-cli` in top-level javascript/typescript file for aliasing `process.env` as `windows.env` in development mode. + + ```ts + import "runtime-env-cli"; + ``` + + It also provides type-safety for `windows.env`. + + Note: You can make it further type-safe by extending interfaces `ProcessEnv` or `WindowEnv`. + + Use environment variables from `window.env`: + + ```ts + window.env.SAMPLE_ENV; + ``` + +### Production Mode + +1. Generate static files for your application. + + ```bash + npm run build + ``` + +2. Install `runtime-env-cli` in hosting environment (if using docker, do this in the last stage). + + ```bash + npm i -g runtime-env-cli + ``` + +3. Run the cli to inject env into html files before serving files (in docker, do this in entrypoint following by serving files, refer [example](https://github.com/JoseVSeb/runtime-env/tree/main/examples/cra)). + + ```bash + runtime-env [options] + ``` + + Note: CLI uses `process.env` to get environment while injecting. Any matching environment variables already configured in shell will be read. To use .env files, first load it before running this (refer [dotenv-cli](https://www.npmjs.com/package/dotenv-cli)). + +### CLI Options + +- **-v, --version**: output the version number. +- **-p, --path [paths...]** (optional): glob patterns to match path of html files (default: ["./build/**/*.html"]). +- **-m, --match \**: regular expression to match environment variable names to be injected. +- **-h, --help**: display help for command. + +#### example + +```bash +runtime-env --path "./**/*.html" --match "^APP_ENV_" +``` + +This will inject all environment variables prefixed with `APP_ENV_` as `window.env` object into all html files under working directory. diff --git a/examples/cra/.env b/examples/cra/.env index 042ec2d..3ef4ee6 100644 --- a/examples/cra/.env +++ b/examples/cra/.env @@ -1 +1,2 @@ +# environment variable to be used for development server REACT_APP_SAMPLE_ENV = "This is for development server." \ No newline at end of file diff --git a/examples/cra/Dockerfile b/examples/cra/Dockerfile index 3d127de..cf566f1 100644 --- a/examples/cra/Dockerfile +++ b/examples/cra/Dockerfile @@ -14,8 +14,10 @@ RUN pnpm build FROM base as runner WORKDIR /app +# install runtime-env-cli for production server RUN npm i -g serve runtime-env-cli COPY --from=builder /workspace/build . COPY scripts/start_server.sh . RUN chmod +x start_server.sh +# server startup shell script as entrypoint ENTRYPOINT [ "./start_server.sh" ] \ No newline at end of file diff --git a/examples/cra/docker-compose.yaml b/examples/cra/docker-compose.yaml index 04a7489..c403c6c 100644 --- a/examples/cra/docker-compose.yaml +++ b/examples/cra/docker-compose.yaml @@ -6,4 +6,5 @@ services: ports: - "3000:3000" environment: + # environment variable provided at runtime - REACT_APP_SAMPLE_ENV=injected from docker compose diff --git a/examples/cra/scripts/start_server.sh b/examples/cra/scripts/start_server.sh index 30238f1..a47f12d 100644 --- a/examples/cra/scripts/start_server.sh +++ b/examples/cra/scripts/start_server.sh @@ -1,6 +1,6 @@ #!/bin/sh -# inject matching env variables in built html +# inject matching env variables in built html on server startup runtime-env -m ^REACT_APP_ -p ./*.html # serve the static files diff --git a/examples/cra/src/App.tsx b/examples/cra/src/App.tsx index 566f052..cb89b69 100644 --- a/examples/cra/src/App.tsx +++ b/examples/cra/src/App.tsx @@ -1,5 +1,6 @@ import React from "react"; export default function App() { + // Access environment variable from `window.env` object return
REACT_APP_SAMPLE_ENV: {window.env.REACT_APP_SAMPLE_ENV}
; } diff --git a/examples/cra/src/index.tsx b/examples/cra/src/index.tsx index ed80ae7..6746435 100644 --- a/examples/cra/src/index.tsx +++ b/examples/cra/src/index.tsx @@ -1,6 +1,8 @@ import React from "react"; import ReactDOM from "react-dom/client"; import App from "./App"; + +// `window.env` is now type-safe and loads `process.env` in development mode. import "runtime-env-cli"; const root = ReactDOM.createRoot( diff --git a/examples/cra/src/react-app-env.d.ts b/examples/cra/src/react-app-env.d.ts index b99fb20..48ae2f5 100644 --- a/examples/cra/src/react-app-env.d.ts +++ b/examples/cra/src/react-app-env.d.ts @@ -2,6 +2,7 @@ declare namespace NodeJS { interface ProcessEnv { + // provide type safety for environment variable REACT_APP_SAMPLE_ENV: string; } }