serverless-plugin-typescript: TypeScript for Serverless without a compiler pipeline

The plugin ships its own tsconfig and you cannot move the output

The claim in the feature list is zero config: it works out of the box without needing any other compiler or plugins. Part of that promise is a default `tsconfig.json` the plugin applies when you do not supply your own.

{
  "compilerOptions": {
    "preserveConstEnums": true,
    "strictNullChecks": true,
    "sourceMap": true,
    "allowJs": true,
    "target": "es5",
    "outDir": ".build",
    "moduleResolution": "node",
    "lib": ["es2015"],
    "rootDir": "./"
  }
}

Two details in that file decide what your code can do. The target is `es5` and the library set is `es2015`, so the output runs on old Node versions but the type definitions available to you are the 2015 ones. The plugin advertises support for ES2015 syntax and features such as `export`, `import`, `async`, `await` and `Promise`, and this is the compiler configuration that delivers it.

The two notes under the sample are the sharp edge. The `outDir` and `rootDir` options cannot be overwritten, so the compiled output always lands in `.build` and the root stays the project root. And the `tsconfig.json` in the repository itself is a different file from the default described here, which is a trap for anyone who reads the wrong one.

Note also that `sourceMap` is on by default, which is what makes the source map instructions further down the documentation work.

Installing is two packages and one plugin entry

The plugin needs the TypeScript compiler alongside it, so the install command names both.

yarn add --dev serverless-plugin-typescript typescript
# or
npm install -D serverless-plugin-typescript typescript

Then the plugin goes into the `plugins` list of your `serverless.yml`.

plugins:
  - serverless-plugin-typescript

That is the whole setup. The plugin hooks the packaging lifecycle, so `sls package`, `sls deploy` and `sls deploy function` all compile on the way through, and `sls invoke local` works as well.

The project was originally developed by Prisma Labs and is now maintained in scope of Serverless, Inc, which is worth knowing because it means the plugin follows the framework's own release cadence rather than a company's product roadmap. The peer dependencies are declared as `serverless` `2 || 3` and `typescript` `>=2.2.2`, which is a wide range and a hint that the plugin is tested against a range of framework and compiler versions rather than pinned to one.

Plugin order decides who compiles first

When you combine the plugin with `serverless-offline`, the order of the entries in `plugins` is not a style choice. The documentation says to make sure that `serverless-plugin-typescript` precedes `serverless-offline` as the order is important.

  plugins:
    ...
    - serverless-plugin-typescript
    ...
    - serverless-offline
    ...

The reason is obvious once stated: the offline simulator needs compiled JavaScript to serve, so the compilation hook has to run first. Get the order wrong and the local server starts with no JavaScript to load, which is a confusing failure if you have not read this part of the documentation.

The same ordering logic extends to a third plugin. For `serverless-dynamodb-local` the list becomes the TypeScript plugin first, then the database plugin, then the offline plugin.

  plugins:
    - serverless-plugin-typescript
    - serverless-dynamodb-local
    - serverless-offline

There is a second difference between the two offline commands. `serverless offline` starts the simulation, while `serverless offline start` additionally fires an `init` and an `end` lifecycle hook, which the documentation says is needed for plugins such as `serverless-offline` and `serverless-dynamodb-local` to switch off resources afterwards.

Extra files travel through package/include

Compiled TypeScript is not the whole artifact. Whatever else your function needs has to be copied into the deployment package, and the plugin handles that through the framework's own include mechanism.

The rule is simple: all files from `package/include` are included in the final build file, and the documentation links to the Serverless packaging guide for the exclude and include options. So the convention is that anything you want at runtime that is not emitted by the compiler, such as templates, JSON fixtures or a data file, goes under `package/include` in your service directory.

Two related mechanisms exist for anything the compiler should not touch at all. The `exclude` option in the same packaging configuration keeps files out of the package, and the plugin's own `tsconfig` handles the compile side with `allowJs` enabled, so plain JavaScript files in your source tree are compiled or copied rather than rejected.

