{"id":16738074,"url":"https://github.com/arabold/serverless-export-env","last_synced_at":"2025-04-06T00:10:33.279Z","repository":{"id":37742757,"uuid":"89604350","full_name":"arabold/serverless-export-env","owner":"arabold","description":"Serverless plugin to export environment variables into a .env file","archived":false,"fork":false,"pushed_at":"2023-02-03T20:29:37.000Z","size":811,"stargazers_count":98,"open_issues_count":16,"forks_count":35,"subscribers_count":5,"default_branch":"master","last_synced_at":"2024-04-24T13:59:26.232Z","etag":null,"topics":["aws","aws-lambda","dotenv","serverless","serverless-plugin"],"latest_commit_sha":null,"homepage":null,"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/arabold.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":"2017-04-27T14:06:50.000Z","updated_at":"2024-04-22T16:04:51.000Z","dependencies_parsed_at":"2023-02-18T10:45:23.640Z","dependency_job_id":null,"html_url":"https://github.com/arabold/serverless-export-env","commit_stats":null,"previous_names":[],"tags_count":20,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/arabold%2Fserverless-export-env","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/arabold%2Fserverless-export-env/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/arabold%2Fserverless-export-env/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/arabold%2Fserverless-export-env/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/arabold","download_url":"https://codeload.github.com/arabold/serverless-export-env/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247415973,"owners_count":20935387,"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":["aws","aws-lambda","dotenv","serverless","serverless-plugin"],"created_at":"2024-10-13T00:29:09.702Z","updated_at":"2025-04-06T00:10:33.262Z","avatar_url":"https://github.com/arabold.png","language":"JavaScript","readme":"# ⚡️ Serverless Export Env Plugin\n\n[![serverless](https://img.shields.io/npm/dependency-version/serverless-export-env/peer/serverless.svg?style=flat-square)](https://www.serverless.com)\n[![nodejs](https://img.shields.io/node/v/serverless-export-env.svg?style=flat-square)](https://nodejs.org/)\n[![npm](https://img.shields.io/npm/v/serverless-export-env.svg)](https://www.npmjs.com/package/serverless-export-env)\n[![license](https://img.shields.io/github/license/arabold/serverless-export-env.svg)](https://github.com/arabold/serverless-export-env/blob/master/LICENSE)\n[![dependencies](https://img.shields.io/librariesio/github/arabold/serverless-export-env.svg)](https://www.npmjs.com/package/serverless-export-env)\n[![prettier](https://img.shields.io/badge/code_style-prettier-ff69b4.svg?style=flat-square)](https://prettier.io/)\n\n## About\n\nThe [Serverless Framework](https://www.serverless.com/) offers a very powerful feature: You can reference AWS resources anywhere from within your `serverless.yml` and it will automatically resolve them to their respective values during deployment. However, this only works properly once your code is deployed to AWS. The _Serverless Export Env Plugin_ extends the Serverless Framework's built-in variable solution capabilities by adding support many additional CloudFormation intrinsic functions (`Fn::GetAtt`, `Fn::Join`, `Fn::Sub`, etc.) as well as variable references (`AWS::Region`, `AWS::StackId`, etc.).\n\nThe _Serverless Export Env Plugin_ helps solve two main use cases:\n\n1. It will automatically hook into the `sls invoke local` and `sls offline start` (see [Serverless Offline Plugin](https://github.com/dherault/serverless-offline)) and help resolve your environment variables. This is fully transparent to your application and other plugins.\n2. Invoke `sls export-env` from the command line to generate a `.env` file on your local filesystem. Then use a library such as [dotenv](https://www.npmjs.com/package/dotenv) to import it into your code, e.g. during local integration tests.\n\n## Usage\n\nAdd the npm package to your project:\n\n```sh\n# Via yarn\n$ yarn add arabold/serverless-export-env --dev\n\n# Via npm\n$ npm install arabold/serverless-export-env --save-dev\n```\n\nAdd the plugin to your `serverless.yml`. It should be listed first to ensure it can resolve your environment variables before other plugins see them:\n\n```yaml\nplugins:\n  - serverless-export-env\n```\n\nThat's it! You can now call `sls export-env` in your terminal to generate the `.env` file. Or, you can run `sls invoke local -f FUNCTION` or `sls offline start` to run your code locally as usual.\n\n### Examples\n\n```sh\nsls export-env\n```\n\nThis will export all project-wide environment variables into a `.env` file in your project root folder.\n\n```sh\nsls export-env --function MyFunction --filename .env-MyFunction\n```\n\nThis will export environment variables of the `MyFunction` Lambda function into a `.env-MyFunction` file in your project root folder.\n\n## Referencing CloudFormation resources\n\nAs mentioned before, the Serverless Framework allows you to reference AWS resources anywhere from within your `serverless.yml` and it will automatically resolve them to their respective values during deployment. However, Serverless' built-in variable resolution is limited and will not always work when run locally. The _Serverless Export Env Plugin_ extends this functionality and automatically resolves commonly used [intrinsic functions](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/intrinsic-function-reference.html) and initializes your local environment properly.\n\n### Supported instrinsic functions\n\n- Condition Functions\n  - `Fn::And`\n  - `Fn::Equals`\n  - `Fn::If`\n  - `Fn::Not`\n  - `Fn::Or`\n- `Fn::FindInMap`\n- `Fn::GetAtt`\n- `Fn::GetAZs`\n- `Fn::Join`\n- `Fn::Select`\n- `Fn::Split`\n- `Fn::Sub` (at the moment only key-value map subtitution is supported)\n- `Fn::ImportValue`\n- `Ref`\n\n### Examples\n\n```yaml\nprovider:\n  environment:\n    S3_BUCKET_URL:\n      Fn::Join:\n        - \"\"\n        - - https://s3.amazonaws.com/\n          - Ref: MyBucket\n```\n\nOr the short version:\n\n```yaml\nprovider:\n  environment:\n    S3_BUCKET_URL: !Join [\"\", [https://s3.amazonaws.com/, Ref: MyBucket]]\n```\n\nYou can then access the environment variable in your code the usual way (e.g. `process.env.S3_BUCKET_URL`).\n\n## Configuration\n\nThe plugin supports various configuration options under `custom.export-env` in your `serverless.yml` file:\n\n```yaml\ncustom:\n  export-env:\n    filename: .env\n    overwrite: false\n    enableOffline: true\n```\n\n### Configuration Options\n\n| Option         | Default | Description                                                                                       |\n| -------------- | ------- | ------------------------------------------------------------------------------------------------- |\n| filename       | `.env`  | Target file name where to write the environment variables to, relative to the project root.       |\n| enableOffline  | `true`  | Evaluate the environment variables when running `sls invoke local` or `sls offline start`.        |\n| overwrite      | `false` | Overwrite the file even if it exists already.                                                     |\n| refMap         | `{}`    | Mapping of [resource resolutions](#Custom-Resource-Resolution) for the `Ref` function             |\n| getAttMap      | `{}`    | Mapping of [resource resolutions](#Custom-Resource-Resolution) for the `Fn::GetAtt` function      |\n| importValueMap | `{}`    | Mapping of [resource resolutions](#Custom-Resource-Resolution) for the `Fn::ImportValue` function |\n\n### Custom Resource Resolution\n\nThe plugin will try its best to resolve resource references like `Ref`, `Fn::GetAtt`, and `Fn::ImportValue` for you. However, sometimes this might fail, or you might want to use mocked values instead. In those cases, you can override those values using the `refMap`, `getAttMap`, and `importValueMap` options.\n\n- `refMap` takes a mapping of _resource name_ to _value_ pairs.\n- `getAttMap` takes a mapping of _resource name_ to _attribute/value_ pairs.\n- `importValueMap` takes a mapping of _import name_ to _value_ pairs.\n\n```yaml\ncustom:\n  export-env:\n    refMap:\n      # Resolve `!Ref MyDynamoDbTable` as `mock-myTable`\n      MyDynamoDbTable: \"mock-myTable\"\n    getAttMap:\n      # Resolve `!GetAtt MyElasticSearchInstance.DomainEndpoint` as `localhost:9200`\n      MyElasticSearchInstance:\n        DomainEndpoint: \"localhost:9200\"\n    importValueMap:\n      # Resolve `!ImportValue MyLambdaFunction` as `arn:aws:lambda:us-east-2::function:my-lambda-function`\n      MyLambdaFunction: \"arn:aws:lambda:us-east-2::function:my-lambda-function\"\n```\n\n\u003e 👉 Generally, it is recommended to avoid the use of intrinsic functions in your environment variables. Often, the same can be achieved by simply predefining a resource name and then manually construct the desired variable values. To share resources between different Serverless services, check out the `${cf:stackName.outputKey}` [variable resolution](https://www.serverless.com/framework/docs/providers/aws/guide/variables/) mechanism.\n\n## Command-Line Options\n\nRunning `sls export-env` will, by default, only export _global_ environment variables into your `.env` file (those defined under `provider.environment` in your `serverless.yml`). If you want to generate the `.env` file for a specific function, pass the function name as a command-line argument as follows:\n\n```sh\nsls export-env --function hello --filename .env-hello\n```\n\n| Option    | Description                                                                                |\n| --------- | ------------------------------------------------------------------------------------------ |\n| filename  | Target filename where to write the environment variables to, relative to the project root. |\n| overwrite | Overwrite the file even if it exists already.                                              |\n| function  | Name of a function for which to generate the .env file.                                    |\n| all       | Merge environment variables of all functions into a single .env file.                      |\n\n## Provided lifecycle events\n\n- `export-env:collect` - Collect environment variables from Serverless\n- `export-env:resolve` - Resolve CloudFormation references and import variables\n- `export-env:apply` - Set environment variables when testing Lambda functions locally\n- `export-env:write` - Write environment variables to file\n\n## Migrating from 1.x to 2.x\n\n- Running `sls invoke local` or `sls offline start` will no longer create or update your `.env` file. If you want to create an `.env` file, simply run `sls export-env` instead.\n- By default, the plugin will no longer overwrite any existing `.env` file. To enable overwriting existing files, either specify `--overwrite` in the command-line or set the `custom.export-env.overwrite` configuration option.\n- Resource `Outputs` values (`resources.Resources.Outputs.*`) are no longer getting exported automatically. This has always been a workaround and causes more problems than it solved. The plugin will try its best to resolve `Fn::GetAtt` and other references for you now, so there should be little need for the old behavior anymore. Add the desired value as an environment variable to `provider.environment` instead.\n- Running `sls export-env` will no longer merge the environment variables of all functions into a single `.env` file. Instead, pass the name of the desired function as `--function` argument to the command line. If no function name is specified, only project-wide environment variables will get exported. To bring back the old behavior, pass `--all` in command line and it will generate a file including all environment variables of all functions. However, please be aware that the behavior is undefined if functions use conflicting values for the same environment variable name.\n- The configuration options `filename` and `pathFromRoot` have been merged to `filename` now. You can specify relative paths in `filename` such as `./dist/.env` now. Make sure the target folder exists!\n\n## Releases\n\n### 2.2.0\n\n- Fixed error with latest `cfn-resolver-lib`. Thanks to [estahn](https://github.com/estahn) for the fix.\n- Updated dependencies to latest versions.\n\n### 2.1.0\n\n- Compatibility with Serverless v3.x\n- Updated dependencies' minor versions\n\n### 2.0.0\n\n- Removed optimistic variable resolution for `Fn::GetAtt` as it was not working properly and caused hard to solve issues. If you rely on `Fn::GetAtt` in your environment variables, define a custom resolution using the `getAttMap` [configuration option](#Configuration-Options).\n\n### alpha.1\n\n- Added `--all` command line parameter to merge the environment variables of all functions into a single `.env` file. Please note that the behavior is _undefined_ if functions use conflicting values for the same environment variable name.\n\n### alpha.0\n\n- Complete rewrite of the variable resolver. We use the amazing [cfn-resolver-lib](https://github.com/robessog/cfn-resolver-lib) lib now. This allows us to support not only `Ref` and `Fn::ImportValue` as in previous releases, but we're able to resolve the most commonly used intrinsic functions automatically now.\n\n\u003cdetails\u003e\n\u003csummary\u003e1.x Releases\u003c/summary\u003e\n\n### 1.4.4\n\n- Reverted changes in 1.4.1. Unfortunately, we broke the semver contract by introducing a breaking feature in a patch update. This feature needs to be rethought and added back in a 1.5.x release as optional. Until then, I had to remove it again.\n\n#### 1.4.3\n\n- Internal version (not published)\n\n### 1.4.2\n\n- Fixed some compatibility issues with the latest Serverless framework release. Thanks to [pgrzesik](https://github.com/pgrzesik) for the necessary updates.\n\n### 1.4.1\n\n- Disabled calls to the real aws infrastructure when running with Serverless Offline. Thanks to marooned071 for the contribution.\n\n### 1.4.0\n\n- Collect and set resource values from actual Cloud Formation stack output. Thanks to [andersquist](https://github.com/andersquist) for his contribution!\n- Fix error when serverless.yml doesn't contain a custom section. Thanks to [michael-wolfenden](https://github.com/michael-wolfenden)!\n\n### 1.3.1\n\n- Explicitly set environment variables during local invocation of the Lambda (`sls invoke local`)\n\n### 1.3.0\n\n- Support different output filename and path. Thanks to [philiiiiiipp](https://github.com/philiiiiiipp).\n- Export `Outputs` as environment variables. Thanks to [lielran](https://github.com/lielran).\n- Updated to latest dependencies\n\n### 1.2.0\n\n- Use operating-system-specific end-of-line when creating `.env` file\n\n### 1.1.3\n\n- Fixed an issue with `AWS::AccountId` being resolved as `[Object Promise]` instead of the actual value.\n\n### 1.1.2\n\n- Fixed an issue with CloudFormation resources not being resolved properly if the stack has more than 100 resources or exports.\n\n### 1.1.1\n\n- Fix issue with multiple environment variables for function (thanks to [@Nevon](https://github.com/Nevon)).\n\n### 1.1.0\n\n- Support `Fn::Join` operation (contribution by [@jonasho](https://github.com/jonasho))\n- Support pseudo parameters `AWS::Region`, `AWS::AccountId`, `AWS::StackId` and `AWS::StackName`.\n\n### 1.0.2\n\n- The plugin now properly resolves and sets the environment variables if a Lambda function is invoked locally (`sls invoke local -f FUNCTION`). This allows seamless as if the function would be deployed on AWS.\n\n### 1.0.1\n\n- Corrected plugin naming\n- Improved documentation\n\n### 1.0.0\n\n- This is the initial release with all basic functionality\n\u003c/details\u003e\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Farabold%2Fserverless-export-env","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Farabold%2Fserverless-export-env","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Farabold%2Fserverless-export-env/lists"}