Serverless TypeScript Plugin

2.1.5 · active · verified Sun Apr 19

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.

Common errors

```
Cannot find module 'typescript' or its corresponding type declarations.
```
cause TypeScript is a peer dependency of the plugin and must be installed separately in your project.

fix Install TypeScript in your project: `npm install -D typescript` or `yarn add -D typescript`.
```
Serverless command 'offline' failed: Plugin 'serverless-offline' must be listed after 'serverless-plugin-typescript' in your serverless.yml.
```
cause The order of plugins in `serverless.yml` is incorrect, causing `serverless-offline` to run before TypeScript compilation.

fix Update your `serverless.yml` to ensure `- serverless-plugin-typescript` appears before `- serverless-offline` in the `plugins` section.
```
TypeError: Cannot read properties of undefined (reading 'hooks') (or similar errors during deployment/packaging)
```
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.

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.

Warnings

breaking 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.
Fix: Upgrade your Serverless Framework installation to v2.x or v3.x (`npm install -g serverless`).
breaking 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.
Fix: Ensure your Node.js environment is v10 or later.
gotcha 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.
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.
gotcha 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.
Fix: Update your `serverless.yml` to ensure `- serverless-plugin-typescript` appears before `- serverless-offline` in the `plugins` section.
gotcha 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.
Fix: Add a `"main": "handler.js"` entry to your `package.json` and ensure the referenced TypeScript file (e.g., `handler.ts`) exists.

Install

npm install serverless-plugin-typescript npm
yarn add serverless-plugin-typescript yarn
pnpm add serverless-plugin-typescript pnpm

Imports

serverless-plugin-typescript (YAML config)
```
plugins:
  - serverless-plugin-typescript
```
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.

Quickstart

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

/* serverless.yml */
service: my-typescript-service

frameworkVersion: "2 || 3"

provider:
  name: aws
  runtime: nodejs16.x # Or a newer supported Node.js version
  region: us-east-1

plugins:
  - serverless-plugin-typescript
  - serverless-offline # Example for common integration

functions:
  hello:
    handler: handler.hello
    events:
      - http:
          path: hello
          method: get

/* handler.ts */
import { APIGatewayProxyHandler } from 'aws-lambda';

export const hello: APIGatewayProxyHandler = async (event, context) => {
  return {
    statusCode: 200,
    body: JSON.stringify(
      {
        message: 'Go Serverless with TypeScript! Your function executed successfully!',
        input: event,
      },
      null,
      2
    ),
  };
};

/* tsconfig.json */
{
  "compilerOptions": {
    "preserveConstEnums": true,
    "strictNullChecks": true,
    "sourceMap": true,
    "allowJs": true,
    "target": "es5", // Plugin default, cannot be overridden via tsconfig.json for compilation target
    "outDir": ".build", // Plugin default, cannot be overridden
    "moduleResolution": "node",
    "lib": ["es2015"], // Plugin default
    "rootDir": "./", // Plugin default, cannot be overridden
    "esModuleInterop": true,
    "resolveJsonModule": true
  },
  "include": ["**/*"],
  "exclude": ["node_modules", ".build"]
}

view raw JSON →