gitblit / plugin-typescript

TypeScript custom runtime + workflows integration for Architect

@architect/plugin-typescript

TypeScript support and workflow integration for Architect

Install

Into your existing Architect project:

npm i @architect/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
export async function handler (request: any, context: any): Promise<any> {
  return request
}

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:

• 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

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

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.

Footnotes

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