This Serverless plugin exports the environment variables defined in serverless.yml
into a distinct .env
file. This allows you to access these environment variables
from local scripts such as for integration tests. You will find the .env
file
in the root folder of your project.
It will collect the global environment variables of the poject as well as all
environment variables of the functions. It will also add API_ENDPOINT
and
IS_OFFLINE
to your environment if you run the plugin via serverless offline
.
Environment variables referencing CloudFormation resources (e.g. Ref: MyDynamoDbTable
),
or import values (e.g. Fn::ImportValue: MyExportedValue
) are automatically
resolved to their respective values. This, however, requires the stack to be
deployed before the plugin can access any of these variables.
This plugin is based on the serverless-dotenv Plugin by Jimdo but largely rewritten to fit our needs.
There're plenty of environment and dotenv plugins available for Serverless. However, some are already obsolete, others are very limited in use case. We needed a possibility to access Serverless environment variables from command line during integration testing of our code. As some of these environment variables are referencing CloudFormation resources, none of the existing plugins was able to solve this.
Serverless offers a very powerful feature: You are able to reference AWS
resources anywhere from within your .yaml
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.
require("dotenv").config({ path: "../.env" /* path to your project root folder */ });
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);
});
The Serverless Export Env Plugin supports references to resources created
within the serverless.yml
, to resources imported from another stack via
Fn::ImportValue
, pseudo parameters such as AWS::Region
and AWS::AccountId
as well as the commonly used Fn::Join
intrinsic function.
The plugin allows you to make use of these references
(and all other environment variables of course) from the command line by
exporting them into a .env
file in your project folder. Then use a library
such as dotenv to read them during
runtime.
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
:
plugins:
- serverless-export-env
That's it! You can now call serverless export-env
in your terminal to
generate the .env
file based on your Serverless configuration.
Alternative you can just start serverless invoke local -f FUNCTION
or
serverless offline
to generate it.
export-env:collect
- Collect environment variables from Serverlessexport-env:resolve
- Resolve CloudFormation references and import variablesexport-env:apply
- Set environment variables when testing Lambda functions locallyexport-env:write
- Write environment variables to file
serverless export-env
This example will export all environment variables into a .env
file in
your project root folder.
- Use operating system-specific end-of-line when creating
.env
file
- Fixed an issue with
AWS::AccountId
being resolved as[Object Promise]
instead of the actual value.
- Fixed an issue with CloudFormation resources not being resolved properly if the stack has more than 100 resources or exports.
- Fix issue with multiple environment variables for function (thanks to @Nevon).
- Support
Fn::Join
operation (contribution by @jonasho) - Support pseudo parameters
AWS::Region
,AWS::AccountId
,AWS::StackId
andAWS::StackName
.
- The plugin now properly resolves and sets the environment variables if a
Lambda function is invoked locally (
serverless invoke local -f FUNCTION
). This allows seamless as if the function would be deployed on AWS.
- Corrected plugin naming
- Improved documentation
- This is the initial release with all basic functionality
- Add support for more intrinsic functions such as
Fn::GetAtt
,Fn::Sub
, etc. (see http://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/intrinsic-function-reference.html) - Write some tests!