@orangejellyfish/serverless-config-merge

serverless-config-merge

An opinionated command-line utility to merge Serverless Framework configuration files. Move common configuration into smaller, maintainable individual files and import them prior to deployment.

service: example-service

provider:
  $<<: ${file(provider-defaults.yml)}
  region: eu-west-1

Installation

Install as a dev dependency to your Serverless Framework project with npm. This is preferred to a global install to allow you to have control over the version of the tool on a per-project basis.

npm install --save-dev @orangejellyfish/serverless-config-merge

Usage

Move common configuration into YAML files. For example, a common "provider" config might include the provider name and region in provider-defaults.yml:

name: aws
region: eu-west-1

Reference a file with a special key. The key is $<< by default, inspired by the YAML merge key proposal. The value must be a Serverless Framework "file" variable, or an array of them. If a key appears in a file that is merged in and also in the source, the value in the source takes precedence:

service: example-service

provider:
  $<<: ${file(provider-defaults.yml)} # Merge in the defaults
  region: eu-west-2 # Override the default from the merged file

plugins:
  $<<:
    - ${file(plugin-defaults-1.yml)} # Merge in multiple files
    - ${file(plugin-defaults-2.yml)}

Run serverless-config-merge (or the alias sls-config-merge) prior to your deployment. For example:

MERGED_CONFIG_FILE=serverless-merged.yml
npx serverless-config-merge -o $MERGED_CONFIG_FILE
sls deploy --config $MERGED_CONFIG_FILE
rm $MERGED_CONFIG_FILE

Options

• -i - input file, defaults to serverless.yml
• -o - output file, defaults to serverless-merge.yml
• -k - merge key, defaults to $<<

Design choices

• Designed as a standalone executable to run prior to deployment because the Severless Framework plugin system does not provide an early enough hook to merge all relevant properties. For example, the serverless-merge-config plugin is unable to merge the provider.name property because it's presence is validated by the framework too early.

• Writes a new config file alongside your existing Serverless Framework config file. It would have been preferable to write this file to a hidden directory such as .serverless but that would require rewriting any other paths in the file. As it stands, you'll have to add this file to .gitignore or delete it post-deployment, as shown in the example above.

• The new config file is written as JSON rather than YAML, simply because the Serverless Framework supports both and since the output is already a JavaScript object it's slightly easier to output it as JSON.

• Only supports Serverless Framework configuration files written in YAML. If your configuration file is written in JSON you can use the same idea with minor tweaks - pull requests welcome!