serverless-api-stage

1.4.0 verified Sat Apr 25 auth: no javascript maintenance

A Serverless Framework plugin for AWS API Gateway that enables stage variables and detailed logging configuration. Current stable version 1.4.0 adds custom Access Logging. The plugin creates an AWS::ApiGateway::Stage resource linked to the deployment, an IAM role for CloudWatch logs, and supports stage variables, method settings, cache, client certificate ID, and documentation version. It consolidates features from two separate plugins into one. Maintenance is sporadic; the roadmap includes breaking changes for v2 (optional role, standardised logical IDs, multiple stages). Key differentiator: tighter integration than manual CloudFormation.

Common errors

error No AWS::ApiGateway::Stage resource created, only Deployment ↓

cause Plugin not properly installed or declared in serverless.yml.

fix

Ensure plugin is listed under 'plugins:' and installed via npm. Use 'serverless plugin list' to verify.

error Error: The CloudFormation template is invalid: Resource [ApiGatewayStage] already exists in template ↓

cause Collision with existing stage resource (e.g., from manual resource definition or another plugin).

fix

Remove duplicate Stage resource from serverless.yml resources section, or disable the plugin's stage creation by setting custom.stageSettings.createStage: false (if supported in v2).

error Logging not working: No logs in CloudWatch Logs ↓

cause IAM role not created or incorrect permissions.

fix

Ensure the plugin creates the IAM role (do not override). Verify LoggingLevel is set in MethodSettings for the target HTTP method/resource.

error Cannot set stage variables: 'Variables' property must be a map ↓

cause Formatting issue in serverless.yml: Variables should be key-value pairs under custom.stageSettings.Variables.

fix

Example: custom: stageSettings: Variables: myVar: myValue

Warnings

breaking V2 milestone plans to make Role creation optional and change default behaviour, breaking existing stacks that rely on automatic role creation. ↓

fix Review migration guide when v2 is released; explicitly set role settings in custom.stageSettings.

breaking V2 milestone plans to standardise the LogicalId of the ApiGatewayStage resource, which will cause stack replacement. ↓

fix Use resource logical IDs directly via CloudFormation refs; update any hardcoded references after upgrade.

deprecated The plugin's original functionality replaced two existing plugins; those plugins are now deprecated. ↓

fix Migrate to serverless-api-stage or use native Serverless Framework stage management.

gotcha The plugin requires IAM role creation for logging; if you already have a custom logging role, you must adapt. ↓

fix Set custom.stageSettings.Role to your existing role ARN to override automatic creation. See docs.

gotcha Stage variables defined in custom.stageSettings.Variables are not automatically injected into functions; you must reference them via ${self:custom.stageSettings.Variables.*}. ↓

fix Use Serverless Framework variable syntax: ${self:custom.stageSettings.Variables.foo} in function configuration.

Install

npm install serverless-api-stage

yarn add serverless-api-stage

pnpm add serverless-api-stage

Imports

default import
wrong
```
npm install serverless-api-stage --save
```
correct
```
plugins:
  - serverless-api-stage
```
Plugin is declared in serverless.yml, not imported in code. Install via npm but registration is in YAML config.

serverless plugin object (programmatic use)

wrong

import ServerlessApiStage from 'serverless-api-stage';

correct

const ServerlessApiStage = require('serverless-api-stage');
// then pass to Serverless constructor as plugin

This is a CommonJS package; no default export. Use require().

TypeScript type import
wrong
```
import { ServerlessApiStage } from 'serverless-api-stage';
```
correct
```
// No official types; use @types/serverless or declare module
```
Package does not ship TypeScript declarations. Use inline types or custom declaration file.

Quickstart

Minimal serverless.yml configuration to enable stage variables and detailed logging via the plugin.

# serverless.yml
service: my-service
provider:
  name: aws
  runtime: nodejs14.x
plugins:
  - serverless-api-stage
custom:
  stageSettings:
    CacheClusterEnabled: true
    CacheClusterSize: '0.5'
    Variables:
      foo: bar
      baz: xyzzy
    MethodSettings:
      - HttpMethod: ANY
        ResourcePath: /*
        LoggingLevel: INFO
        DataTraceEnabled: true
        MetricsEnabled: true
        # ... more per-path settings
functions:
  hello:
    handler: handler.hello
    events:
      - http:
          path: hello
          method: get