Monorepo Tools

Context

I kept rebuilding the same skeleton for every project: Go API, worker, TypeScript frontend, shared contracts, Docker Compose, migrations. The structure was fine, I'd already refined it on real projects. The problem was that I copied it by hand each time, so the copies drifted. A fix I made in one project never made it back to the others. At some point I got tired of that and pulled the whole thing into a template. Best afternoon I've spent on boilerplate.

What I built

A Go + TypeScript monorepo template with a small generator script around it.

• create.sh <destination> <display-name> <go-module-path> writes out a fresh monorepo with no git history or build artifacts. It's a new project, not a fork of an old one.
• All task running goes through Moon, so Go and TypeScript share one task graph. Bun workspaces handle the TypeScript packages. One gotcha: run bun install before anything else, Moon needs the TypeScript compiler it installs for web and shared-package tasks.
• The Go side has an actual API (apps/api, with /healthz and /api/v1/health) and a worker entrypoint (apps/worker). Both compile and run on first boot.
• The TypeScript side (apps/web, packages/ui, packages/contracts, packages/config) starts as placeholders. The wiring between them is the point, not the code inside.
• infra/ brings Docker Compose, an env example, Postgres and Redis, migrations, and sqlc config. The local environment comes up before you write the first feature.

Lessons

The README tells you to document your actual tech choices in the generated project's AGENTS.md, otherwise, in its words, "the agents will be halucination". That's the part everyone skips and regrets later. The skeleton itself is mechanical. The decisions you write down in ADRs and AGENTS.md are what actually make the next project cheaper than the last one.