{"id":14913,"library":"serverless-plugin-typescript","title":"Serverless TypeScript Plugin","description":"The `serverless-plugin-typescript` package offers zero-configuration TypeScript support for applications built with the Serverless Framework, particularly targeting AWS Lambda functions. It automatically handles the compilation of TypeScript source files to JavaScript during standard Serverless deployment lifecycle hooks, such as `sls package`, `sls deploy`, and `sls deploy function`. The current stable version is 2.1.5, with the last update in June 2023 addressing minor bug fixes. Major version changes are less frequent, with v2.0.0 released in September 2021, indicating a slower, maintenance-oriented release cadence rather than rapid feature additions. A key differentiator is its 'zero-config' philosophy, allowing developers to integrate TypeScript without needing to set up Webpack, Babel, or other complex build tools, making it an attractive option for simpler Serverless projects. It supports modern ES2015+ features like `async/await` and works well with `sls invoke local` (including a `--watch` mode) and the popular `serverless-offline` plugin for local development and testing.","status":"active","version":"2.1.5","language":"javascript","source_language":"en","source_url":"https://github.com/serverless/serverless-plugin-typescript","tags":["javascript","serverless","serverless plugin","typescript","aws lambda"],"install":[{"cmd":"npm install serverless-plugin-typescript","lang":"bash","label":"npm"},{"cmd":"yarn add serverless-plugin-typescript","lang":"bash","label":"yarn"},{"cmd":"pnpm add serverless-plugin-typescript","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Peer dependency for Serverless Framework integration.","package":"serverless","optional":false},{"reason":"Peer dependency for TypeScript compilation.","package":"typescript","optional":false}],"imports":[{"note":"This package is a Serverless Framework plugin and is enabled by listing its name in the `plugins` array within your `serverless.yml` configuration file. It does not provide JavaScript/TypeScript symbols for direct `import` or `require` into your application code.","symbol":"serverless-plugin-typescript (YAML config)","correct":"plugins:\n  - serverless-plugin-typescript"}],"quickstart":{"code":"/* serverless.yml */\nservice: my-typescript-service\n\nframeworkVersion: \"2 || 3\"\n\nprovider:\n  name: aws\n  runtime: nodejs16.x # Or a newer supported Node.js version\n  region: us-east-1\n\nplugins:\n  - serverless-plugin-typescript\n  - serverless-offline # Example for common integration\n\nfunctions:\n  hello:\n    handler: handler.hello\n    events:\n      - http:\n          path: hello\n          method: get\n\n/* handler.ts */\nimport { APIGatewayProxyHandler } from 'aws-lambda';\n\nexport const hello: APIGatewayProxyHandler = async (event, context) => {\n  return {\n    statusCode: 200,\n    body: JSON.stringify(\n      {\n        message: 'Go Serverless with TypeScript! Your function executed successfully!',\n        input: event,\n      },\n      null,\n      2\n    ),\n  };\n};\n\n/* tsconfig.json */\n{\n  \"compilerOptions\": {\n    \"preserveConstEnums\": true,\n    \"strictNullChecks\": true,\n    \"sourceMap\": true,\n    \"allowJs\": true,\n    \"target\": \"es5\", // Plugin default, cannot be overridden via tsconfig.json for compilation target\n    \"outDir\": \".build\", // Plugin default, cannot be overridden\n    \"moduleResolution\": \"node\",\n    \"lib\": [\"es2015\"], // Plugin default\n    \"rootDir\": \"./\", // Plugin default, cannot be overridden\n    \"esModuleInterop\": true,\n    \"resolveJsonModule\": true\n  },\n  \"include\": [\"**/*\"],\n  \"exclude\": [\"node_modules\", \".build\"]\n}\n","lang":"typescript","description":"Demonstrates how to enable the plugin and create a basic TypeScript-based AWS Lambda function, including the necessary `serverless.yml`, `handler.ts`, and `tsconfig.json` files. This setup enables automatic compilation and local testing with `serverless-offline`."},"warnings":[{"fix":"Upgrade your Serverless Framework installation to v2.x or v3.x (`npm install -g serverless`).","message":"serverless-plugin-typescript v2.0.0 dropped support for Serverless Framework v1.x. Users on older Serverless versions must upgrade their framework or use a v1.x version of the plugin.","severity":"breaking","affected_versions":">=2.0.0"},{"fix":"Ensure your Node.js environment is v10 or later.","message":"serverless-plugin-typescript v2.0.0 dropped support for Node.js v6 and v8. This plugin now requires Node.js v10 or later to function correctly.","severity":"breaking","affected_versions":">=2.0.0"},{"fix":"Adjust your build process to rely on the plugin's default output directory (`.build`) and root directory behavior, or ensure your tsconfig aligns with these fixed values.","message":"The `outDir` and `rootDir` options in your `tsconfig.json` cannot be overridden by this plugin, as it sets them internally for its build process. Attempts to set them differently in your tsconfig may be ignored.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Update your `serverless.yml` to ensure `- serverless-plugin-typescript` appears before `- serverless-offline` in the `plugins` section.","message":"When integrating with `serverless-offline`, `serverless-plugin-typescript` must be listed *before* `serverless-offline` in the `plugins` section of your `serverless.yml` for correct compilation and local simulation.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Add a `\"main\": \"handler.js\"` entry to your `package.json` and ensure the referenced TypeScript file (e.g., `handler.ts`) exists.","message":"For Google Cloud Functions, you must define a `main` field in your `package.json` (e.g., `'main': 'handler.js'`) pointing to the *compiled JavaScript file*. The plugin will then look for a corresponding `.ts` file (e.g., `handler.ts`) to compile.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Install TypeScript in your project: `npm install -D typescript` or `yarn add -D typescript`.","cause":"TypeScript is a peer dependency of the plugin and must be installed separately in your project.","error":"Cannot find module 'typescript' or its corresponding type declarations."},{"fix":"Update your `serverless.yml` to ensure `- serverless-plugin-typescript` appears before `- serverless-offline` in the `plugins` section.","cause":"The order of plugins in `serverless.yml` is incorrect, causing `serverless-offline` to run before TypeScript compilation.","error":"Serverless command 'offline' failed: Plugin 'serverless-offline' must be listed after 'serverless-plugin-typescript' in your serverless.yml."},{"fix":"Verify your Serverless Framework version. If it's v1.x, either upgrade Serverless Framework to v2/v3 (`npm install -g serverless`) or downgrade `serverless-plugin-typescript` to a v1.x version that supports Serverless v1.","cause":"This error often indicates an incompatibility between the plugin version and the Serverless Framework version. v2.x of this plugin requires Serverless v2 or v3.","error":"TypeError: Cannot read properties of undefined (reading 'hooks') (or similar errors during deployment/packaging)"}],"ecosystem":"npm"}