{"id":13676603,"url":"https://github.com/goatandsheep/react-native-dotenv","last_synced_at":"2025-05-14T00:04:47.749Z","repository":{"id":37783977,"uuid":"278097666","full_name":"goatandsheep/react-native-dotenv","owner":"goatandsheep","description":"Load react native environment variables using import statements for multiple env files.","archived":false,"fork":false,"pushed_at":"2025-05-07T09:15:15.000Z","size":1773,"stargazers_count":840,"open_issues_count":9,"forks_count":47,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-05-12T13:50:47.224Z","etag":null,"topics":["12factor","babel","babel-plugin","dotenv","environment-variables","hacktoberfest","react","react-native","react-native-config"],"latest_commit_sha":null,"homepage":"https://www.npmjs.com/package/react-native-dotenv","language":"JavaScript","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/goatandsheep.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null},"funding":{"github":["goatandsheep"],"patreon":"goatandsheep","open_collective":null,"ko_fi":null,"tidelift":null,"community_bridge":null,"liberapay":null,"issuehunt":"goatandsheep","otechie":null,"custom":null}},"created_at":"2020-07-08T13:31:51.000Z","updated_at":"2025-05-01T05:38:04.000Z","dependencies_parsed_at":"2023-02-09T12:31:30.746Z","dependency_job_id":"4cd579b2-bc6e-475f-8547-5d800b530910","html_url":"https://github.com/goatandsheep/react-native-dotenv","commit_stats":{"total_commits":322,"total_committers":21,"mean_commits":"15.333333333333334","dds":0.7701863354037267,"last_synced_commit":"7b57c0f2582f132c3513d38faa6e8a4fafe58370"},"previous_names":[],"tags_count":50,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/goatandsheep%2Freact-native-dotenv","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/goatandsheep%2Freact-native-dotenv/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/goatandsheep%2Freact-native-dotenv/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/goatandsheep%2Freact-native-dotenv/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/goatandsheep","download_url":"https://codeload.github.com/goatandsheep/react-native-dotenv/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254043298,"owners_count":22004917,"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":["12factor","babel","babel-plugin","dotenv","environment-variables","hacktoberfest","react","react-native","react-native-config"],"created_at":"2024-08-02T13:00:30.181Z","updated_at":"2025-05-14T00:04:47.725Z","avatar_url":"https://github.com/goatandsheep.png","language":"JavaScript","funding_links":["https://github.com/sponsors/goatandsheep","https://patreon.com/goatandsheep","https://issuehunt.io/r/goatandsheep"],"categories":["JavaScript"],"sub_categories":[],"readme":"# react-native-dotenv [![CircleCI](https://circleci.com/gh/goatandsheep/react-native-dotenv.svg?style=svg)](https://circleci.com/gh/goatandsheep/react-native-dotenv)\n\n\u003e Load environment variables using `import` statements.\n\n[![npm version](https://badgen.net/npm/v/react-native-dotenv)](https://www.npmjs.com/package/react-native-dotenv)\n[![dependencies Status](https://img.shields.io/librariesio/release/npm/react-native-dotenv)](https://img.shields.io/librariesio/release/npm/react-native-dotenv)\n[![codecov](https://badgen.net/codecov/c/github/goatandsheep/react-native-dotenv)](https://codecov.io/gh/goatandsheep/react-native-dotenv)\n[![XO code style](https://badgen.net/badge/code%20style/XO/cyan)](https://github.com/xojs/xo)\n[![npm downloads](https://img.shields.io/npm/dt/react-native-dotenv.svg?style=flat-square)](https://www.npmjs.com/package/react-native-dotenv)\n[![works with dotenv-vault](https://badge.dotenv.org/works-with.svg?r=1)](https://www.dotenv.org/r/github.com/dotenv-org/dotenv-vault?r=1)\n\n## Installation\n\n```sh\n$ npm install -D react-native-dotenv\n```\n\nIf you are using Yarn:\n\n```sh\n$ yarn add -D react-native-dotenv\n```\n\n**Breaking changes**: moving from `v0.x` to `v2.x` changes both the setup and usage of this package. Please see the [migration guide](https://github.com/goatandsheep/react-native-dotenv/wiki/Migration-Guide).\n\nMany have been asking about the reasons behind recent changes in this repo. Please see the [story wiki page](https://github.com/goatandsheep/react-native-dotenv/wiki/Story-of-this-repo).\n\n## Introduction\n\nThis babel plugin lets you inject your environment variables into your Javascript environment using dotenv for multiple environments. It is best suited for use with react native and works with all flavors including web.\n\n## Usage\n\n\u003e Also preview [the expo test app](https://github.com/goatandsheep/react-native-dotenv-expo-test).\n\n**babel.config.js**\n\nBasic setup:\n\n```javascript\napi.cache(false)\nmodule.exports = {\n  plugins: [\n    ['module:react-native-dotenv']\n  ]\n};\n```\n\nIf the defaults do not cut it for your project, this outlines the available options for your Babel configuration and their respective default values, but you do not need to add them if you are using the default settings.\n\n```javascript\napi.cache(false)\nmodule.exports = {\n  plugins: [\n    [\n      'module:react-native-dotenv',\n      {\n        envName: 'APP_ENV',\n        moduleName: '@env',\n        path: '.env',\n        blocklist: null,\n        allowlist: null,\n        blacklist: null, // DEPRECATED\n        whitelist: null, // DEPRECATED\n        safe: false,\n        allowUndefined: true,\n        verbose: false,\n      },\n    ],\n  ],\n};\n\n```\n\n\u003e Note: for safe mode, it's highly recommended to set `allowUndefined` to `false`.\n\n\u003e Note: Expo now has [built-in environment variable support](https://docs.expo.dev/guides/environment-variables/). Evaluate if you need\n\n**.env**\n\n```dosini\nAPI_URL=https://api.example.org\nAPI_TOKEN=abc123\n```\n\n### process.env technique\n\nIn **users.js**\n\n```js\nfetch(`${process.env.API_URL}/users`, {\n  headers: {\n    'Authorization': `Bearer ${process.env.API_TOKEN}`\n  }\n})\n```\n\n### Import technique\n\n\u003e The import technique, which is the initial functionality of the library, is to have an import statement at the top that turns into an object because of Babel\n\nIn **users.js**\n\n```js\nimport {API_URL, API_TOKEN} from \"@env\"\n\nfetch(`${API_URL}/users`, {\n  headers: {\n    'Authorization': `Bearer ${API_TOKEN}`\n  }\n})\n```\n\n## [DEPRECATED] White and black lists\n\nMoving forward to a more inclusive language, terms like `white` and `black` are being moved away. Future versions will just use `allowlist` and `blocklist` while `whitelist`/`blacklist` are still supported.\n\n## Allow and Block lists\n\nIt is possible to limit the scope of env variables that will be imported by specifying a `allowlist` and/or a `blocklist` as an array of strings.\n\n```json\n{\n  \"plugins\": [\n    [\"module:react-native-dotenv\", {\n      \"blocklist\": [\n        \"GITHUB_TOKEN\"\n      ]\n    }]\n  ]\n}\n```\n\n```json\n{\n  \"plugins\": [\n    [\"module:react-native-dotenv\", {\n      \"allowlist\": [\n        \"API_URL\",\n        \"API_TOKEN\"\n      ]\n    }]\n  ]\n}\n```\n\n## Safe mode\n\nEnable safe mode to only allow environment variables defined in the `.env` file. This will completely ignore everything that is already defined in the environment.\n\nThe `.env` file has to exist.\n\n```json\n{\n  \"plugins\": [\n    [\"module:react-native-dotenv\", {\n      \"safe\": true\n    }]\n  ]\n}\n```\n\n## Allow undefined\n\nAllow importing undefined variables, their value will be `undefined`.\n\n```json\n{\n  \"plugins\": [\n    [\"module:react-native-dotenv\", {\n      \"allowUndefined\": true\n    }]\n  ]\n}\n```\n\n```js\nimport {UNDEFINED_VAR} from '@env'\n\nconsole.log(UNDEFINED_VAR === undefined) // true\n```\n\nWhen set to `false`, an error will be thrown. **This is no longer default behavior**.\n\n## Override `envName`\n\nOne thing that we've noticed is that metro overwrites the test environment variable even if you specify a config, so we've added a way to fix this. By default, defining the `APP_ENV` variable can be used to set your preferred environment, separate from `NODE_ENV`.\n\n```json\n// package.json\n{\n  \"scripts\": {\n    \"start:staging\": \"APP_ENV=staging npx react-native start\",\n  }\n}\n```\nThe above example would use the `.env.staging` file. The standard word is `test`, but go nuts.\n\nTo use your own defined name as the environment override, you can define it using `envName`:\n\n```json\n{\n  \"plugins\": [\n    [\"module:react-native-dotenv\", {\n     \"envName\": \"MY_ENV\"\n    }]\n  ]\n}\n```\n\nNow you can define `MY_ENV`:\n\n```json\n// package.json\n{\n  \"scripts\": {\n    \"start:staging\": \"MY_ENV=staging npx react-native start\",\n  }\n}\n```\n\nNote: if you're using `APP_ENV` (or `envName`), you cannot use `development` nor `production` as values, and you should avoid having a `.env.development` or `.env.production`. This is a Babel and Node thing that I have little control over unfortunately and is consistent with many other platforms that have an override option, like [Gatsby](https://www.gatsbyjs.com/docs/how-to/local-development/environment-variables/#additional-environments-staging-test-etc). If you want to use `development` and `production`, you should not use `APP_ENV` (or `envName`), but rather the built-in `NODE_ENV=development` or `NODE_ENV=production`.\n\n\n## Multi-env\n\nThis package now supports environment specific variables. This means you may now import environment variables from multiple files, i.e. `.env`, `.env.development`, `.env.production`, and `.env.test`. This is based on [dotenv-flow](https://www.npmjs.com/package/dotenv-flow).\n\nNote: it is not recommended that you commit any sensitive information in `.env` file to code in case your git repo is exposed. The best practice is to put a `.env.template` or `.env.development.template` that contains dummy values so other developers know what to configure. Then add your `.env` and `.env.development` to `.gitignore`. You can also keep sensitive keys in a separate `.env.local` (and respective `.env.local.template`) in `.gitignore` and you can use your other `.env` files for non-sensitive config.\n\nIf you are publishing your apps on an auto-publishing platform like EAS (Expo Application Services), make sure to put your secrets on the platform dashboard directly. If you are wondering what environment the platforms choose it is likely `.env.production` (not `.env.prod`) and there is likely no way to change this.\n\nThe base set of variables will be `.env` and the environment-specific variables will overwrite them.\n\nThe variables will automatically be pulled from the appropriate environment and `development` is the default. The choice of environment is based on your Babel environment first and if that value is not set, your NPM environment, which should actually be the same, but this makes it more robust.\n\nIn general, **Release** is `production` and **Debug** is `development`.\n\nTo choose, setup your scripts with `NODE_ENV` for each environment\n\n```json\n// package.json\n{\n  \"scripts\": {\n    \"start:development\": \"NODE_ENV=development npx react-native start\",\n    \"start:production\": \"NODE_ENV=production npx react-native start\",\n  }\n}\n```\n\n## TypeScript\n\nFor the library to work with TypeScript, you must manually specify the types for the module.\n\n- Create a `types` folder in your project\n- Inside that folder, create a `*.d.ts`file, say, `env.d.ts`\n- in that file, declare a module as the following format:\n\n```ts\ndeclare module '@env' {\n  export const API_BASE: string;\n}\n```\n\nAdd all of your .env variables inside this module.\n\n- Finally, add this folder into the `typeRoots` field in your `tsconfig.json` file:\n\n```json\n{\n...\n  \"compilerOptions\": {\n    ...\n      \"typeRoots\": [\"./types\"],\n    ...\n  }\n...\n}\n```\n\n## Reference Material\n\nIf you are not familiar with how dotenv or Babel work, make sure to read the following reference materials:\n\n* [babel environments](https://babeljs.io/docs/en/6.26.3/babelrc#env-option)\n* [dotenv documentation](https://www.npmjs.com/package/dotenv)\n* [See the wiki for more troubleshooting tips](https://github.com/goatandsheep/react-native-dotenv/wiki/Multi-env-troubleshooting)\n\n### How this works\n\nThis Babel plugin processes your `.env` files and your environment variables and replaces the references to the environment variables in your code before it runs. This is because the environment variables will no longer be accessible once the React Native engine generates the app outputs.\n\n## Cacheing\n\nWhen using with [`babel-loader`](https://github.com/babel/babel-loader) with caching enabled you will run into issues where environment changes won’t be picked up.\nThis is due to the fact that `babel-loader` computes a `cacheIdentifier` that does not take your `.env` file(s) into account. The good news is that a recent update has fixed this problem as long as you're using a new version of Babel. Many react native libraries have not updated their Babel version yet so to force the version, add in your `package.json`:\n\n```json\n\"resolutions\": {\n  \"@babel/core\": \"^7.20.2\",\n  \"babel-loader\": \"^8.3.0\"\n}\n```\n\nIf this does not work, you should set `api.cache(false)` in your babel config\n\nmetro.config.js`resetCache: true`\n\nYou can easily clear the cache:\n\n```shell\nrm -rf node_modules/.cache/babel-loader/*\n```\n\nor\n\n`npm start -- --reset-cache`\n\nor\n\n`yarn start --reset-cache`\n\nor\n\n`yarn start --clear`\n\nor\n\n`jest --no-cache`\n\nor\n\n`expo r -c`\n\nand\n\n`expo start --clear`\n\nor\n\n`rm -rf .expo/web/cache`\n\nor\n\n[react-native-clean-project](https://www.npmjs.com/package/react-native-clean-project)\n\nMaybe a solution for updating package.json scripts:\n\n\u003e     \"cc\": \"rimraf node_modules/.cache/babel-loader/*,\",\n\u003e     \"android\": \"npm run cc \u0026\u0026 react-native run-android\",\n\u003e     \"ios\": \"npm run cc \u0026\u0026 react-native run-ios\",\n\nOr you can override the default `cacheIdentifier` to include some of your environment variables.\n\nThe tests that use `require('@env')` are also not passing.\n\nFor nextjs, you _must_ set `moduleName` to `react-native-dotenv`.\n\n## Credits\n\n* Based on [David Chang](https://github.com/zetachang)’s works on [babel-plugin-dotenv](https://github.com/zetachang/react-native-dotenv/tree/master/babel-plugin-dotenv).\n* Also based on [Bertrand Marron](https://github.com/tusbar)'s works on [babel-plugin-dotenv-import](https://github.com/tusbar/babel-plugin-dotenv-import).\n\nIf you'd like to become an active contributor, please send us a message.\n\n## Miscellaneous\n\n```\n    ╚⊙ ⊙╝\n  ╚═(███)═╝\n ╚═(███)═╝\n╚═(███)═╝\n ╚═(███)═╝\n  ╚═(███)═╝\n   ╚═(███)═╝\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgoatandsheep%2Freact-native-dotenv","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgoatandsheep%2Freact-native-dotenv","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgoatandsheep%2Freact-native-dotenv/lists"}