[@types/serverless] Add Serverless Framework v4 types and comprehensive JSDoc documentation by ofri-peretz · Pull Request #74484 · DefinitelyTyped/DefinitelyTyped

ofri-peretz · 2026-02-05T22:07:16Z

Summary

This PR adds support for Serverless Framework v4 properties and significantly improves the documentation of the AWS provider type definitions.

Breaking Changes

None. This PR only adds optional properties and documentation. All existing type definitions remain unchanged and backward compatible.

🆕 New v4-Specific Properties (`@since v4`)

Root `Serverless` Interface

Property	Type	Description
`stages`	`Stages`	Stage-specific configuration for parameters, observability, and integrations
`build`	`Build \| false`	Native build configuration for TypeScript/JavaScript bundling with EsBuild

`Provider` Interface

Property	Type	Description
`licenseKey`	`string`	Serverless Framework license key for v4+

New Interfaces

Interface	Description
`Stages`	Map of stage names to stage configurations
`StageConfig`	Configuration for a specific stage (params, observability, resolvers)
`StageResolvers`	Variable resolvers configuration (Vault, Terraform, custom)
`VaultResolver`	HashiCorp Vault variable resolver (address, token, version, path)
`TerraformResolver`	Terraform state variable resolver (s3, cloud, remote, http backends)
`Build`	Native build configuration container
`EsBuildConfig`	EsBuild bundler configuration (configFile, bundle, minify, sourcemap, external, target, platform)

`VaultResolver` Properties

Property	Type	Description
`address`	`string`	Vault server URL (or use `VAULT_ADDR` env var)
`token`	`string`	Authentication token (or use `VAULT_TOKEN` env var)
`version`	`string`	Vault API version (default: `v1`)
`path`	`string`	Default path prefix for secrets

`TerraformResolver` Properties

Property	Type	Description
`type`	`'s3' \| 'cloud' \| 'remote' \| 'http'`	Terraform state backend type
`bucket`	`string`	S3 bucket name (for s3 backend)
`key`	`string`	S3 object key for state file (for s3 backend)
`region`	`string`	AWS region (for s3 backend)
`organization`	`string`	Terraform Cloud/HCP organization name
`workspaces`	`{ name?: string }`	Terraform Cloud/HCP workspace configuration
`address`	`string`	HTTP endpoint URL (for http backend)

`EsBuildConfig` Properties

Property	Type	Description
`configFile`	`string`	Path to esbuild config file relative to serverless.yml
`bundle`	`boolean`	Enable bundling
`minify`	`boolean`	Enable minification
`sourcemap`	`boolean`	Enable source maps
`external`	`string[]`	External packages to exclude from bundle
`target`	`string`	Target environment
`platform`	`'node' \| 'browser'`	Platform

⚠️ Deprecation Warnings

The following properties now include @deprecated annotations pointing to their modern replacements:

`Serverless` Interface

Deprecated Property	Replacement	Notes
`variablesResolutionMode`	N/A	Only relevant for v2 migrations
`tenant`	`org`	Use `org` property instead

`Service` Interface

Deprecated Property	Replacement	Notes
`awsKmsKeyArn`	`provider.kmsKeyArn`	Use `kmsKeyArn` at the provider level

`Provider` Interface

Deprecated Property	Replacement	Notes
`lambdaHashingVersion`	N/A	No longer needed in v3+
`role`	`iam.role`	Use IAM configuration instead
`rolePermissionsBoundary`	`iam.role.permissionsBoundary`	Use IAM configuration instead
`iamRoleStatements`	`iam.role.statements`	Use IAM configuration instead
`iamManagedPolicies`	`iam.role.managedPolicies`	Use IAM configuration instead
`cfnRole`	`iam.deploymentRole`	Use IAM configuration instead

`Package` Interface

Deprecated Property	Replacement	Notes
`include`	`patterns`	Use patterns with positive globs

