1.4.0 • Public • Published

Serverless API Stage plugin

serverless License: MIT npm version Build Status

Plugin for the serverless framework that allows the use of stages with defined stage variables and logging configuration, when using the AWS provider.

This is a rewritten plugin with the same functionality provided by two existing plugins:


  • In addition to the AWS::APIGateway::Deployment resource, an AWS::APIGateway::Stage resource is also created.
  • The stage is linked to the deployment, to replace the StageName property of the deployment.
  • The stage may have stage variables defined by custom.stageSettings.Variables in your serverless.yml.
  • The stage may have logging and other method properties defined by custom.stageSettings.MethodSettings in your serverless.yml.
  • An AWS::IAM::Role resource is created with the correct permissions to write Cloudwatch logs.
  • This IAM Role for logs is set in the AWS::ApiGateway::Account settings resource.


Install the plugin via npm.

Usage Example

  - serverless-api-stage
    CacheClusterEnabled: true
    CacheClusterSize: '0.5'
      foo: bar
      baz: xyzzy
      LoggingLevel: INFO
      CachingEnabled: true
      CacheTtlInSeconds: 3600
      # see below... 

The full list of MethodSettings available are defined in the AWS CloudFormation documentation.


Please contribute by submitting a pull request, or raising an issue.

Code changes or additions should include corresponding unit test changes or additions. Tests can be run locally using npm test.

Please don't update the version attribute in package.json, as multiple changes might be bundled into a single release. Version bumps will be done in separate pull requests at the time of creating the release and publishing to npm.

Plugin Roadmap

Due to discussion with contributors, there are some breaking changes to be made to the plugin, namely:

  • Make the Role creation optional (and change the default behaviour)
  • Standardise the LogicalId of the ApiGatewayStage resource
  • Multiple stages

A migration guide will be provided.

See v2.

Package Sidebar


npm i serverless-api-stage

Weekly Downloads






Unpacked Size

38.6 kB

Total Files


Last publish


  • leftclick