Serverless, a framework for managing cloud applications, is a very powerful tool. As your application grows in complexity, it can be difficult to manage deployment variables based on different stages (development, QA, production). Currently it isn’t easy to reference deployment specific custom or environment variables. I knew there had to be a better way of handling these variables while also making them composable. After some research into serverless’ architecture, I came up with a plugin that does just that: serverless-plugin-composed-vars.

What does it do?

serverless-plugin-composed-vars lets you define stage specific variable files. It overrides the variables defined in your serverless.yml or in separate variables.yml and environment.yml files for custom and environment variables respectively. To define stage specific files, just insert the stage name into the file like so: variables.stage.yml or environment.stage.yml. For example, if you’d like to create variable files for your stage named “prod”, you’d name the files variables.prod.yml and environment.prod.yml.

Let’s see it in action:

https://gist.github.com/chris-feist/0c044a8afaac09c3d66a0f9273cd4070

Installation

custom:

  googlesWebsite: www.google.com

  myEndpoint: api.endpoint.com/dev



provider:

  environment:

    THE_ANSWER_IS: 42

    USER_TABLE_NAME: Test-Users

    MY_ENDPOINT: ${self:custom.myEndpoint}

# variables.prod.yml



myEndpoint: api.endpoint.com

# environment.prod.yml



USER_TABLE_NAME: Users

Using the example files above, custom and environment variables are composed and computed into the following for a “prod” deployment stage:

custom:

  googlesWebsite: www.google.com

  myEndpoint: api.endpoint.com



environment:

  THE_ANSWER_IS: 42

  USER_TABLE_NAME: Users

  MY_ENDPOINT: api.endpoint.com

For a cleaner serverless.yml service file, you can separate your default variables into their own variables.yml and environment.yml files. serverless-plugin-composed-vars will automatically read those files when composing your deployment variables. Note that the serverless.yml file variables have the least priority when also using default variable files.

How do I use it?

Install

Install the plugin using your favorite package manager:

npm install -D serverless-plugin-composed-vars

or

yarn add -D serverless-plugin-composed-vars

Enable

Add the plugin to your service file:

# serverless.yml



plugins:

  - serverless-plugin-composed-vars

  - other-serverless-plugin

Note: To ensure compatibility with other plugins, it is recommended that serverless-plugin-composed-vars be the first plugin in the plugins list.

Create

Create deployment stage variable files. The default file names are variables.stage.yml and environment.stage.yml for custom and environment variables. Here’s an example project structure for custom variables:

# variables.yml



endpoint: endpoint.com/test  # Default custom variables, such as dev endpoint

# variables.qa.yml



endpoint: endpoint.com/qa    # QA specific custom variables

# variables.prod.yml



endpoint: endpoint.com       # Prod specific custom variables

Advanced Usage

For advanced usage and configuration, see the GitHub Readme.

How does it work?

Under the covers, serverless-plugin-composed-vars leverages the fact that serverless doesn’t compute variables until hooks are executed. This allows the plugin to compose deployment stage variables and rewrite them before your service is packaged for deployment.

Check it out!

Now that you’ve seen how easy it is to use deployment stage variables, give the plugin a shot. Leave any comments or suggestions here or submit issues on the GitHub repository.