serverless-plugin-composed-vars

This plugin is Serverless variables reimagined, making them composable and easier to manage. It automatically scans for variables.yml and environment.yml files in your service directory to assign custom and environment variables in your service. In addition, it easily allows for stage specific overrides by loading variables.stage.yml and environment.stage.yml where stage is your deployment stage, like beta or prod.

Installation

yarn add -D serverless-plugin-composed-vars

Add serverless-plugin-composed-vars as the first plugin in your serverless.yml file:

plugins:
  - serverless-plugin-composed-vars
  - other-serverless-plugin

Usage

Custom Variables

Create a variables.yml file for default variable definitions:

# variables.yml
myServiceName: Always My Service
myEndpoint: beta.endpoint.com
webpack:
  webpackConfig: 'beta-webpack.config.js'
  includeModules: true
  packager: yarn

Create a stage specific variable file:

# variables.prod.yml
myEndpoint: prod.endpoint.com
webpack:
  webpackConfig: 'webpack.config.js'
  includeModules: false

prod stage environments will result in:

myServiceName: Always My Service
myEndpoint: prod.endpoint.com
webpack:
  webpackConfig: 'webpack.config.js'
  includeModules: false
  packager: yarn

Environment Variables

Create an environment.yml file for default definitions:

# environment.yml
MY_ENDPOINT: ${self:custom.myEndpoint}
STAGE: beta

Create a stage specific environment file:

# environment.prod.yml
STAGE: prod

prod stage environments will result in:

MY_ENDPOINT:: ${self:custom.myEndpoint}
STAGE: prod

Supported File Extensions

yml
yaml
js
json

Advanced Usage

Service File Definitions

You can additionally define custom variables and environment variables in your service file. Note that these have the least priority and will be overridden by variables.yml and environment.yml.

# serverless.yml
custom:
  googlesWebsite: www.google.com
  myEndpoint: dev.endpoint.com
provider:
  environment:
    THE_ANSWER_IS: 42
    STAGE: dev

Using the examples above, prod stage environments will result in:

# Custom Variables
googlesWebsite: www.google.com
myServiceName: Always My Service
myEndpoint: prod.endpoint.com
webpack:
  webpackConfig: 'webpack.config.js'
  includeModules: false
  packager: yarn

# Environment Variables
THE_ANSWER_IS: 42
MY_ENDPOINT:: ${self:custom.myEndpoint}
STAGE: prod

Alternate File Location

If you'd like to specify a different directory or variable file name, just add a file reference for custom or environment:

# serverless.yml
custom: ${file(./different/path/custom.yml)}
provider:
  environment: ${file(./different/path/env.yml)}

In this example, variables will be overridden with stage specific definitions defined in the following files:

Custom: ./different/path/custom.stage.yml

Environment: ./different/path/env.stage.yml

Troubleshooting

You can troubleshoot your variable setup by running the composed-vars merged and composed-vars computed commands. For example, npx serverless composed-vars merged will output the merged variables before any of the reference properties are computed. Whereas npx serverless composed-vars computed will output the fully computed values.

Limitations

serverless-plugin-composed-vars will only override custom variables and environment variables defined in main service file: serverless.yml. It does not perform an expansive search to override outside of the custom and environment definitions. Below are some examples that won't be overridden. However, with the structure of serverless-plugin-composed-vars, all of them can easily be handled by moving the definitions to the variables.yml file.

Examples

Functions and Resources

# serverless.yml
plugins:
  - serverless-plugin-composed-vars
provider:
  stackName: ${file(./another-var-file.yml):stackName}
functions:
  hello:
    handler: handler.hello
    events: ${file(./hello-events.yml)}
  hi:
    handler: handler.hi
    events:
      - schedule: ${file(./schedule-vars.yml):globalSchedule}
resources:
  Resources:
    itemsTable: ${file(./items-table-vars.yml)}
    usersTable:
      tableName: ${file(./table-vars.yml):usersTable}

Deep File References

# variables.yml
tableNames: ${file(./table-names.yml)}
# This will not be converted to table-names.stage.yml

Recursive/Nested Variable File Names:

# serverless.yml
custom: ${file(./${self:service.name}.json)}

Avoiding Limitations

Move all of these references to the variables.yml and take advantage of stage overrides.

# serverless.yml
plugins:
  - serverless-plugin-composed-vars
provider:
  stackName: ${self:custom.stackName}
functions:
  hello:
    handler: handler.hello
    events: ${self:custom.helloEvents}
  hi:
    handler: handler.hi
    events:
      - schedule: ${self:custom.globalSchedule}
resources:
  Resources:
    itemsTable: ${self:custom.itemsTable}
    usersTable:
      tableName: ${self:custom.tableNames.usersTable}

# variables.yml
stackName: My Stack
helloEvents:
  - http
  - schedule
schedule:
  globalSchedule: 1 hour
itemsTable: ${file(./items-table-vars.yml)}
tableNames: ${file(./table-names.yml)}

# variables.prod.yml
stackName: My Production Stack
schedule:
  globalSchedule: 5 minutes
itemsTable: ${file(./items-table-vars.prod.yml)}
tableNames: ${file(./table-names.prod.yml)}