{"id":28739916,"url":"https://github.com/sozialhelden/twelve-factor-dotenv","last_synced_at":"2025-06-16T06:11:15.721Z","repository":{"id":35156558,"uuid":"214226245","full_name":"sozialhelden/twelve-factor-dotenv","owner":"sozialhelden","description":"12-factor config for SSR web apps. Isometric API, dotenv support, makes a `process.env` subset accessible in client-side code.","archived":false,"fork":false,"pushed_at":"2024-09-06T09:06:47.000Z","size":1779,"stargazers_count":4,"open_issues_count":9,"forks_count":1,"subscribers_count":4,"default_branch":"master","last_synced_at":"2025-05-22T21:35:02.974Z","etag":null,"topics":["dotenv-support","ssr"],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/sozialhelden.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2019-10-10T15:59:25.000Z","updated_at":"2022-06-29T19:42:40.000Z","dependencies_parsed_at":"2023-01-15T14:58:13.672Z","dependency_job_id":null,"html_url":"https://github.com/sozialhelden/twelve-factor-dotenv","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/sozialhelden/twelve-factor-dotenv","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sozialhelden%2Ftwelve-factor-dotenv","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sozialhelden%2Ftwelve-factor-dotenv/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sozialhelden%2Ftwelve-factor-dotenv/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sozialhelden%2Ftwelve-factor-dotenv/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/sozialhelden","download_url":"https://codeload.github.com/sozialhelden/twelve-factor-dotenv/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sozialhelden%2Ftwelve-factor-dotenv/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":260109606,"owners_count":22960037,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["dotenv-support","ssr"],"created_at":"2025-06-16T06:11:14.137Z","updated_at":"2025-06-16T06:11:15.684Z","avatar_url":"https://github.com/sozialhelden.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# [12-factor](https://12factor.net) dotenv support for SSR web apps\n\n\n\n- Use environment variables to configure server and client-side code in one central place\n- Supports [an `.env` file](https://www.npmjs.com/package/dotenv) if existing\n- Isometric access to environment variables in browser and server-side code\n- Customize which variables the server shares with the client to hide secret tokens\n- Don't recompile when environment configuration changes to make your app conform to the [\n  twelve-factor model](https://12factor.net/config) which requires that configuration and build are\n  separated\n- Debug different configurations without potentially introducing new bugs in the build process\n- Supports TypeScript\n- Optional support for Express.js and React SSR\n\n## Installation\n\n```bash\nnpm install --save @sozialhelden/twelve-factor-dotenv\n#or\nyarn add @sozialhelden/twelve-factor-dotenv\n```\n\n## Usage\n\n### 1. Add a `env.ts` file to your application\n\n```typescript\nconst { loadGlobalEnvironment } = require('@sozialhelden/twelve-factor-dotenv');\nconst env = loadGlobalEnvironment();\nmodule.exports = env;\n```\n\n### 2. Import the file before any other code on the server\n\n```typescript\nconst env = require('./env');\n\n// more application code here\n```\n\n### 3. Setup client access to a filtered subset of the environment variables\n\nNow you have a working environment configuration on the server—code (e.g. with `env.CONFIG_VALUE`).\n\nWhat's missing is that browser-executed code needs access to the variables too. Here are two ways to\nachieve this:\n\n#### Method 1: Static HTML with a JavaScript served from an extra endpoint\n\nYou can request a JavaScript file from your server (e.g. via Express.js) that adds the configuration\nas global variable to `window`.\n\nAdvantages:\n\n- You can change the configuration without clients having to reload the whole app code\n- Environment variable values never appear in rendered or cached HTML or JS app code, they 'live'\n  externally\n\nDisadvantages:\n\n- If you cache the configuration, it can get out of sync with the app code. If you don't cache it,\n  it can cause a slower page load.\n- The browser must load the script synchronously before any other code runs.\n\nServer side (using [Express.js](https://expressjs.com)):\n\n```typescript\nconst env = require('../lib/env');\nconst { createBrowserEnvironmentJSResponseHandler } = require('@sozialhelden/twelve-factor-dotenv');\n\nconst server = express();\n\n// Provides access to a filtered set of environment variables on the client.\n// Read https://github.com/sozialhelden/twelve-factor-dotenv for more infos.\nserver.get('/clientEnv.js', createBrowserEnvironmentJSResponseHandler(env));\n```\n\nIf you don't use Express.js, you can provide your own response handler:\n\n```typescript\nconst { getFilteredClientEnvironment } = require('@sozialhelden/twelve-factor-dotenv');\n\n// Provides access to a filtered set of environment variables on the client.\n// Read https://github.com/sozialhelden/twelve-factor-dotenv for more infos.\napp.route('/clientEnv.js', (req, res) =\u003e {\n  const filteredEnvObject = JSON.stringify(getFilteredClientEnvironment(env, filterFunction));\n  res.setHeader('Cache-Control', 'max-age=300');\n  res.send(`window.env = ${filteredEnvObject};`);\n});\n```\n\nClient side:\n\n```html\n\u003c!-- Add code to your index.html's \u003chead\u003e --\u003e\n\u003chead\u003e\n  \u003c!-- ...more code... --\u003e\n  \u003cscript src=\"/clientEnv.js\"\u003e\u003c/script\u003e\n\u003c/head\u003e\n```\n\n#### Method 2: Server-side rendering your environment variables into your HTML with React.js\n\nTo load the environment in the browser, you can also render the `\u003cscript\u003e` tag including its content\nwith SSR, for example like this:\n\n```jsx\nimport * as React from 'react';\nimport env from './env';\nimport { environmentScriptTagFactory } from '@sozialhelden/twelve-factor-dotenv';\nconst EnvironmentScriptTag = environmentScriptTagFactory(React);\n\nfunction Head() {\n  return (\n    \u003chead\u003e\n      \u003ctitle\u003eA website!\u003c/title\u003e\n      \u003cEnvironmentScriptTag env={env} /\u003e\n    \u003c/head\u003e\n  );\n}\n```\n\nNow, code running in your browser will have access to some of the environment variables.\n\nThe following variables will be accessible to clients:\n\n- all server process environment variables prefixed with `REACT_APP_` (mimicking the default\n  behavior of [create-react-app](https://github.com/facebook/create-react-app))\n- `npm_package_version` (Tip: version your app with the `version` field in `package.json` and show\n  this in your UI!)\n\nFor security reasons, the library exposes no other process environment variables, as they might\ncontain secret tokens or expose server-side vulnerabilities.\n\n## Contributors\n\n- [@opyh](https://github.com/opyh)\n\nSupported by\n\n[\u003cimg alt=\"Sozialhelden e.V.\" src='./doc/sozialhelden-logo.svg' width=\"200\" style=\"vertical-align: middle;\"\u003e](https://sozialhelden.de)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsozialhelden%2Ftwelve-factor-dotenv","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsozialhelden%2Ftwelve-factor-dotenv","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsozialhelden%2Ftwelve-factor-dotenv/lists"}