SST OpenAPI Boilerplate

A starter project combining SST v3 (sst.dev) with OpenAPI to define, develop, and deploy serverless APIs on AWS, plus a generated client for frontend integration.

---

Table of Contents

1. Features

2. Architecture & Folder Structure

3. Prerequisites

4. Getting Started

   • Install dependencies
   • Local Development

5. Commands Overview

   • API (Functions) Commands
   • OpenAPI Spec (Core) Commands
   • Client (Frontend) Commands
   • Root-level Scripts

6. Deployment

7. Contributing

---

Features

• SST v3 infrastructure-as-code for AWS Lambda + API Gateway
• OpenAPI-based request validation, routing, and documentation
• Built-in Swagger UI for interactive API exploration
• Easy client generation for frontend consumption
• Environment-based configuration and local emulation
• Zero-downtime deployments via SST

---

Architecture & Folder Structure

root
├─ sst.config.ts           # SST v3 entrypoint (IAC)
├─ package.json            # Root scripts & workspace configuration
├─ pnpm-workspace.yaml     # Monorepo workspace setup
├─ packages
│  ├─ core
│  │  ├─ openapi.yml       # OpenAPI spec definitions
│  │  ├─ src
│  │  └─ client            # Generated/hand-written frontend client
│  └─ functions
│     ├─ src               # Lambda functions & business logic
│     └─ tests             # Unit/integration tests
└─ README.md               # This file

• sst.config.ts defines all stacks, resources, and live development configuration.

• packages/core holds your OpenAPI specification and related code:

  • openapi.yml — your API contract
  • server-side controllers/handlers wired via openapi-backend
  • frontend client package for consuming your API

• packages/functions contains AWS Lambda functions that implement the endpoints.

---

Prerequisites

• Node.js ≥ 18.x
• pnpm ≥ 7.x
• AWS credentials configured in your environment (e.g. via aws configure)
• SST CLI: pnpm add -g sst

---

Getting Started

Install dependencies

# From repo root
pm install

If you’re using pnpm workspaces:

pnpm install

Local Development

Live Mode (API + Functions)

# Starts SST live (hot-reload infrastructure + Lambdas)
pm run start:dev
# or
pnpm start:dev

Environment-specific Local Emulation

pnpm start:dev
pnpm start:staging
pnpm start:production

Swagger UI

# Starts the Swagger UI server against your OpenAPI spec
pnpm dev
# or from root (pnpm start:swagger)

---

Commands Overview

API (Functions) Commands

Run inside packages/functions:

Script	Description
pnpm run dev	Start functions locally with SST live mode
pnpm run test	Run unit/integration tests
pnpm run build	Compile/Bundle Lambda functions

---

OpenAPI Spec (Core) Commands

Run inside packages/core:

Script	Description
pnpm run openapi	Export raw JSON from openapi.yml
pnpm run typegen	Generate TypeScript types from your OpenAPI definitions
pnpm run dev	Launch Swagger UI (3001) for your spec
pnpm run build	Run openapi + typegen in sequence

---

Client (Frontend) Commands

Run inside packages/core/client:

npm run build          # Bundle the client library
npm version [major|minor|patch]  # Bump the client version
npm publish           # Publish to npm registry

---

Root-level Scripts

Script	Description
pnpm build:types	Build types for all packages (runs core:build)
pnpm run dev:swagger	Start Swagger UI from root
pnpm run build	Recursively build all workspaces (core, functions, client)
pnpm run start:dev	SST live for entire monorepo
pnpm run start:<env>	SST emulate specific environment
pnpm run deploy:<env>	Deploy stacks to AWS for given environment (e.g. staging/prod)

---

Deployment

To deploy your infrastructure and Lambdas:

pnpm deploy:dev
pnpm deploy:staging
pnpm deploy:production

---

Contributing

1. Fork the repository.
2. Create a feature branch (git checkout -b feature/awesome).
3. Make your changes & add tests.
4. Commit & push: git push origin feature/awesome.
5. Open a Pull Request.

Please follow the existing code style and include JSDoc for new utilities.

---