npm package: @jeremigendron/sls-ts-plugin
Description: Used by [sls-ts-template](https://github.com/jeremigendron/sls-ts-template)
Author: Jeremi Gendron
Latest version: 1.2.3

# sls-ts-plugin

Used by [sls-ts-template](https://github.com/jeremigendron/sls-ts-template)

Serverless plugin for zero-config Typescript support

[![sls][sls-image]][sls-url]
[![npm][npm-image]][npm-url]
[![build][build-image]][build-url]

[sls-image]: http://public.serverless.com/badges/v3.svg
[sls-url]: http://www.serverless.com
[npm-image]: https://badge.fury.io/js/%40jeremigendron%2Fsls-ts-plugin.svg
[npm-url]: https://www.npmjs.com/package/@jeremigendron/sls-ts-plugin
[build-image]: https://img.shields.io/github/workflow/status/jeremigendron/sls-ts-plugin/CI
[build-url]: https://github.com/jeremigendron/sls-ts-plugin/actions?query=workflow%3ACI

## 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`](https://github.com/dherault/serverless-offline)

## Install

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

Add the following plugin to your `serverless.yml`:

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

## Configure

See [examples folder](examples) for examples.

### `tsconfig.json`

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

```json
{
  "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:
> ```yaml
> 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:
> ```yaml
> custom:
>   typescript:
>     noCopyDeps: true
> ```

### Including extra files

All files from `package/include` will be included in the final build file. See [Exclude/Include](https://serverless.com/framework/docs/providers/aws/guide/packaging#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](https://github.com/dherault/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:
```yaml
  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:
```yaml
  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:

```bash
$ 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](https://github.com/serverless/serverless-google-cloudfunctions) plugin, you simply have to provide a `main` field in your `package.json`:

```js
{
  // ...
  "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.