Go Full Stack Template

A GitHub template for small, production-ready full-stack applications in Amp orbs and exe.dev. It produces one portable Go binary containing the React app, API, migrations, and SQLite driver—without a project-generation CLI.

• Go, chi, slog, modernc SQLite, goose migrations, and sqlc
• OpenAPI-first generated Go server types and TypeScript client types
• React, TypeScript, Vite, TanStack Router and Query, Tailwind CSS, and shadcn/ui
• Server-sent events that invalidate client queries for real-time updates
• Go integration tests, Vitest component tests, and Playwright end-to-end tests
• Supervised Amp development services and an exe.dev systemd deployment

There is intentionally no application authentication. The production recipe exposes the app only to your Tailscale network. Add app-level authorization if users within that tailnet should not all have the same access.

1. Use this repository as a GitHub template.
2. Open the new repository in an Amp orb.
3. Let .agents/setup run.

Setup derives the application name and Go module from the downstream GitHub origin, updates the template files, and deliberately leaves those changes uncommitted for review. It also installs pinned Go, Node.js, pnpm, and just versions plus project dependencies. Running setup again is safe.

For local development outside Amp, install Go 1.27+, Node 24+, pnpm 11+, and just, then run:

just setup
just dev

In Amp, .amp/services.yaml runs the API and Vite as supervised services. Use the Vite portal printed by amp orb services ensure; Vite proxies /api and the SSE stream to Go with HMR enabled.

The included Notes CRUD slice is executable documentation for the complete path from SQLite/sqlc through OpenAPI and Go to React Query and SSE. Keep it as a starting point, or remove it before building your app:

just remove-example
just check

The removal is intentionally visible and uncommitted. It replaces the example with a minimal health-backed shell while preserving SQLite, generated contracts, shadcn/ui, and real-time infrastructure.

After changing an endpoint or database query:

1. Edit api/openapi.yaml and/or db/migrations and db/queries.
2. Run just generate.
3. Implement against the generated Go interface and TypeScript types.
4. Run just check; run just e2e for affected user flows.

Generated files are committed so editors and agents work before generation. Do not edit internal/httpapi/api.gen.go, sqlc outputs in internal/store, or web/src/api/schema.d.ts manually.

Useful commands:

just setup             install dependencies
just dev               run API and Vite together
just generate          regenerate OpenAPI and sqlc code
just test              run Go and React tests
just e2e               run Playwright against the full stack
just check             format, test, typecheck, and build
just build             produce bin/app
just backup PATH       create a consistent SQLite backup
just restore PATH      restore a backup while the server is stopped
just deploy-exe VM     deploy to an existing exe.dev VM

Create a default Ubuntu/exeuntu VM manually, ensure you can connect with ssh VM.exe.xyz, and enroll it in your tailnet with a reusable or ephemeral auth key on the first deployment:

TS_AUTHKEY='tskey-auth-…' just deploy-exe VM

Later deployments normally need only just deploy-exe VM. The deployment:

• runs the full release check and builds the single binary;
• keeps the exe.dev proxy private and away from the application's port;
• installs a hardened systemd service on 127.0.0.1:28080;
• backs up SQLite before migrations and retains the newest 10 backups;
• atomically replaces the binary and restores the previous one if health fails;
• configures Tailscale Serve HTTPS, not Funnel, for tailnet-only access.

Deployment changes are manual by design—there is no GitHub Actions workflow. See deploy/README.md for operations, rollback details, and optional Litestream replication.

MIT