I recently published my serverless-exports-plugin
for the Serverless Framework. While it shares similarities with existing plugins like serverless-export-env and serverless-export-outputs, my plugin supports to export both environment variables and stack outputs.
What It Does
The plugin retrieves environment variables and stack outputs specified in serverless.yaml
and saves them to local files during deployment.
Here's a sample Serverless project to illustrate:
service: acme-service
frameworkVersion: '3'
plugins:
- serverless-exports-plugin
custom:
exports:
environment:
file: .env.${sls:stage}
format: env
overwrite: true
stack:
file: .serverless/stack-outputs.txt
format: env
overwrite: true
provider:
name: aws
runtime: nodejs18.x
environment:
FOO: bar
STAGE: ${sls:stage}
REGION: ${aws:region}
SERVICE: ${self:service}
functions:
hello:
handler: index.handler
resources:
Resources:
bucket:
Type: AWS::S3::Bucket
Properties:
BucketName: ${self:service}-${sls:stage}-bucket
Outputs:
Foo:
Value: bar
BucketName:
Value: !Ref bucket
When deployed using serverless deploy --stage dev
:
The defined environment variables are saved in a file .env.dev
:
# .env.dev
FOO: bar
STAGE: dev
REGION: us-east-1
SERVICE: acme-service
The outputs from the stack are written to the .serverless/stack-outputs.txt
file.
# .serverless/stack-outputs.txt
ServerlessDeploymentBucketName: acme-service-dev-serverlessdeploymentbuck-ab4cd786
HelloLambdaFunctionQualifiedArn: arn:aws:lambda:us-east-1:000000000000:function:acme-service-dev-hello:1
Foo: bar
BucketName: acme-service-dev-bucket
Note, that the stack outputs contain additional keys from the Serverless Framework that have not been explicitly defined.
Why I Created It
Although I designed it for a specific need, there are numerous other applications. For instance, I've set up an S3 bucket and a CloudFront distribution in a Serverless project to host a website. When I need to deploy the website — whether locally or in CI — I first deploy the infrastructure resources and then upload the web assets (HTML, JS, CSS) to S3. To streamline this into a single script, I needed the Serverless environment variables and stack outputs with their evaluated values.
The deploy script is as follows:
#!/bin/bash
# Verify if the STAGE environment variables is set
if [ -z "$STAGE" ]; then
echo "Environment variable STAGE is not defined"
exit 1
fi
# Deploy Serverless service
# This produces a .env.<STAGE> file and a .serverless/stack-outputs.txt file
serverless deploy --stage "$STAGE"
# Build Vite application
# This loads the .env.<STAGE> file with mode=<STAGE>
vite build --mode "$STAGE"
# Stack outputs are generated during the Serverless deployment
# These include the S3 bucket name
STACK_OUTPUTS_FILE=".serverless/stack-outputs.txt"
# Read the file and set each line as an environment variable
while IFS="=" read -r key value; do
export "$key=$value"
done < "$STACK_OUTPUTS_FILE"
# Upload the bundled app to the S3 bucket
# $BucketName is an output from the stack outputs
aws s3 sync "dist/" "s3://$BucketName"
# Additional steps
# ...
What’s Ahead
There are several features I'm still working on. At present, only the .env
format is available for exporting. However, I plan to add support for other formats, including JSON, TOML, and YAML. To provide even greater versatility, exports might be relayed to a JavaScript handler function rather than being saved to a file.
Furthermore, only globally specified environment variables are currently exported. I intend to ensure function-level variables are also exported. In addition, I plan to implement support for including and excluding specific keys that are exported.
zirkelc / serverless-exports-plugin
Serverless plugin to export environment variables and stack outputs
Serverless Exports Plugin
This plugin exports environment variables and stack outputs from your Serverless project to local files These files can then be used in development or in CI/CD pipelines to set environment variables or use as input for other tools.
Usage
Install the plugin as a development dependency in your Serverless project:
npm install --save-dev serverless-exports-plugin
Then add the plugin to your serverless.yml
file:
plugins:
- serverless-exports-plugin
Finally, configure the exports you want to generate:
custom:
exports:
environment:
file: .env.${sls:stage}
format: env
overwrite: true
stack:
file: stack-outputs.txt
format: env
overwrite: true
That's it! Now you can run serverless deploy
or serverless package
or serverless info
and the plugin will generate the exports for you.
Configuration
The plugin supports two type of exports: environment
variables and stack
outputs.
The configuration for each export is the following:
custom
exports
…There are likely many bugs I'm not yet aware of, so contributions and feedback are very welcome!
I hope you found this post helpful. If you have any questions or comments, feel free to leave them below. If you'd like to connect with me, you can find me on LinkedIn or GitHub. Thanks for reading!
Top comments (1)
Great Writeup!