Introduction

Here at Serverless Guru, there is always an ongoing discussion about what’s new and what’s coming, so we can learn, anticipate, and be ready for the upcoming changes. Recently we had several threads regarding upcoming changes in the Serverless framework, and just recently V3 was released. Let’s look into the few important features. 

Stage Params 

This feature is not a breaking change, but it is a very nice touch by the Serverless team to help developers make their templates more readable. To get some context, let’s start with an example. It’s not uncommon that businesses assign subdomains per stage. We want to have api.serverlessguru.com for the production while we wish to have our dev and staging environment accessed with api-dev.serverlessguru.com and api-staging.serverlessguru.com, respectively. The easiest way to do it with a Serverless framework is to use the serverless-domain-manager plugin. 

So far, we have been using the “custom” attribute in our serverless.yml file to make this work. Here is the snippet that explains how to have a subdomain per stage configuration: 

provider:
  stage: ${opt:stage, 'dev'}

custom:
  domains:
    dev:
      domain: api-dev.serverlessguru.com
      cert: dev-certificate-arn

    staging:
      domain: api-staging.serverlessguru.com
      cert: staging-certificate-arn
    prod:
      domain: api.serverlessguru.com
      cert: production-certificate-arn

  customDomain:
    domainName: ${self:custom.domains.${self:provider.stage}.domain}
    certificateArn: ${self:custom.domains.${self:provider.stage}.cert}

With the new multi-stage variables, we can make it more readable:

service: serverlessguru

params:
  dev: 
    domain: api-dev.serverlessguru.com
    cert: dev-certificate-arn
  staging: 
    domain: api-staging.serverlessguru.com
    cert: staging-certificate-arn
  prod: 
    domain: api.serverlessguru.com
    cert: production-certificate-arn
  
custom:
  customDomain:
    domainName: ${params:domain}
    certificateArn: ${param:cert}

.env files

So far .env files have been supported only by using plugins. Version 3 supports .env files natively. To use .env files, we need to add the following configuration:

useDotenv: true
 
provider:
  environment:
    PROFILE: ${env:PROFILE}

Then create .env file and set your value as desired:

PROFILE=test

projectDir

This one created a lot of negative feedback from the community. It is a breaking change that no longer allows you to reference yml file outside of the project directory. This is an important feature that allows creating and using shared configuration across services to simplify development and follow DRY principle. Since this feature is widely adopted, it has a huge impact on the current deployments. 

You can still use this feature, but you need to specify projectDir attribute in all projects to have a valid template. This is not a problem for a new project, but the old projects will be heavily affected, requiring many unplanned refactorings and maybe rewrites.

Based on a recent Twitter discussion, it looks like it will not happen after all, but it’s better to be aware and prepared if something changes.

Referencing SSM parameters

In the previous version of the framework, we had to specify ~true suffix on the SSM parameter name to read encrypted values.

environment:
    DECRYPTED:  ${ssm:ENCRYPTED_VALUE~true}

With the latest version, not that this is a  requirement anymore, but you have to remove it, or otherwise it will be treated as a parameter name which can lead to an error. 

environment:
    DECRYPTED:  ${ssm:ENCRYPTED_VALUE}

Error output

The error output is much more readable than earlier. Here is an example:

We don’t need to scroll and read through the lines of meaningless output in the terminal to find what went wrong. CLI will print an Error with convenient information at the end. 

Conclusion

In this article, we discussed several significant changes in the latest version of the Serverless framework. If you plan to upgrade your services to the new version of the CLI, you need to install the latest stable version 2 of the framework, then read and address the deprecation warning in the console output. To prepare for the breaking changes, you can turn on a new variable resolution mode used in version 3 to avoid unpleasant surprises. A complete migration guide is also available on the Serverless framework website.