Mantle

Appearance

Getting Started ​

Zero to deployed API in 5 minutes.

Prerequisites ​

  • Node.js 24+, pnpm 9+
  • AWS credentials configured
  • Docker (for container Lambdas only)

1. Set up the project ​

bash
mkdir my-api && cd my-api
pnpm init
pnpm add -D @j0nathan-ll0yd/cli
pnpm add @j0nathan-ll0yd/core @j0nathan-ll0yd/validation

Add a mantle.config.ts at the project root -- see Configuration:

typescript
import { defineConfig } from '@j0nathan-ll0yd/core'

export default defineConfig({
  name: 'my-api',
  database: { provider: 'aurora-dsql' },
  allowedStages: ['staging'],
})

The create-mantle-app scaffolder is not published. Its templates live at the repo root (templates/) and resolve relative to the package's dist/, so they fall outside the npm tarball; an installed copy produces an empty project. It runs from a checkout of the Mantle repo only.

2. Write a Handler ​

typescript
// src/lambdas/api/items/index.get.ts  →  GET /items
import { buildValidatedResponse } from '@j0nathan-ll0yd/core'
import { defineApiHandler, z } from '@j0nathan-ll0yd/validation'

const ResponseSchema = z.object({
  items: z.array(z.object({ id: z.string(), name: z.string() })),
})

const api = defineApiHandler({ auth: 'bearer' })
export const handler = api(async ({ context }) => {
  return buildValidatedResponse(context, 200, { items: [] }, ResponseSchema)
})

File-system routing: src/lambdas/api/<path>/<name>.<method>.ts maps to <method> /<path>/<name>.

3. Develop ​

bash
mantle dev              # local server with hot reload
pnpm test               # run tests
mantle check            # lint + convention rules

4. Build & Deploy ​

bash
mantle build                        # bundle all Lambdas
mantle deploy --stage staging       # push to AWS

mantle deploy runs OpenTofu under the hood — it provisions Lambda functions, API Gateway routes, and all supporting infrastructure from your mantle.config.ts.

Project Layout ​

my-api/
  src/
    lambdas/
      api/           # file-system routed API handlers
      eventbridge/   # EventBridge-triggered handlers
      scheduled/     # CloudWatch scheduled handlers
      standalone/    # direct-invocation handlers
    entities/        # Drizzle schema definitions
    migrations/      # database migrations
  mantle.config.ts

Next Steps ​

  • Handlers — defineApiHandler, defineEventBridgeHandler, defineScheduledHandler
  • Database — Aurora DSQL, Aurora Serverless v2, Neon
  • Deployment — build options, deploy stages, rollback
  • Infrastructure — OpenTofu modules reference