Single Architecture: One Binary

Overview

The single architecture is the most different from the other Grit modes. Instead of a Turborepo monorepo with separate apps, you get a flat project where a single Go binary serves both the REST API and the compiled React frontend using go:embed. Think of it like Laravel or an embedded Next.js app -- one deployment unit that handles everything.

There is no Turborepo, no pnpm-workspace.yaml, no turbo.json. The Go module path is just myapp (not myapp/apps/api). Schemas and types live directly in frontend/src/ -- there is no pnpm workspace, so no shared package.

grit new myapp --single --vite

Key Characteristics

Full Folder Structure

The entire project is flat. Go code lives in internal/, React code lives in frontend/, and main.go sits at the root.

Directory Breakdown

package main

import (
    "embed"
    "io/fs"
    "net/http"

    "myapp/internal/config"
    "myapp/internal/database"
    "myapp/internal/routes"
)

//go:embed frontend/dist/*
var frontendFS embed.FS

func main() {
    cfg := config.Load()
    db := database.Connect(cfg)

    // Serve API routes
    r := routes.Setup(db, cfg)

    // Serve embedded frontend
    dist, _ := fs.Sub(frontendFS, "frontend/dist")
    r.NoRoute(gin.WrapH(http.FileServer(http.FS(dist))))

    r.Run(":" + cfg.Port)
}

{
  "architecture": "single",
  "frontend": "tanstack",
  "go_module": "myapp"
}

Data Flow

The data flow differs between development and production. In development, you run two processes: Go on port 8080 and Vite on port 5173. Vite proxies API requests to Go. In production, there is only one process: the Go binary serves everything.

Production

Browser → Go binary (:8080)
               ├── /api/*        → Gin router → handlers → services → database
               └── everything else → serves frontend/dist/ (HTML, JS, CSS)

Development

Browser → Vite dev server (:5173)
               ├── /api/*  → proxied to Go (:8080) → handlers → services → database
               └── other   → Vite HMR (instant refresh)

The Vite proxy is configured in vite.config.ts to forward any request starting with /api to the Go server running on port 8080.

Development Workflow

One command runs the whole single app — the Go API (with hot reload) and the Vite frontend together. Press Ctrl+C to stop both.

grit start

Need just the Go API? Use grit start server. The generated Makefile also exposes the same workflow if you prefer make:

grit start server   # API only
make dev            # equivalent: runs Go + Vite concurrently

import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react'
import { TanStackRouterVite } from '@tanstack/router-plugin/vite'

export default defineConfig({
  plugins: [TanStackRouterVite(), react()],
  server: {
    port: 5173,
    proxy: {
      '/api': {
        target: 'http://localhost:8080',
        changeOrigin: true,
      },
    },
  },
})

Production Build

Building for production is a two-step process: build the frontend, then build the Go binary. The Go compiler embeds the compiled frontend assets into the binary at compile time.

# Step 1: Build the frontend
cd frontend && pnpm build
# This creates frontend/dist/ with optimized HTML, JS, and CSS

# Step 2: Build the Go binary
cd .. && go build -o myapp main.go
# The binary now contains the embedded frontend

# Step 3: Deploy
scp myapp server:/opt/myapp/
scp .env server:/opt/myapp/
# That's it. One binary + one .env file.

No Node.js runtime needed on the production server. No npm install, no pnpm, no build tools. Just the binary and your environment variables.

Code Generation

When you run grit generate resource in a single-architecture project, the CLI creates files in different locations compared to the monorepo architectures.

With no packages/shared/ to publish to, the generated hook declares its own Post interface inline rather than importing one -- a single-binary app has exactly one consumer, so there is nothing to keep in sync.

Deployment

Deploying a single-architecture app is as simple as it gets. You only need to transfer two files to your server: the compiled binary and your .env file.

Docker

FROM node:20-alpine AS frontend
WORKDIR /app/frontend
COPY frontend/package.json frontend/pnpm-lock.yaml ./
RUN corepack enable && pnpm install --frozen-lockfile
COPY frontend/ ./
RUN pnpm build

FROM golang:1.21-alpine AS backend
WORKDIR /app
COPY go.mod go.sum ./
RUN go mod download
COPY . .
COPY --from=frontend /app/frontend/dist ./frontend/dist
RUN CGO_ENABLED=0 go build -o server main.go

FROM alpine:3.19
WORKDIR /app
COPY --from=backend /app/server .
EXPOSE 8080
CMD ["./server"]

Direct Deploy (no Docker)

# Build locally for your server's OS/arch
GOOS=linux GOARCH=amd64 go build -o myapp main.go

# Transfer and run
scp myapp .env yourserver:/opt/myapp/
ssh yourserver 'cd /opt/myapp && ./myapp'

When to Choose Single

Example Project