Minimal Go Starter Kit

#backend #go #frontend

Here is my go-to minimal setup.

gin-gonic/gin — HTTP router and web framework.
gin-contrib/cors — CORS middleware for cross-origin requests.
golang-jwt/jwt/v5 — JWT authentication and token handling.
joho/godotenv — Loads environment variables from .env files.
golang.org/x/crypto — Password hashing and cryptography utilities.
gorm.io/gorm — ORM for database operations.
gorm.io/driver/mysql — MySQL driver for GORM.

Other options:

Atlas — manages DB schema migrations.
sqlc — generates Go code from your SQL queries, no need to write DB code manually.

Folders

api/ : Contains the core HTTP server setup (server.go) and common API response formatting (response.go). This is where your routes are registered and the main server instance is created.
config/ : Handles application configuration. The config.go file here is responsible for tasks like connecting to your database and managing global settings.
handlers/ : Contains the HTTP request handlers (controllers) like auth.go, user.go, role.go, etc. These files receive incoming HTTP requests, process the business logic (often by interacting with models), and send back HTTP responses.
middleware/ : Contains functions that run before your main handlers. For example, auth.go and permission.go likely intercept requests to verify that a user is logged in and has the correct permissions before allowing them to access protected routes.
migrations/ : Contains raw SQL files (e.g., ...create_users.up.sql) used to create and modify your database schema over time. This keeps track of your database structure versions.
models/ : Defines the data structures (Go structs) that represent your database tables (like User, Role, Permission). These are used to map data between your Go code and your database.
seeders/ : Contains scripts to populate your database with initial or dummy data (like a default admin user or basic roles) which is very useful for setting up a fresh development environment.

Root Files

main.go : The entry point of your Go application. It bootstraps the app by loading environment variables, setting up logging, connecting to the database via the config package, and starting the HTTP server via the api package.
.env & **.env.example**
.air.toml : The configuration file for Air, a popular live-reloading tool for Go. It tells Air how to build and run your app automatically when you save changes.

And at managing the command to run/migrate/seed/etc, we can use tools like Taskfile or Makefile.

version: '3'

dotenv: ['backend/.env']

tasks:
  # ── Dev ──────────────────────────────────────────────────────────────────
  dev:
    desc: Start backend (Air) and frontend (Vite) concurrently
    cmds:
      - 'npx --prefix frontend concurrently --names "backend,frontend" --prefix-colors "cyan,magenta" "cd backend && \"{{.AIR_PATH}}\"" "pnpm --dir frontend run dev"'

  # ── Backend ──────────────────────────────────────────────────────────────
  backend:
    desc: Run backend with Air live reload
    dir: backend
    cmds:
      - '"{{.AIR_PATH}}"'

  # ── Frontend ─────────────────────────────────────────────────────────────
  frontend:
    desc: Run frontend Vite dev server
    dir: frontend
    cmds:
      - pnpm run dev

  # ── DB / Migrations ──────────────────────────────────────────────────────
  db:create:
    desc: Create the database if it doesn't exist
    dir: backend
    cmds:
      - '"{{.MYSQL_PATH}}" -u{{.DB_USER}} -p{{.DB_PASS}} -h{{.DB_HOST}} -P{{.DB_PORT}} -e "CREATE DATABASE IF NOT EXISTS {{.DB_NAME}}"'

  migrate:up:
    desc: Run all pending migrations
    dir: backend
    cmds:
      - task: db:create
      - '"{{.MIGRATE_PATH}}" -path migrations -database "mysql://{{.DB_USER}}:{{.DB_PASS}}@tcp({{.DB_HOST}}:{{.DB_PORT}})/{{.DB_NAME}}" up'

  migrate:create:
    desc: "Create a new migration - usage: task migrate:create NAME=create_posts"
    dir: backend
    cmds:
      - '"{{.MIGRATE_PATH}}" create -ext sql -dir migrations -seq {{.NAME}}'

  seed:
    dir: backend
    cmds:
      - go run ./seeders

  # ── Utilities ────────────────────────────────────────────────────────────
  tidy:
    desc: Run go mod tidy
    dir: backend
    cmds:
      - go mod tidy

  install:
    desc: First-time project setup (copy .env, tidy, migrate)
    cmds:
      - cp backend/.env.example backend/.env
      - task: tidy
      - task: migrate:up

  setup:
    desc: Full setup + start dev servers
    cmds:
      - task: install
      - task: dev