Project Layout
What you will learn
Go does not force a folder layout on you, and that freedom makes beginners nervous. This lesson shows how a project grows in stages, so you always know the smallest layout that fits, and explains what the common folders cmd, internal, pkg, and api are for, and when to leave them out.
There is no official layout
The Go toolchain only requires a go.mod file and directories that contain packages. Everything else is convention. Large open-source projects have organised themselves in many different ways, and copying a big layout into a tiny project is a common beginner mistake. It adds folders, imports, and indirection before they solve any problem.
The rule to follow is simple: start flat, split when it hurts.
Stage 1: one file
For a script or a small tool, this is enough:
hello/
├── go.mod
└── main.go
Run it with go run .. There is nothing wrong with a project that stays like this.
Stage 2: several files, one package
When main.go grows past a few hundred lines, split it by topic but keep a single package:
tasker/
├── go.mod
├── main.go # starts the program
├── tasks.go # task type and operations
└── storage.go # loading and saving
All three files declare package main, so they share names with no imports. This is the cheapest way to get readable files.
Stage 3: your own packages
Create a new package when a group of code has a clear responsibility and a name that describes it:
tasker/
├── go.mod
├── main.go
└── task/
├── task.go
└── storage.go
main.go now imports example.com/tasker/task. A good signal that you need a package is when you can describe it in one short phrase, such as "task storage", and you want a boundary around it. Names should be short and lowercase: task, storage, auth. Avoid vague names like utils, common, or helpers, which turn into dumping grounds.
Stage 4: commands and internal code
When the project has more than one executable, or when most of its code should not be importable by others, use cmd and internal:
myapp/
├── go.mod
├── cmd/
│ ├── api/
│ │ └── main.go
│ └── worker/
│ └── main.go
└── internal/
├── app/
│ └── app.go
└── storage/
└── storage.go
Here is a small working version:
package main
import (
"fmt"
"myapp/internal/app"
)
func main() {
fmt.Println(app.Start())
}
package app
func Start() string {
return "app started"
}
module myapp
go 1.26
Run it from the module root:
go run ./cmd/api
app started
What each folder is for
cmd/api and cmd/worker. Each subfolder contains a small package main that wires things together and starts the program. Keep the real logic out of it, so it can be reused and tested elsewhere. Use cmd when you have more than one program, or when you want main to be a thin starter.Signs a layout is too big
- Folders that each contain a single file with a single function.
- Every package imports every other package.
- You spend more time deciding where code goes than writing it.
- A
utilsorcommonpackage keeps growing.
The fix is to merge folders back together. Package boundaries should reflect real responsibilities, not a desire to look organised.
Common mistakes
- Copying a template layout on day one. Start flat and let the structure appear when you need it.
- Splitting by technical kind (
models/,controllers/,helpers/) instead of by responsibility. Prefer packages named for what they do, likebillingorauth. - Using
pkgas a default. It carries no special meaning to Go. - Creating import cycles by splitting too aggressively. If two packages need each other, they probably belong together.
Practice
You are building three things: (a) a 40-line program that renames files, (b) a web API plus a separate background worker that share storage code, and (c) a small library other people will import. Choose a layout for each.
(a) Rename tool: go.mod and main.go. Forty lines do not justify any folders.
(b) API plus worker: two executables need two entry points, so use cmd:
shop/
├── go.mod
├── cmd/
│ ├── api/main.go
│ └── worker/main.go
└── internal/
└── storage/storage.go
Both commands import shop/internal/storage. The internal folder keeps the shared code private to the module.
(c) Library: put the public package at the module root, for example go.mod and slugify.go with package slugify, so users can import github.com/you/slugify directly. Add internal/ only for helpers you do not want to promise as public API.
Summary
Go has no mandated project layout, so start with one file, then several files in one package, then your own packages, and only then cmd and internal. Use cmd for multiple executables, internal for code that only your module should import, and treat pkg and api as optional conventions. If a layout makes you spend more time arranging than coding, it is too big.
Official reference: Organizing a Go module.
Ready to wrap up?
Mark this complete when you can explain the main idea and finish the practice task.