arabold / serverless-export-env

Serverless plugin to export environment variables into a .env file
MIT License
103 stars 34 forks source link
aws aws-lambda dotenv serverless serverless-plugin

⚡️ Serverless Export Env Plugin

serverless nodejs npm license dependencies prettier

About

The Serverless Framework 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.).

The Serverless Export Env Plugin helps solve two main use cases:

  1. It will automatically hook into the sls invoke local and sls offline start (see Serverless Offline Plugin) and help resolve your environment variables. This is fully transparent to your application and other plugins.
  2. Invoke sls export-env from the command line to generate a .env file on your local filesystem. Then use a library such as dotenv to import it into your code, e.g. during local integration tests.

Usage

Add the npm package to your project:

# Via yarn
$ yarn add arabold/serverless-export-env --dev

# Via npm
$ npm install arabold/serverless-export-env --save-dev

Add the plugin to your serverless.yml. It should be listed first to ensure it can resolve your environment variables before other plugins see them:

plugins:
  - serverless-export-env

That'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.

Examples

sls export-env

This will export all project-wide environment variables into a .env file in your project root folder.

sls export-env --function MyFunction --filename .env-MyFunction

This will export environment variables of the MyFunction Lambda function into a .env-MyFunction file in your project root folder.

Referencing CloudFormation resources

As 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 and initializes your local environment properly.

Supported instrinsic functions

Examples

provider:
  environment:
    S3_BUCKET_URL:
      Fn::Join:
        - ""
        - - https://s3.amazonaws.com/
          - Ref: MyBucket

Or the short version:

provider:
  environment:
    S3_BUCKET_URL: !Join ["", [https://s3.amazonaws.com/, Ref: MyBucket]]

You can then access the environment variable in your code the usual way (e.g. process.env.S3_BUCKET_URL).

Configuration

The plugin supports various configuration options under custom.export-env in your serverless.yml file:

custom:
  export-env:
    filename: .env
    overwrite: false
    enableOffline: true

Configuration Options

Option Default Description
filename .env Target file name where to write the environment variables to, relative to the project root.
enableOffline true Evaluate the environment variables when running sls invoke local or sls offline start.
overwrite false Overwrite the file even if it exists already.
refMap {} Mapping of resource resolutions for the Ref function
getAttMap {} Mapping of resource resolutions for the Fn::GetAtt function
importValueMap {} Mapping of resource resolutions for the Fn::ImportValue function

Custom Resource Resolution

The 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.

custom:
  export-env:
    refMap:
      # Resolve `!Ref MyDynamoDbTable` as `mock-myTable`
      MyDynamoDbTable: "mock-myTable"
    getAttMap:
      # Resolve `!GetAtt MyElasticSearchInstance.DomainEndpoint` as `localhost:9200`
      MyElasticSearchInstance:
        DomainEndpoint: "localhost:9200"
    importValueMap:
      # Resolve `!ImportValue MyLambdaFunction` as `arn:aws:lambda:us-east-2::function:my-lambda-function`
      MyLambdaFunction: "arn:aws:lambda:us-east-2::function:my-lambda-function"

👉 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 mechanism.

Command-Line Options

Running 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:

sls export-env --function hello --filename .env-hello
Option Description
filename Target filename where to write the environment variables to, relative to the project root.
overwrite Overwrite the file even if it exists already.
function Name of a function for which to generate the .env file.
all Merge environment variables of all functions into a single .env file.

Provided lifecycle events

Migrating from 1.x to 2.x

Releases

2.2.0

2.1.0

2.0.0

alpha.1

alpha.0

1.x Releases ### 1.4.4 - 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. #### 1.4.3 - Internal version (not published) ### 1.4.2 - Fixed some compatibility issues with the latest Serverless framework release. Thanks to [pgrzesik](https://github.com/pgrzesik) for the necessary updates. ### 1.4.1 - Disabled calls to the real aws infrastructure when running with Serverless Offline. Thanks to marooned071 for the contribution. ### 1.4.0 - Collect and set resource values from actual Cloud Formation stack output. Thanks to [andersquist](https://github.com/andersquist) for his contribution! - Fix error when serverless.yml doesn't contain a custom section. Thanks to [michael-wolfenden](https://github.com/michael-wolfenden)! ### 1.3.1 - Explicitly set environment variables during local invocation of the Lambda (`sls invoke local`) ### 1.3.0 - Support different output filename and path. Thanks to [philiiiiiipp](https://github.com/philiiiiiipp). - Export `Outputs` as environment variables. Thanks to [lielran](https://github.com/lielran). - Updated to latest dependencies ### 1.2.0 - Use operating-system-specific end-of-line when creating `.env` file ### 1.1.3 - Fixed an issue with `AWS::AccountId` being resolved as `[Object Promise]` instead of the actual value. ### 1.1.2 - Fixed an issue with CloudFormation resources not being resolved properly if the stack has more than 100 resources or exports. ### 1.1.1 - Fix issue with multiple environment variables for function (thanks to [@Nevon](https://github.com/Nevon)). ### 1.1.0 - Support `Fn::Join` operation (contribution by [@jonasho](https://github.com/jonasho)) - Support pseudo parameters `AWS::Region`, `AWS::AccountId`, `AWS::StackId` and `AWS::StackName`. ### 1.0.2 - 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. ### 1.0.1 - Corrected plugin naming - Improved documentation ### 1.0.0 - This is the initial release with all basic functionality