If you need a different configuration file, for example one that differs from the default for a specific build, there is a dedicated setting. In your `serverless.yaml` you can point the plugin at another file.

custom:
  serverlessPluginTypescript:
    tsConfigFileLocation: './tsconfig.build.json'

That covers the case where the repository root tsconfig is tuned for your editor and type checking, while the deployed build wants different compiler options.

Google Cloud Functions need a main field pointing at compiled JavaScript

Deploying to Google Cloud Functions through the `serverless-google-cloudfunctions` plugin needs one extra step, and it is easy to get wrong because the field names the compiled file, not the source.

{
  // ...
  "main": "handler.js",
  // ..
}

The documentation is explicit that the field must refer to the compiled file name, meaning it ends with a `.js` extension, and that the plugin then compiles the TypeScript correctly on its own. If no `main` field is found, the plugin falls back to `index.js`.

Before compilation starts, the plugin checks that the indicated file exists with a `.ts` extension, which is what lets a `handler.js` entry in `package.json` map to `handler.ts` in the source tree. The example project in the repository shows the same pattern with `example/handler.ts`, `example/package.json` and `example/serverless.yml`.

This is a small mechanism, but it is the kind of detail that separates a plugin that works on the first deploy from one that fails with a missing handler error, and it is only written down in this one paragraph of the documentation.

Local invocation recompiles on change

Running a function on your own machine goes through `sls invoke local`, which the documentation describes as working with a `--watch` mode as well.

$ serverless invoke local --function <function-name>

Four options are documented. `--function` or `-f` is required and names the function to run. `--watch` recompiles and reruns the function on source changes. `--path` or `-p` points at a JSON or YAML file holding input data, and `--data` or `-d` passes input data inline.

That combination is the plugin's most useful daily feature, because a TypeScript error or a changed handler shows up in the terminal within seconds instead of after a package and deploy cycle. The documentation also recommends `serverless-offline` for simulating AWS Lambda and AWS API Gateway locally, and lists two options for it: `--dontPrintOutput` to reduce the clutter it generates and `--noTimeout` to disable timeouts.

For readable stack traces, the documentation points at the separate `source-map-support` package.

yarn add --dev source-map-support

Since the default tsconfig already sets `sourceMap` to true, the missing half is the runtime registration inside your function.

// inside of your function
import 'source-map-support/register'

If you also bundle with webpack, the documentation notes that you should add `devtool: 'source-map'` to your webpack configuration so the mapping survives the bundling step.

Releases stopped in 2023 while commits continued into 2026

The published versions tell one story and the commit history tells another. The most recent release is v2.1.5 from 2023-06-05, preceded by v2.1.2 in April 2022 and v2.1.1 in January 2022. The repository is not archived and the last push was on 2026-05-12.

So if you install from npm you get the 2.1.5 build, while the master branch has moved on since. The package version in `package.json` is still 2.1.5, which is a common pattern for projects that keep version bumps tied to releases.

The dependency set is dated in the same way. The compiler is `typescript` `^4.9.5` in development, the test runner is `jest` 24 with `ts-jest` 24, the linter is `tslint` rather than ESLint, and `rimraf` 2 is used in the build script. The runtime dependencies are small: `fs-extra`, `globby` and `lodash`. The build itself is `rimraf dist && tsc`, and releases are cut with `standard-version`, configured to skip commit and tag creation.

The licence is MIT, which covers commercial use and modification, including in closed source services, provided the notice is retained. That is a reading of the licence terms rather than legal advice.

The practical read is that this is a stable, low maintenance plugin that still works with the Serverless Framework versions it declares, and that a team worried about the framework moving forward should check the `serverless` peer range of `2 || 3` against the version they run.

Editorial conclusion

Adopt serverless-plugin-typescript when your Serverless service is plain TypeScript that needs compiling and you would rather not maintain a bundler configuration, and skip it when you need bundling, tree shaking or a modern runtime target. Verify first that your functions only use syntax the ES5 target and the es2015 library set support, since the plugin's default tsconfig cannot have its outDir or rootDir changed.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. README
4. Releases
5. serverless/serverless-plugin-typescript on GitHub