`AwsFunction` Interface

Deprecated Property	Replacement	Notes
`awsKmsKeyArn`	`kmsKeyArn`	Use `kmsKeyArn` property instead

📚 Documentation Improvements

Added comprehensive JSDoc comments with @see links to official Serverless Framework documentation
Added @example blocks with YAML configuration examples
Documented all previously undocumented interfaces (50+ interfaces)
Added property-level documentation for all interface members
Added AWS Lambda Kafka documentation reference
Added migration warning for build property when using legacy bundler plugins

🐛 Bug Fixes

Fixed syntax error in YAML example where */* pattern was breaking JSDoc comment parsing (wrapped in quotes: '*/*')

Testing

✅ TypeScript compilation passes with tsc --noEmit
✅ No breaking changes to existing types
✅ All additions are optional properties

References

@see

… JSDoc documentation - Add v4-specific properties: stages, build, Stages, StageConfig, Build, EsBuildConfig - Add comprehensive JSDoc documentation with @see links to official docs - Fix syntax error in YAML example (*/* pattern breaking JSDoc parsing) - Document all previously undocumented interfaces - Add @SInCE v4 annotations for new properties - Add @deprecated annotations for legacy properties

typescript-bot · 2026-02-05T22:07:55Z

@ofri-peretz Thank you for submitting this PR! I see this is your first time submitting to DefinitelyTyped 👋 — I'm the local bot who will help you through the process of getting things through.

This is a live comment that I will keep updated.

1 package in this PR

serverless — on npm, on unpkg

Code Reviews

Because you edited one package and updated the tests (👏), I can help you merge this PR once someone else signs off on it.

You can test the changes of this PR in the Playground.

Status

✅ No merge conflicts
✅ Continuous integration tests have passed
🕐 Most recent commit is approved by type definition owners or DT maintainers

Once every item on this list is checked, I'll ask you for permission to merge and publish the changes.

Diagnostic Information: What the bot saw about this PR

{
  "type": "info",
  "now": "-",
  "pr_number": 74484,
  "author": "ofri-peretz",
  "headCommitOid": "d3033b3f98f80476496ac7e98cd0a59319b8ae72",
  "mergeBaseOid": "c6ed86518513036ff29ef42c044a3de58a3cd921",
  "lastPushDate": "2026-02-05T22:07:16.000Z",
  "lastActivityDate": "2026-02-05T23:24:50.000Z",
  "hasMergeConflict": false,
  "isFirstContribution": true,
  "tooManyFiles": false,
  "hugeChange": false,
  "popularityLevel": "Popular",
  "pkgInfo": [
    {
      "name": "serverless",
      "kind": "edit",
      "files": [
        {
          "path": "types/serverless/plugins/aws/provider/awsProvider.d.ts",
          "kind": "definition"
        },
        {
          "path": "types/serverless/serverless-tests.ts",
          "kind": "test"
        }
      ],
      "owners": [
        "hassankhan",
        "JonathanWilbur",
        "a-pavlenko",
        "fredericbarthelet",
        "bryan-hunter",
        "thomasaribart",
        "G-Rath",
        "AbdullahAli",
        "fargito",
        "bacarybruno",
        "domazet93"
      ],
      "addedOwners": [],
      "deletedOwners": [],
      "popularityLevel": "Popular"
    }
  ],
  "reviews": [],
  "mainBotCommentID": 3856551927,
  "ciResult": "pass"
}

typescript-bot · 2026-02-05T22:07:58Z

🔔 @hassankhan @JonathanWilbur @a-pavlenko @fredericbarthelet @bryan-hunter @ThomasAribart @G-Rath @AbdullahAli @fargito @bacarybruno @domazet93 — please review this PR in the next few days. Be sure to explicitly select Approve or Request Changes in the GitHub UI so I know what's going on.

…rning - Add configFile property to EsBuildConfig for custom esbuild configuration - Add migration warning for users coming from v3 with bundler plugins - Allow build: false to disable native bundling during plugin migration

@SInCE

… types - Add resolvers property to StageConfig for external data sources - Add VaultResolver interface with address, token, version, path options - Add TerraformResolver interface supporting s3, cloud, remote, http backends - Add StageResolvers interface for custom named resolvers - All new types marked with @SInCE v4 annotation

typescript-bot · 2026-02-05T22:15:43Z

@ofri-peretz The CI build failed! Please review the logs for more information.

Once you've pushed the fixes, the build will automatically re-run. Thanks!

Note: builds that are failing do not end up on the list of PRs for the DT maintainers to review.

@maximum

- Replace @minimum/@maximum tags with inline descriptions (CI lint fix) - Add comprehensive tests for v4 types: stages, build, resolvers - Test VaultResolver, TerraformResolver with all backend types - Test EsBuildConfig with all properties - Test backward compatibility with deprecated properties - Test Kafka event with consumerGroupId

ofri-peretz · 2026-02-05T23:24:50Z

@czubocha @eahefnawy

typescript-bot added Popular package This PR affects a popular package (as counted by NPM download counts). Untested Change This PR does not touch tests labels Feb 5, 2026

typescript-bot added this to Pull Request Status Board Feb 5, 2026

typescript-bot moved this to Waiting for Code Reviews in Pull Request Status Board Feb 5, 2026

ofri-peretz added 2 commits February 5, 2026 16:10

typescript-bot added the The CI failed When GH Actions fails label Feb 5, 2026

typescript-bot moved this from Waiting for Code Reviews to Needs Author Action in Pull Request Status Board Feb 5, 2026

typescript-bot removed The CI failed When GH Actions fails Untested Change This PR does not touch tests labels Feb 5, 2026

typescript-bot moved this from Needs Author Action to Waiting for Code Reviews in Pull Request Status Board Feb 5, 2026

style: remove extra blank lines in awsProvider.d.ts

d3033b3

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

[@types/serverless] Add Serverless Framework v4 types and comprehensive JSDoc documentation#74484

[@types/serverless] Add Serverless Framework v4 types and comprehensive JSDoc documentation#74484
ofri-peretz wants to merge 5 commits intoDefinitelyTyped:masterfrom
ofri-peretz:feature/serverless-add-v4-types

ofri-peretz commented Feb 5, 2026 •

edited

Loading

Uh oh!

typescript-bot commented Feb 5, 2026 •

edited

Loading

Uh oh!

typescript-bot commented Feb 5, 2026

Uh oh!

typescript-bot commented Feb 5, 2026

Uh oh!

ofri-peretz commented Feb 5, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Conversation

ofri-peretz commented Feb 5, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Breaking Changes

🆕 New v4-Specific Properties (@since v4)

Root Serverless Interface

Provider Interface

New Interfaces

VaultResolver Properties

TerraformResolver Properties

EsBuildConfig Properties

⚠️ Deprecation Warnings

Serverless Interface

Service Interface

Provider Interface

Package Interface

AwsFunction Interface

📚 Documentation Improvements

🐛 Bug Fixes

Testing

References

Uh oh!

typescript-bot commented Feb 5, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

1 package in this PR

Code Reviews

Status

Uh oh!

typescript-bot commented Feb 5, 2026

Uh oh!

typescript-bot commented Feb 5, 2026

Uh oh!

ofri-peretz commented Feb 5, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

ofri-peretz commented Feb 5, 2026 •

edited

Loading

🆕 New v4-Specific Properties (`@since v4`)

Root `Serverless` Interface

`Provider` Interface

`VaultResolver` Properties

`TerraformResolver` Properties

`EsBuildConfig` Properties

`Serverless` Interface

`Service` Interface

`Provider` Interface

`Package` Interface

`AwsFunction` Interface

typescript-bot commented Feb 5, 2026 •

edited

Loading