DEV Community

Cover image for Serverless Plugin: Exporting Environment Variables and Stack Outputs
Chris
Chris

Posted on • Originally published at zirkelc.dev

Serverless Plugin: Exporting Environment Variables and Stack Outputs

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

Enter fullscreen mode Exit fullscreen mode

When deployed using serverless deploy --stage dev:

Terminal

The defined environment variables are saved in a file .env.dev:

# .env.dev
FOO: bar
STAGE: dev
REGION: us-east-1
SERVICE: acme-service
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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
# ...
Enter fullscreen mode Exit fullscreen mode

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.

GitHub logo zirkelc / serverless-exports-plugin

Serverless plugin to export environment variables and stack outputs

CI npm npm

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.

Terminal

Usage

Install the plugin as a development dependency in your Serverless project:

npm install --save-dev serverless-exports-plugin
Enter fullscreen mode Exit fullscreen mode

Then add the plugin to your serverless.yml file:

plugins
  - serverless-exports-plugin
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

That's it! Now you can run serverless deploy or serverless package and the plugin will generate the exports for you.

Configuration

The plugin supports to type of exports: environment variables and stack outputs.

The configuration for each export is the following:

custom
  exports:
    <environment |
Enter fullscreen mode Exit fullscreen mode

There are likely many bugs I'm not yet aware of, so contributions and feedback are very welcome!

Top comments (1)

Collapse
 
niklampe profile image
Nik

Great Writeup!