Registry / aws / serverless-api-stage

serverless-api-stage

library1.4.0jsnpmunverified

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.

aws devops

npm install serverless-api-stage

github ↗package ↗

INSTALL

IMPORT

SIG · SERVERLESS-API-STA

serverless-api-stage

awsjavascriptv1.4.0

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

default import

✓ plugins: - serverless-api-stage

✗ npm install serverless-api-stage --save

Plugin is declared in serverless.yml, not imported in code. Install via npm but registration is in YAML config.

serverless plugin object (programmatic use)

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

✗ import ServerlessApiStage from 'serverless-api-stage';

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

TypeScript type import

✓ // No official types; use @types/serverless or declare module

✗ import { ServerlessApiStage } from 'serverless-api-stage';

Package does not ship TypeScript declarations. Use inline types or custom declaration file.

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

Debug

Known issues

breakingV2 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.

affects: >=2.0.0

breakingV2 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.

affects: >=2.0.0

deprecatedThe 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.

affects: all

gotchaThe 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.

affects: >=1.0.0

gotchaStage 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.

affects: >=1.0.0

Errors

Common errors & fixes

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

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: The CloudFormation template is invalid: Resource [ApiGatewayStage] already exists in template

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).

Logging not working: No logs in CloudWatch Logs

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.

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

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

fix

Example:
custom:
  stageSettings:
    Variables:
      myVar: myValue

Upgrade

Version history

1.4.0latest on npm

Audit

Dependencies

serverlessrequiredRuntime peer dependency; the plugin extends the Serverless Framework engine.

Agent activity

12 hits · last 30 days

node

Amazon

Resources

githubhttps://github.com/leftclickben/serverless-api-stage ↗

packagehttps://www.npmjs.com/package/serverless-api-stage ↗