go-project-layout

Go Project Layout

Standard project structure and setup patterns for Go.

Directory Structure

Small projects (libraries, CLIs) should stay flat. Only add structure when the project warrants it. Do not create directories speculatively.

Application Layout

myapp/
├── cmd/
│   └── myapp/
│       └── main.go          # entry point, minimal logic
├── internal/
│   ├── server/
│   │   └── server.go        # HTTP server setup
│   ├── handler/
│   │   └── user.go          # HTTP handlers
│   ├── service/
│   │   └── user.go          # business logic
│   └── store/
│       └── postgres.go       # data access
├── go.mod
├── go.sum
├── Makefile
├── Dockerfile
├── .golangci.yml
└── README.md

Library Layout

mylib/
├── mylib.go                  # primary package API
├── mylib_test.go
├── internal/
│   └── parse/                # unexported helpers
│       └── parse.go
├── go.mod
└── README.md

Key Directories

cmd/

Each subdirectory is an executable. Keep main.go minimal: parse flags, build dependencies, call run().

// cmd/myapp/main.go
package main

import (
    "context"
    "fmt"
    "os"

    "myapp/internal/server"
)

func main() {
    if err := run(context.Background()); err != nil {
        fmt.Fprintln(os.Stderr, err)
        os.Exit(1)
    }
}

func run(ctx context.Context) error {
    srv, err := server.New()
    if err != nil {
        return fmt.Errorf("create server: %w", err)
    }
    return srv.Start(ctx)
}

internal/

Packages under internal/ cannot be imported by other modules. Use this for code that is not part of your public API. The Go toolchain enforces this.

When NOT to use certain directories

• pkg/: Avoid. If code is meant to be imported, put it at the module root or in a named package. pkg/ adds a directory with no meaning.
• src/: Not a Go convention. Do not use.
• models/ / types/ / utils/: These become dumping grounds. Name packages by what they do, not what they contain.