sls-ts-plugin

Used by sls-ts-template

Serverless plugin for zero-config Typescript support

Features

• Zero-config: Works out of the box without the need to install any other compiler or plugins
• Supports ES2020 syntax + features (export, import, async, await, Promise, ...)
• Supports sls package, sls deploy and sls deploy function
• Supports sls invoke local + --watch mode
• Integrates nicely with serverless-offline

Install

yarn add --dev @jeremigendron/sls-ts-plugin
# or
npm install -D @jeremigendron/sls-ts-plugin

Add the following plugin to your serverless.yml:

plugins:
  - '@jeremigendron/sls-ts-plugin'

Configure

See examples folder for examples.

tsconfig.json

The default tsconfig file used by the plugin looks like this:

{
  "compilerOptions": {
    "module": "commonjs",
    "target": "es5",
    "lib": ["ES2020"],
    "rootDir": "./",
    "allowJs": true,
    "checkJs": true,
    "strict": true,
    "noImplicitAny": true,
    "strictNullChecks": true,
    "strictFunctionTypes": true,
    "strictBindCallApply": true,
    "strictPropertyInitialization": true,
    "noImplicitThis": true,
    "alwaysStrict": true,
    "noUnusedLocals": true,
    "noUnusedParameters": true,
    "noImplicitReturns": true,
    "noFallthroughCasesInSwitch": true,
    "moduleResolution": "node",
    "esModuleInterop": true,
    "experimentalDecorators": true,
    "emitDecoratorMetadata": true,
    "forceConsistentCasingInFileNames": true,
    "preserveConstEnums": true,
    "sourceMap": true,
  }
}

If you have a tsconfig.json file in the root of your project, the plugin will attempt to use it for compilation if you don't specify another one to use. If you don't specify any and it can't find tsconfig.json in the root, it will use the default one above.

Note 1: The outDir and rootDir options cannot be overwritten.

Note 2: You can specify a tsconfig to use for compilation with the cli flag tsconfigFilePath=tsconfig.example.json or the custom option:

custom:
  typescript:
    tsconfigFilePath: tsconfig.example.json

Note 3: You can signal not to copy the root node_modules on every build (reduces build time when you have a monorepo setup) with the cli flag noCopyDeps=true or the custom option:

custom:
  typescript:
    noCopyDeps: true

Including extra files

All files from package/include will be included in the final build file. See Exclude/Include

Files from function/fnName/package/include will also be included in the build folder.

If you have a monorepo setup and wish to include your function's node_modules in the final build, you will need to specifically include a matching glob in the function's package's include property.

Usage

Automatic compilation

The normal Serverless deploy procedure will automatically compile with Typescript:

• Create the Serverless project with serverless create -t aws-nodejs
• Install and configure as shown above
• Deploy with serverless deploy

Usage with serverless-offline

The plugin integrates very well with serverless-offline to simulate AWS Lambda and AWS API Gateway locally.

Add the plugins to your serverless.yml file and make sure that '@jeremigendron/sls-ts-plugin' precedes serverless-offline as the order is important:

  plugins:
    ...
    - '@jeremigendron/sls-ts-plugin'
    ...
    - serverless-offline
    ...

Run serverless offline or serverless offline start to start the Lambda/API simulation.

In comparison to serverless offline, the start command will fire an init and a end lifecycle hook which is needed for serverless-offline and e.g. serverless-dynamodb-local to switch off resources (see below)

serverless-dynamodb-local

Configure your service the same as mentioned above, but additionally add the serverless-dynamodb-local plugin as follows:

  plugins:
    - '@jeremigendron/sls-ts-plugin'
    - serverless-dynamodb-local
    - serverless-offline

Run serverless offline start.

Other useful options

You can reduce the clutter generated by serverless-offline with --dontPrintOutput and disable timeouts with --noTimeout.

Run a function locally

To run your compiled functions locally you can:

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

Options are:

• --function or -f (required) is the name of the function to run
• --watch - recompile and run a function locally on source changes
• --path or -p (optional) path to JSON or YAML file holding input data
• --data or -d (optional) input data

Google Cloud Functions

When using with Google Cloud Functions via the serverless-google-cloudfunctions plugin, you simply have to provide a main field in your package.json:

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

And this plugin will automatically compile your typescript correctly. Note that the field must refer to the compiled file name, namely, ending with a .js extension.

If a main field was not found, then this plugin will use index.js. Before compilation begins, it will check to see that the file indicated exists with a .ts extension before actually trying to compile it.