serverless-export-env

⚡️ Serverless Export Env Plugin

About

The Serverless Framework offers a very powerful feature: You are able to 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 resultion 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 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 the 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 based on your Serverless configuration. Or, you can just run sls invoke local -f FUNCTION or sls offline start to run your code locally as usual.

Examples

serverless export-env

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

serverless export-env --function MyFunction --filename .env-MyFunction

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

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	{}	A mapping of resource resolutions for the Ref function
getAttMap	{}	A mapping of resource resolutions for the Fn::GetAtt function
importValueMap	{}	A mapping of resource resolutions for the Fn::ImportValue function

Referencing CloudFormation resources

The Serverless Framework offers a very powerful feature: You are able to reference AWS resources anywhere from within your serverless.yml and it will automatically resolve them to their respective values during deployment. A common example is to bind a DynamoDB table name to an environment variable, so you can access it in your Lambda function implementation later:

provider:
  environment:
    TABLE_NAME:
      Ref: MyDynamoDbTable
# ...
resources:
  Resources:
    MyDynamoDbTable:
      Type: AWS::DynamoDB::Table
      DeletionPolicy: Retain
      Properties:
        # ...

Later in your code you can simply access process.env.TABLE_NAME to get the proper DynamoDB table name without having to hardcode anything.

const AWS = require("aws-sdk");
const docClient = new AWS.DynamoDB.DocumentClient({
  /* ... */
});
docClient.get(
  {
    TableName: process.env.TABLE_NAME,
    Key: { foo: "bar" },
  },
  (result) => {
    console.log(result);
  }
);

So far, all this works out of the box when being deployed, without the need for this plugin. However, if you try to run the above code locally using sls invoke local or sls offline start, the TABLE_NAME environment variable will not be initialized properly. This is where the Serverless Export Env Plugin comes in. It automatically resolves intrinsic functions like Ref and Fn::ImportValue and initializes your local environment properly.

Supported instrinsic functions

• Condition Functions
  • Fn::And
  • Fn::Equals
  • Fn::If
  • Fn::Not
  • Fn::Or
• Fn::FindInMap
• Fn::GetAtt
• Fn::GetAZs
• Fn::Join
• Fn::Select
• Fn::Split
• Fn::Sub (at the moment only key-value map subtitution is supported)
• Fn::ImportValue
• Ref

Example:

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]]

Note that sls invoke local will report an error if you're using any function other than Fn::ImportValue or Ref in your environment variables. This is a Serverless limitation and cannot be fixed by this plugin unfortunately.

Resource Resolution

The plugin will try its best to resolve resource references like Ref, Fn::GetAtt, and Fn::ImportValue for you. However, in 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.

• refMap takes a mapping of resource name to value pairs.
• getAttMap takes a mapping of resource name to attribute/value pairs.
• importValueMap takes a mapping of import name to value pairs.

custom:
  export-env:
    refMap:
      MyDbTable: "mock-myTable"
    getAttMap:
      ElasticSearchInstance:
        DomainEndpoint: "localhost:9200"
    importValueMap:
      OtherLambdaFunction: "arn:aws:lambda:us-east-2::function:other-lambda-function"

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 file name 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 for.

Provided lifecycle events

• export-env:collect - Collect environment variables from Serverless
• export-env:resolve - Resolve CloudFormation references and import variables
• export-env:apply - Set environment variables when testing Lambda functions locally
• export-env:write - Write environment variables to file

Migrating from 1.x to 2.x

• 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.
• By default the plugin will no longer overwrite any existing .env file. To enable overwriting existing files either specific --overwrite in the command line or set the custom.export-env.overwrite configuration option.
• Resource Outputs values (resources.Resources.Outputs.*) are no longer exported automatically. This has always been a workaround and causes more problems than it actually 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 new environment variable to provider.environment instead.
• 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 is specified, only global environment variables will be exported.
• The configuration options filename and pathFromRoot have been merged to filename now. You can specify relative paths in filename now such as ./dist/.env. Make sure the target folder exists!

Releases

2.0.0

• Complete rewrite of the variable resolver. We use the amazing 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 most commonly used intrinstic functions automatically now.

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 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 for his contribution!
• Fix error when serverless.yml doesn't contain a custom section. Thanks to michael-wolfenden!

1.3.1

• Explicitly set environment variables during local invocation of the Lambda (sls invoke local)

1.3.0

• Support different output file name and path. Thanks to philiiiiiipp.
• Export Outputs as environment variables. Thanks to 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).

1.1.0

• Support Fn::Join operation (contribution by @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