@architect/plugin-typescript

`@architect/plugin-typescript`

TypeScript support and workflow integration for Architect

Install

Into your existing Architect project:

npm i @architect/plugin-typescript --save-dev

Add the following to your Architect project manifest (usually app.arc):

@aws
runtime typescript # sets TS as the the default runtime for your entire project

@plugins
architect/plugin-typescript

Or, if you'd prefer to add a single TS Lambda to start, forego the above runtime typescript setting in your project manifest, and add the following to a single Lambda:

# src/http/get-index/config.arc
@aws
runtime typescript

Usage

Now, simply author and port Lambdas in the src tree with index.ts handlers. For example:

// src/http/get-index/index.ts
import { Context, APIGatewayProxyResult, APIGatewayEvent } from 'aws-lambda'

export const handler = async (event: APIGatewayEvent, context: Context): Promise<APIGatewayProxyResult> => {
  console.log(`Event:`, event)
  console.log(`Context:`, context)
  return { statusCode: 200, body: JSON.stringify({ message: 'Hello world!' }) }
}

The above function will be automatically transpiled by Architect to ./.build/http/get-index.js. (The destination build directory is configurable, see below.)

When working locally, Sandbox automatically detects changes to your TypeScript handlers and re-transpiles them for you.

Configuration

`tsconfig.json`

By default, Architect TypeScript will pass your tsconfig.json along to the transpiler,esbuild¹.

If you have a unique tsconfig.json file for a single Lambda (e.g. src/http/get-index/tsconfig.json), that will be given priority over your project-level TSConfig in the root of your project.

Project manifest settings

The following higher-level settings are also available in your Architect project manifest with the @typescript settings pragma:

build - customize the build directory; defaults to .build
- Note: make sure you add this directory to your .gitignore
sourcemaps - enable sourcemaps for Architect environments; defaults to testing + staging
- List of testing, staging, and/or production environment in which to add sourcemaps, or disable all sourcemaps with false
- We strongly advise you do not add sourcemaps to your production environment as it may have a meaningful impact on end-user performance and coldstart time
esbuild-config - add arbitrary esbuild configuration options
- Value is a relative path to a CJS file that exports an object of esbuild options; these options will be passed to the build
- Any options that conflict with this plugin's defaults will be ignored
base-runtime - set a different base Node.js version; defaults to nodejs20.x
- See the list of Lambda-supported Node runtimes

Example:

@typescript
# Build into `./dist`
build dist

# Disable sourcemaps in `staging`, but add them to `production`; you probably shouldn't actually do this though
sourcemaps testing production

# Add esbuild plugins
esbuild-config esbuild-config.js

# Set the Lambda base runtime to Node.js 18
base-runtime nodejs18.x

Caveats

Architect TypeScript, which uses esbuild, bundles to CommonJS to avoid issues surrounding transpiling to ESM with second-order dynamic requires. However, due to ongoing issues surrounding top-level await in esbuild, TypeScript, V8, etc., top-level await is not yet supported.

If you need top-level await, we suggest authoring in plain JavaScript for the time being.

Head here for more information about how esbuild makes use of TSConfig ↩

@architect/plugin-typescript