Fastify Turbo Monorepo Starter

This is a starter project for building an API server using Typescript, Fastify v5 and Kysely with Postgres.

Features

Fastify v5 with Typescript.
It is setup as a monorepo using turbo and pnpm.
Outputs OpenAPI schema for the API and has a web UI for viewing it.
A sample REST test is included using Vitest.
Sample database migrations / repositories are included using Kysely.
An client SDK package is included to generate typescript client code from the API schema.
An error handler package is included to handle errors and return a consistent response.
Code generators using turbo gen to create new API endpoints and database tables.
Publish packages to npm and generate changelogs and releases using changesets.

Libraries and tools used

typescript
pnpm for package management
changesets for version and changelogs
commitlint for commit message linting
turbo for monorepo management
fastify for the API server framework
hash-runner for caching builds
kysely for the database query builder
postgres + pgAdmin for the database
testcontainers for testing with a sandboxed postgres instance
vitest for endpoint testing
loglayer for formatted logging
biome for linting and formatting
syncpack for keeping package versions in sync
Hey API for generating the backend SDK using the generated OpenAPI schema from the backend

Setup

Install docker
Install pnpm
pnpm install turbo --global
pnpm install
Copy apps/backend/.env.example to apps/backend/.env

Start local postgres server:

docker compose up -d

Perform database migrations:

pnpm db:migrate:lastest

In Github settings (to publish packages and changelogs):

Edit .changeset/config.json to your repository
Code and Automation > Actions > Workflow permissions
- Read and write permissions
- Allow Github Actions to create and approve pull requests
Secrets and variables > Actions
- Repository Secrets > Actions > create NPM_TOKEN > your npm publish token

Development

turbo watch dev

API server: http://localhost:3080
OpenAPI docs: http://localhost:3080/docs
PGAdmin: http://localhost:5050

Testing

Make sure docker is running as it uses testcontainers to spin up a temporary postgres database.

turbo test

Build

turbo build

Generate scaffolding

Generators for the following:

New API endpoints + tests
Database tables and repositories

turbo gen

Database migrations

Create a migration: pnpm db:create
Run migrations: pnpm db:latest
Rollback migrations: pnpm db:undo

Update all dependencies

pnpm syncpack:update

Development workflow / Add a new CHANGELOG.md entry + package versioning

Create a branch and make changes.
Create a new changeset entry: pnpm changeset
Commit your changes and create a pull request.
Merge the pull request
A new PR will be created with the changeset entry/ies.
When the PR is merged, the package versions will be bumped and published and the changelog updated.

note: To publish a package, private: false must be set in the package.json

Troubleshooting

turbo watch dev failing

• Packages in scope: @internal/backend, @internal/backend-client, @internal/backend-errors, @internal/tsconfig
• Running dev in 4 packages
• Remote caching disabled
  × failed to connect to daemon
  ╰─▶ server is unavailable: channel closed

Try:

turbo daemon clean

Then try running turbo watch dev again.

If you get:

• Packages in scope: @internal/backend, @internal/backend-client, @internal/backend-errors, @internal/tsconfig
• Running dev in 4 packages
• Remote caching disabled
  × discovery failed: bad grpc status code: The operation was cancelled

Wait a few minutes and try again.