Serverless Framework V3 Is Live!

Jan 27, 2022

We are excited to announce the release of Serverless Framework v3.

This new major version brings a cleaner and redesigned CLI experience as well as a brand new feature: stage parameters.

On top of that, we've worked on cleaning up the dependencies to make the serverless package 40% lighter and get rid of NPM security warnings.

Upgrading

Before we dive into the new features, let's talk about upgrading from v2 to v3.

As mentioned in the v3 beta announcement, we have revisited many deprecations and breaking changes to make the upgrade to v3 easier.

To upgrade safely, follow these 3 steps:

  1. Upgrade to the latest v2 version (e.g. via "npm -g install serverless@2")
  2. Fix any deprecation you encounter when deploying with v2
  3. When there are no deprecations left, you are safe to upgrade to v3:
$ npm -g install serverless
...

# Check the version
$ serverless --version
Framework Core: 3.0.0

If you installed serverless as a standalone binary, read these instructions instead.

You can read the complete "Upgrading to v3" guide to read about all breaking changes and instructions for specific cases.

It is also possible to use both v2 and v3 in different projects. Read more about this in the v3 upgrade guide.

Finally, if you are looking to get started with Serverless Framework v3, check out our new Getting Started guide.

Stage parameters

Serverless Framework v3 introduces "stage parameters". It allows changing the service configuration based on the current stage.

This is particularly useful when deploying services to multiple environments, like a development/staging environment and a production environment.

Parameters can be defined under the new params key, and can be used via "${param:xxx}" variables:

# serverless.yml
service: myapp

provider:
  name: aws
  environment:
    APP_DOMAIN: ${param:domain}

params:
  prod:
    domain: myapp.com
  dev:
    domain: preview.myapp.com

In the example above, the "${param:domain}" variable will resolve to:

  • myapp.com for the "prod" stage
  • preview.myapp.com for the "dev" stage

It is also possible to define default parameter values via the default key. These values will apply to all the other stages:

params:
  default:
    domain: ${sls:stage}.preview.myapp.com
  prod:
    domain: myapp.com
  dev:
    domain: preview.myapp.com

Note that this new feature is born out of a common pattern: using the "custom" section with nested variables. For example:

provider:
  environment:
	APP_DOMAIN: ${self:custom.stages.${sls:stage}.domain}

If you are already using this pattern, we hope the new stage parameters can help simplify your configuration and make it more maintainable!

Finally, thanks to the optional integration with Serverless Dashboard, you can also store secret values securely and retrieve them via the "${param:my-secret}" variable syntax.

Learn everything about stage parameters in the Parameters documentation.

Redesigned CLI experience

Over the years, Serverless Framework has become the most advanced tool to create and deploy serverless applications.

This comes with a challenge: maintaining a clean and simple experience for users. As deprecations, plugins, and cloud resources multiply, so does the noisiness of the CLI.

Serverless Framework v3 is the framework you know and love, with a reimagined interface. We started from scratch and asked ourselves: "as a user, what do I need to know?" at each step of each command. The new design:

  • focuses on actionable information
  • removes all extra noise
  • is easier on the eyes with minimalistic colors and styles

Below is a preview of the new design with the most common commands.

Deploy

The "serverless deploy" command now features a clean and minimal output. Here is a comparison of v2 (left) and v3 (right):

Verbose output

Serverless Framework v3 now supports the standard "--verbose" flag to output more details.

That option can be particularly useful in CI/CD, for example to get a detailed history of the CloudFormation deployment:

Clear errors

The error screen has been improved: any failure is now clearly signaled, secondary information is toned down and the error message is printed last, to appear right above the command prompt.

On top of that, CloudFormation errors now contain more details about resources and their statuses:

Cleaner logs

The "serverless logs" command now features a cleaner and lighter output, that brings more focus on the content of the logs.

New serverless onboarding

Serverless Framework can now interactively set up new projects: just run "serverless" in an empty directory and follow the prompt.

The interactive setup also lets you set up the Serverless Dashboard in a few steps. Run "serverless" in an existing project and get access to premium monitoring, AWS account management, parameters, and more.

Upgrading plugins

We have worked hard at helping plugins be ready for Serverless Framework v3.

That being said, given the size of the ecosystem, we have identified 3 categories of plugins:

  1. Plugins that are compatible with v3 and integrate with the new CLI design.
  2. Plugins that are compatible with v3.
  3. Plugins that are not compatible with v3 yet.

Fortunately, most of the plugins are in categories 1 or 2. Some plugins might not integrate fully with the new design yet, but they should work fine.

We want to help developers take their plugins to the next level! This is why v3 comes with:

If you need help updating your plugin, jump in the GitHub discussion and let us know.

Architectural Guidance & Commercial Support

While Serverless Framework makes it easy to create radically efficient cloud apps, nothing beats the confidence you’ll gain from working with the team that built the Serverless Framework.

Serverless Inc's support offering includes architectural reviews to highlight improvements and standards you can leverage to scale projects and teams.  Our support offering also features a private Slack channel where you can interact directly with our team and discuss plugins, the Framework and serverless architectures on AWS.  Consider us your partner in serverless success. 

Learn more about Serverless Premium Support.

Subscribe to our newsletter to get the latest product updates, tips, and best practices!

Thank you! Your submission has been received!
Oops! Something went wrong while submitting the form.