architect / plugin-typescript

TypeScript custom runtime + workflow integration for Architect

@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.

Footnotes

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

plugin-typescript's Issues

Handler is not recompiled on dependent file change

Describe the issue
The plugin works well for handlers. However, i'm having an issue when changing code in the shared folder, because the handler is not recompiled after the change. I have to manually trigger save in the handler file again to recompile the dependent code.

Steps to reproduce
Steps to reproduce the behavior:

1. Create a handler (i.e. get-index/index.ts)
2. Create a file in shared (i.e. shared/manager/UserManager.ts)
3. Import that file and use it in your handler
4. Make a change in the UserManager.ts file
5. Observe that the handler is not recompiled
6. Go back to the handler and manually save the file again. Notice that the code is now compiled correctly including the dependent code.

Expected behavior
The affected handlers are recompiled on dependent code changes.

No create.handlers method found for custom runtime plugin 'typescript' (architect/plugin-typescript)

Hi, I am getting this error when running arc init with new http endpoints.

Version ⌁ Architect 10.14.2
         cwd ⌁ /XXX

✓ Create Existing Architect project manifest found
init failed! No create.handlers method found for custom runtime plugin 'typescript' (architect/plugin-typescript)
ReferenceError: No create.handlers method found for custom runtime plugin 'typescript' (architect/plugin-typescript)
    at writeCode (/XXX/node_modules/@architect/create/src/write-functions/write-code.js:40:15)
    at writeFunctions (/XXX/node_modules/@architect/create/src/write-functions/index.js:18:13)
    at create (/XXX/node_modules/@architect/create/src/index.js:100:13)
    at process.processTicksAndRejections (node:internal/process/task_queues:95:5)
    at async main (/XXX/node_modules/@architect/architect/src/index.js:78:7)
    at async /XXX/node_modules/@architect/architect/src/index.js:94:5

Wrong handler recompiled when running in sandbox

When I have 2 http handlers with a common base path the first (shorter) handler is recompiled when there are changes made to the second.

Example:

Say I have the following http handlers:

• src/http/get-api-v1-users/index.ts
• src/http/get-api-v1-users-000id/index.ts

When I make a change to get-api-v1-users-000id, get-api-v1-users is recompiled instead. It looks like this line is matching the first handler because they share a common filename prefix.

Hopefully, this is helpful...