{"id":18787,"library":"serverless-api-stage","title":"serverless-api-stage","description":"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.","status":"maintenance","version":"1.4.0","language":"javascript","source_language":"en","source_url":"ssh://git@github.com/leftclickben/serverless-api-stage","tags":["javascript","serverless","api","stage","variable","logging","gateway"],"install":[{"cmd":"npm install serverless-api-stage","lang":"bash","label":"npm"},{"cmd":"yarn add serverless-api-stage","lang":"bash","label":"yarn"},{"cmd":"pnpm add serverless-api-stage","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Runtime peer dependency; the plugin extends the Serverless Framework engine.","package":"serverless","optional":false}],"imports":[{"note":"Plugin is declared in serverless.yml, not imported in code. Install via npm but registration is in YAML config.","wrong":"npm install serverless-api-stage --save","symbol":"default import","correct":"plugins:\n  - serverless-api-stage"},{"note":"This is a CommonJS package; no default export. Use require().","wrong":"import ServerlessApiStage from 'serverless-api-stage';","symbol":"serverless plugin object (programmatic use)","correct":"const ServerlessApiStage = require('serverless-api-stage');\n// then pass to Serverless constructor as plugin"},{"note":"Package does not ship TypeScript declarations. Use inline types or custom declaration file.","wrong":"import { ServerlessApiStage } from 'serverless-api-stage';","symbol":"TypeScript type import","correct":"// No official types; use @types/serverless or declare module"}],"quickstart":{"code":"# serverless.yml\nservice: my-service\nprovider:\n  name: aws\n  runtime: nodejs14.x\nplugins:\n  - serverless-api-stage\ncustom:\n  stageSettings:\n    CacheClusterEnabled: true\n    CacheClusterSize: '0.5'\n    Variables:\n      foo: bar\n      baz: xyzzy\n    MethodSettings:\n      - HttpMethod: ANY\n        ResourcePath: /*\n        LoggingLevel: INFO\n        DataTraceEnabled: true\n        MetricsEnabled: true\n        # ... more per-path settings\nfunctions:\n  hello:\n    handler: handler.hello\n    events:\n      - http:\n          path: hello\n          method: get","lang":"yaml","description":"Minimal serverless.yml configuration to enable stage variables and detailed logging via the plugin."},"warnings":[{"fix":"Review migration guide when v2 is released; explicitly set role settings in custom.stageSettings.","message":"V2 milestone plans to make Role creation optional and change default behaviour, breaking existing stacks that rely on automatic role creation.","severity":"breaking","affected_versions":">=2.0.0"},{"fix":"Use resource logical IDs directly via CloudFormation refs; update any hardcoded references after upgrade.","message":"V2 milestone plans to standardise the LogicalId of the ApiGatewayStage resource, which will cause stack replacement.","severity":"breaking","affected_versions":">=2.0.0"},{"fix":"Migrate to serverless-api-stage or use native Serverless Framework stage management.","message":"The plugin's original functionality replaced two existing plugins; those plugins are now deprecated.","severity":"deprecated","affected_versions":"all"},{"fix":"Set custom.stageSettings.Role to your existing role ARN to override automatic creation. See docs.","message":"The plugin requires IAM role creation for logging; if you already have a custom logging role, you must adapt.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Use Serverless Framework variable syntax: ${self:custom.stageSettings.Variables.foo} in function configuration.","message":"Stage variables defined in custom.stageSettings.Variables are not automatically injected into functions; you must reference them via ${self:custom.stageSettings.Variables.*}.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-25T00:00:00.000Z","next_check":"2026-07-24T00:00:00.000Z","problems":[{"fix":"Ensure plugin is listed under 'plugins:' and installed via npm. Use 'serverless plugin list' to verify.","cause":"Plugin not properly installed or declared in serverless.yml.","error":"No AWS::ApiGateway::Stage resource created, only Deployment"},{"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).","cause":"Collision with existing stage resource (e.g., from manual resource definition or another plugin).","error":"Error: The CloudFormation template is invalid: Resource [ApiGatewayStage] already exists in template"},{"fix":"Ensure the plugin creates the IAM role (do not override). Verify LoggingLevel is set in MethodSettings for the target HTTP method/resource.","cause":"IAM role not created or incorrect permissions.","error":"Logging not working: No logs in CloudWatch Logs"},{"fix":"Example:\ncustom:\n  stageSettings:\n    Variables:\n      myVar: myValue","cause":"Formatting issue in serverless.yml: Variables should be key-value pairs under custom.stageSettings.Variables.","error":"Cannot set stage variables: 'Variables' property must be a map"}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}