@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[^1].

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.

[^1]: Head here for more information about how esbuild makes use of TSConfig