When to Use the `/examples` Directory in Go Projects: A Complete Guide

The /examples directory is a conventional location for runnable, self-contained programs that demonstrate how to use your Go library or application, typically reserved for public libraries, complex applications, educational material, and integration testing.

The golang-standards/project-layout repository defines the de facto standard for organizing production-grade Go codebases. Understanding when to use the /examples directory in Go projects helps maintain clean repository boundaries while providing essential, executable documentation for consumers of your code.

What Is the /examples Directory?

According to the project layout standard, this directory holds runnable snippets illustrating how to use the code—whether it is an application, library, or utilities. The repository's root README.md lists /examples among the top-level directories and links to its dedicated README for implementation details【/cache/repos/github.com/golang-standards/project-layout/master/README.md†L165-L169】.

The examples/README.md clarifies that this folder contains "Examples for your applications and/or public libraries" and provides external references for guidance【/cache/repos/github.com/golang-standards/project-layout/master/examples/README.md†L1-L9】.

When to Add an /examples Directory

Include this directory when your repository contains reusable code that benefits from live demonstrations. The following situations warrant adding examples:

Public Libraries

Demonstrate your library's API and show idiomatic usage to reduce the learning curve for downstream developers. Place small programs with a main package that import the library and exercise core features.

Complex Applications

Highlight entry points, configuration patterns, or integration points such as CLI flags and HTTP servers. Include end-to-end example binaries that build and run with a single go run ./examples/... command.

Teaching and Documentation

Provide hands-on code that developers can copy into the Go Playground or local workspaces. These short, self-contained examples reinforce written documentation without requiring extra setup.

Testing Edge Cases

Serve as integration-style examples that verify the public contract across versions. These are example programs compiled in CI pipelines using commands like go test -run Example.

Showcasing Best Practices

Give concrete references for recommended patterns including error handling, context usage, and architecture. Use representative scaffolding that mirrors the repository's recommended structure using /cmd, /internal, and /pkg.

When to Skip the /examples Directory

Do not create this directory if your project is a tiny script or single-file utility, as it adds unnecessary noise. Also avoid it when comprehensive unit tests and documentation already cover all usage scenarios, preventing duplicate effort.

Structuring Go Examples

Effective examples are self-contained and reference the repository's internal structure. They should compile with a single go run command.

Library Usage Example

Create examples/hello/main.go to demonstrate public API consumption:

package main

import (
	"fmt"
	"github.com/golang-standards/project-layout/pkg/hello"
)

func main() {
	// Demonstrates the public API of the `hello` package.
	msg := hello.Greet("World")
	fmt.Println(msg) // Output: Hello, World!
}

Run with: go run ./examples/hello.

Application Bootstrap Example

For complex applications, create examples/server/serve.go showing integration:

package main

import (
	"log"
	"net/http"

	"github.com/golang-standards/project-layout/internal/app/server"
)

func main() {
	srv := server.New()
	log.Println("Listening on :8080")
	if err := http.ListenAndServe(":8080", srv); err != nil {
		log.Fatalf("server failed: %v", err)
	}
}

Run with: go run ./examples/server.

Key Files in the Standard Layout

Understanding the reference documentation helps implement this convention correctly:

• README.md: The root file mentions /examples in the overview and links to its dedicated documentation【/cache/repos/github.com/golang-standards/project-layout/master/README.md†L165-L169】.
• examples/README.md: Defines the directory's purpose and lists external reference projects【/cache/repos/github.com/golang-standards/project-layout/master/examples/README.md†L1-L9】.
• Example program files: Concrete implementations like examples/hello/main.go or examples/server/serve.go illustrate component usage.

Summary

• The /examples directory stores runnable demonstrations for libraries and applications.
• Add it for public APIs, complex architectures, educational content, and CI integration tests.
• Keep examples self-contained and executable with go run ./examples/....
• Omit it for single-file utilities or when tests already provide sufficient documentation.
• Structure examples to mirror the repository's layout using /internal, /pkg, and /cmd.

Frequently Asked Questions

Should I put example tests or unit tests in the /examples directory?

Unit tests belong in *_test.go files within their respective packages. The /examples directory is specifically for standalone main packages that demonstrate real-world usage. However, you can compile examples in CI to serve as integration tests using go test -run Example.

Can I have multiple example applications in subdirectories?

Yes, organize related examples into subdirectories like examples/cli/ and examples/web/. Each subdirectory should contain its own main package and be runnable independently with go run ./examples/cli or go run ./examples/web.

How do I import my own package in /examples code?

Use the full module path as declared in your go.mod file. For instance, if your module is github.com/org/project, import internal packages like github.com/org/project/internal/app/server or public packages like github.com/org/project/pkg/hello in your example files.

Is the /examples directory required for every Go project?

No, the directory is optional. Single-file utilities or internal tools without external consumers do not need examples. Only add it when downstream developers or new team members would benefit from seeing executable usage patterns.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}