https://github.com/architect/plugin-typescript
TypeScript custom runtime + workflow integration for Architect
https://github.com/architect/plugin-typescript
architect aws-lambda typescript
Last synced: 9 months ago
JSON representation
TypeScript custom runtime + workflow integration for Architect
- Host: GitHub
- URL: https://github.com/architect/plugin-typescript
- Owner: architect
- Created: 2022-01-18T18:23:24.000Z (almost 4 years ago)
- Default Branch: main
- Last Pushed: 2024-03-26T21:21:52.000Z (almost 2 years ago)
- Last Synced: 2025-04-13T11:41:48.018Z (9 months ago)
- Topics: architect, aws-lambda, typescript
- Language: JavaScript
- Homepage: https://www.npmjs.com/package/@architect/plugin-typescript
- Size: 43 KB
- Stars: 17
- Watchers: 5
- Forks: 8
- Open Issues: 5
-
Metadata Files:
- Readme: readme.md
- Changelog: changelog.md
- Contributing: .github/contributing.md
- Code of conduct: .github/code_of_conduct.md
Awesome Lists containing this project
README
## [`@architect/plugin-typescript`](https://www.npmjs.com/package/@architect/plugin-typescript)
> TypeScript support and workflow integration for Architect
[](https://github.com/architect/plugin-typescript/actions?query=workflow%3A%22Node+CI%22)
## Install
Into your existing Architect project:
```sh
npm i @architect/plugin-typescript --save-dev
```
Add the following to your Architect project manifest (usually `app.arc`):
```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:
```arc
# 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:
```ts
// src/http/get-index/index.ts
import { Context, APIGatewayProxyResult, APIGatewayEvent } from 'aws-lambda'
export const handler = async (event: APIGatewayEvent, context: Context): Promise => {
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](#configuration).)
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`](https://esbuild.github.io/)[^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](https://esbuild.github.io/api/) 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](https://docs.aws.amazon.com/lambda/latest/dg/lambda-runtimes.html)
Example:
```arc
@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`](https://esbuild.github.io/), bundles to CommonJS to avoid issues surrounding [transpiling to ESM with second-order dynamic requires](https://github.com/evanw/esbuild/issues/1921). However, due to ongoing [issues surrounding top-level await in esbuild, TypeScript, V8, etc.](https://github.com/evanw/esbuild/issues/253), 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](https://esbuild.github.io/api/#tsconfig)