# App Lifecycle
Source: https://docs.gocopper.dev/architecture/app-lifecycle



Every Copper binary starts the same way: you create the app, then hand it something to run. Let's look at the `main.go` from a generated project:

```go cmd/app/main.go theme={null}
func main() {
	app := copper.New()

	server, err := InitServer(app)
	if err != nil {
		log.Fatalln("Failed to init server: ", err.Error())
	}

	app.Start(server)
}
```

`copper.New()` builds the **app container**, which parses command-line flags, loads config, and sets up the logger and lifecycle:

```go theme={null}
type App struct {
	Lifecycle *clifecycle.Lifecycle
	Config    cconfig.Loader
	Logger    clogger.CoreLogger
}
```

### Runners

Anything with a `Run() error` method can be run by the app:

```go theme={null}
type Runner interface {
	Run() error
}
```

`chttp.Server` and `csql.Migrator` both implement it, and you are free to implement it with your own types, such as a job worker, a queue consumer, or a one-off script.

### Run vs. Start

* **`app.Run(runners...)`** is for short-lived work. It runs each runner in order, then shuts down. This is how the migrate binary works: `app.Run(migrator)`.
* **`app.Start(runners...)`** is for long-lived work. It runs each runner, then blocks until the process receives `SIGINT` or `SIGTERM`, and shuts down gracefully. This is how the HTTP server runs.

If any runner returns an error, the app logs it and exits with code 1.

### Registering Cleanup with OnStop

You may register cleanup work, such as closing a database connection or flushing a client, using `OnStop`. Copper will run these functions during shutdown, each with a deadline context:

```go theme={null}
func NewClient(lc *clifecycle.Lifecycle) (*Client, error) {
	conn, err := dial()
	if err != nil {
		return nil, err
	}

	lc.OnStop(func(ctx context.Context) error {
		return conn.Close()
	})

	return &Client{conn: conn}, nil
}
```

### Running Background Goroutines

You should not use a bare `go` statement for long-running work, since the app has no way to wait for it during shutdown. Instead, use `Lifecycle.Go`. Goroutines started this way are tracked, awaited on shutdown, and recovered from panics, so a panic is logged with its stack trace instead of crashing the app:

```go theme={null}
lc.Go(func(ctx context.Context) {
	err := telemetry.Upload(ctx, flightData)
	if err != nil {
		logger.Error("Failed to upload flight data", err)
	}
})
```

### Graceful Shutdown

Shutdown happens in two phases, which is what makes it graceful:

1. **`Lifecycle.Shutdown()`** is a channel that closes when shutdown *begins*. Loops should select on it to exit.
2. **`Lifecycle.Context()`** is a context that stays valid *during* shutdown so that in-flight work can finish. It is only canceled at the very end.

A long-running worker uses both:

```go theme={null}
func (t *Tracker) Run() error {
	t.lc.Go(func(ctx context.Context) {
		ticker := time.NewTicker(10 * time.Second)
		defer ticker.Stop()

		for {
			select {
			case <-t.lc.Shutdown():
				return
			case <-ticker.C:
				t.pingSatellites(ctx)
			}
		}
	})

	return nil
}
```

<Warning>
  Shutdown waits up to 30 seconds for `Go` goroutines to finish before running `OnStop` funcs and exiting. Work that can't finish in time is abandoned, so keep background tasks incremental.
</Warning>


# Dependency Injection
Source: https://docs.gocopper.dev/architecture/dependency-injection



Copper uses [google/wire](https://github.com/google/wire) for dependency injection. Wire generates plain Go code at build time, so there is no runtime container and no reflection. If your dependency graph has a problem, you will find out with a compile error rather than a production surprise.

You will rarely write wire code by hand. `copper scaffold:pkg`, `scaffold:router`, and `scaffold:queries` maintain it for you, and `copper run` regenerates it on every build.

### Wire Modules

Each package declares what it provides in a `wire.go` file:

```go pkg/rockets/wire.go theme={null}
var WireModule = wire.NewSet(
	LoadConfig,
	wire.Struct(new(NewSvcParams), "*"),
	NewSvc,
	wire.Struct(new(NewRouterParams), "*"),
	NewRouter,
)
```

The `wire.Struct(new(NewSvcParams), "*")` line tells wire to fill every field of the params struct from the dependency graph. This **params struct convention** is used throughout Copper:

```go theme={null}
type NewSvcParams struct {
	Queries *Queries
	Mission *missions.Svc
	Logger  clogger.Logger
}

func NewSvc(p NewSvcParams) *Svc {
	return &Svc{queries: p.Queries, mission: p.Mission, logger: p.Logger}
}
```

Adding a dependency is a one-line struct change. You will not need to update constructor signatures throughout your codebase, or edit any wire code beyond the package's own module.

### Composing Modules

`pkg/app/wire.go` is the composition root for your packages. `copper scaffold:pkg` adds each new package's module to it, alongside a few app-level providers:

```go pkg/app/wire.go theme={null}
var WireModule = wire.NewSet(
	MetricsRegistry,
	ProvideLoggerHooks,

	rockets.WireModule,
	missions.WireModule,
)
```

Copper ships several wire modules that you may pull into your binaries as needed:

| Module                      | Provides                                                                                             |
| --------------------------- | ---------------------------------------------------------------------------------------------------- |
| `copper.WireModule`         | `cconfig.Loader`, `*clifecycle.Lifecycle`, `clogger.Logger`                                          |
| `chttp.WireModule`          | HTTP server, JSON/HTML reader-writers, request logger middleware                                     |
| `chttp.WireModuleEmptyHTML` | Empty HTML/static dir values to satisfy `chttp.WireModule` in API-only apps with no `web/` directory |
| `csql.WireModule`           | DB connection, `csql.Querier`, migrator, transaction middleware                                      |
| `cmetrics.WireModule`       | `cmetrics.Metrics` (you provide the `*Registry`)                                                     |

### Binding Interfaces

If you would like to depend on an interface rather than a concrete type, add a `wire.Bind`:

```go theme={null}
var WireModule = wire.NewSet(
	wire.Struct(new(NewSvcParams), "*"),
	NewSvc,
	wire.Bind(new(Telemetry), new(*SatelliteTelemetry)),
)
```

Any package may now ask for `Telemetry` and receive the satellite implementation. If you decide to swap implementations later, it is a one-line change.

### Regenerating

Wire output is generated into `wire_gen.go` files, which are checked in. `copper run` and `copper build` regenerate them automatically. If you would like to run the generator manually:

```
go run github.com/google/wire/cmd/wire ./...
```

<Note>
  Wire errors can look intimidating, but they almost always say one of two things: a type has **no provider** (a constructor or module is missing from a wire set) or has **two providers** (the same type is provided in two modules). Read the first error, find the type it names, and check your `WireModule`s for it.
</Note>


# Request Lifecycle
Source: https://docs.gocopper.dev/architecture/request-lifecycle



Understanding how a request travels through a Copper application makes everything else in these docs feel less magical. This page follows one request from the socket to the response.

### Accepting the Request

`copper.New()` builds the app container, and `app.Start(server)` runs `chttp.Server`, which listens on the configured port (5901 in generated projects). Every request that arrives is handled by a single `http.Handler` assembled at startup in `pkg/app/handler.go`:

```go pkg/app/handler.go theme={null}
func NewHTTPHandler(p NewHTTPHandlerParams) http.Handler {
	return chttp.NewHandler(chttp.NewHandlerParams{
		Routers: []chttp.Router{
			p.Rockets,
		},
		GlobalMiddlewares: []chttp.Middleware{
			chttp.SetRequestIDInCtxMiddleware(),
			p.DatabaseTxMW,
			p.RequestLoggerMW,
		},
		Logger: p.Logger,
	})
}
```

This is the one place where your application's routers and global middlewares come together. Since the handler is built by [dependency injection](/architecture/dependency-injection), adding a router means adding a field, nothing more.

### Matching the Route

Copper collects every route from every router and sorts them automatically, so the most specific route wins regardless of declaration order. To learn how matching works, see [Routing](/http/routing).

### Running the Middleware

The matched request then passes through the middleware chain, from the outside in:

1. **Panic recovery**, which Copper installs automatically. If anything below panics, the error and stack are logged and the client receives a 500.
2. **Global middlewares**, in the order they are listed. In a generated project that means a request ID is placed in the context, `csql.TxMiddleware` opens a database transaction for mutating requests, and the request logger starts its timer.
3. **Route middlewares**, which run only for the route that declares them. Since they sit inside the global chain, they are the right place for concerns that apply to some endpoints but not others, such as auth on an admin route:

```go theme={null}
{
	Path:        "/admin/rockets",
	Methods:     []string{http.MethodPost},
	Middlewares: []chttp.Middleware{ro.authMW},
	Handler:     ro.HandleDecommissionRocket,
},
```

Each middleware wraps the next, so a request runs panic recovery, then each global middleware in order, then each route middleware in order, then your handler; the same chain unwinds in reverse as the response is written. To learn more, including the built-in middlewares and how to write your own, see [Middleware](/http/middleware).

### Handling the Request

Your handler is a plain `http.HandlerFunc` on a router struct. It reads path parameters with `chttp.URLParams`, decodes and validates the body, and calls into your [services](/the-basics/packages). Anything downstream that touches the database through `csql.Querier` automatically participates in the request's transaction, since the transaction travels in the request context. To learn more, see [Transactions](/database/transactions).

### Writing the Response

The handler writes its response through one of Copper's writers: `WriteJSON` for APIs, `WriteHTML` for Go templates, or the Inertia renderer for React pages. As the response is written, the middleware chain unwinds:

* `TxMiddleware` commits or rolls back the request's transaction based on the response status, and any `OnCommit` callbacks run once the commit succeeds. The full rules live in [Transactions](/database/transactions).
* The request logger records the method, path, status, and duration, and emits the built-in [HTTP metrics](/digging-deeper/metrics).

### Where Inertia Fits

An Inertia page render is an ordinary handler that ends in `inertia.Render` instead of `WriteJSON`, and the lifecycle above applies unchanged. The only difference is the response format, which the renderer picks per request:

* On a **first visit**, it renders the full HTML shell (`layouts/main.html`), embeds the page component name and props as JSON, and the [Vite render func](/frontend/vite) injects the right script tags. React boots and takes over.
* On **subsequent navigations**, Inertia's client sends the `X-Inertia` header, and the renderer responds with a small JSON payload of the next page's props instead of HTML. No full page load happens again.

Either way it is the same route, the same middleware chain, and the same transaction semantics. To learn more, see [Inertia](/frontend/inertia).

### Next

Now that you can trace a request end to end, you may want to read [App Lifecycle](/architecture/app-lifecycle) for what happens at startup and shutdown, or [Dependency Injection](/architecture/dependency-injection) for how the handler graph is assembled.


# Migrations
Source: https://docs.gocopper.dev/database/migrations



Migrations are plain SQL files in the `migrations/` directory, run with [sql-migrate](https://github.com/rubenv/sql-migrate). Since they are embedded into your binary, a deployed application carries its own schema history.

### Writing Migrations

Migration files are named sequentially with a short description, such as `0001_initial.sql` and `0002_create_rockets.sql`. Each file has an up and a down section:

```sql migrations/0002_create_rockets.sql theme={null}
-- +migrate Up
CREATE TABLE rockets (
    id         TEXT PRIMARY KEY,
    created_at TIMESTAMP NOT NULL DEFAULT NOW(),
    name       TEXT NOT NULL,
    fuel       BIGINT NOT NULL DEFAULT 0
);

CREATE INDEX idx_rockets_name ON rockets (name);

-- +migrate Down
DROP TABLE IF EXISTS rockets;
```

### Running Migrations

During development, you rarely need to think about migrations since `copper run` applies any pending ones before starting your application. If you would like to skip this, pass `-migrate=false`.

You may also run migrations on their own:

```
copper migrate
```

To roll back, pass the direction:

```
copper migrate -direction=down
```

<Warning>
  `down` reverts only the most recent migration. You may run it again to step back further.
</Warning>

### Migrations in Production

`copper build` compiles a standalone migrator alongside your app:

```
copper build
./build/migrate.out -config config/prod.toml    # apply pending migrations
./build/app.out -config config/prod.toml        # start the app
```

Run the migrator as a deploy step before starting (or restarting) the app.

To roll back the most recent migration, set the direction with `-set`:

```
./build/migrate.out -config config/prod.toml -set 'csql.migrations.direction="down"'
```

The value is parsed as TOML, so the inner quotes matter. All of the `[csql.migrations]` keys are listed in the [Configuration Reference](/reference/configuration).


# Models
Source: https://docs.gocopper.dev/database/models



Copper models are plain Go structs. There is no ORM and no base class to extend; a model is simply a struct whose fields are tagged with the columns they map to.

### Defining a Model

Models conventionally live in your package's `models.go`. Columns are mapped to fields using `db:` tags, and you may add `json:` tags alongside them when the same struct shapes your API responses or Inertia props:

```go pkg/rockets/models.go theme={null}
type Rocket struct {
	ID        int64     `db:"id,readonly"        json:"id"`
	CreatedAt time.Time `db:"created_at,readonly" json:"createdAt"`
	Name      string    `db:"name"                json:"name"`
	Fuel      int64     `db:"fuel"                json:"fuel"`
	Note      *string   `db:"note"                json:"note,omitempty"`
}
```

The `db:` tags are used both when scanning rows in [Queries](/database/queries) and when generating SQL fragments with [Query Builder](/database/query-builder).

### Nullable Columns

Pointer fields map to nullable columns. A `NULL` value scans as `nil`, and writing `nil` stores a `NULL`. If you would like to build pointers inline, the `cvars.Ptr` helper saves you a temporary variable:

```go theme={null}
rocket.Note = cvars.Ptr("engine check complete")
```

### The readonly Modifier

The `,readonly` modifier marks columns that are written once and never updated, such as `id` and `created_at`. Readonly columns are included when inserting but excluded when updating, which is enforced by the [Query Builder](/database/query-builder) `SetColumns` and `SetValues` functions.

### Tag Rules

* Fields without a `db:` tag, tagged `db:"-"`, or unexported are skipped.
* Embedded structs are flattened; their tagged fields are included recursively.
* `db:"col,readonly"` includes the column in inserts but excludes it from updates, as described above.

### Custom Column Types

Since scanning is built on `database/sql`, any type that implements `driver.Valuer` and `sql.Scanner` may be used as a column type. This lets a domain type validate and format itself while being stored as a simple column:

```go theme={null}
type LaunchCode string

func (c LaunchCode) Value() (driver.Value, error) {
	return string(c), nil
}

func (c *LaunchCode) Scan(src any) error {
	s, ok := src.(string)
	if !ok {
		return fmt.Errorf("cannot scan %T into LaunchCode", src)
	}

	*c = LaunchCode(s)
	return nil
}
```

### Next

Now that you have a model, you may want to read and write it with [Queries](/database/queries), or generate the SQL fragments from its tags with [Query Builder](/database/query-builder).


# Queries
Source: https://docs.gocopper.dev/database/queries



Copper's `csql` package provides a thin, productive layer over `database/sql`. Queries are parameterized and scanned into plain structs, so there is no ORM to learn and no query language beyond SQL itself.

### The Queries Struct

Each package that talks to the database keeps its queries in a `Queries` struct. You may scaffold one using the CLI:

```
copper scaffold:queries rockets
```

This creates `pkg/rockets/queries.go` and adds it to the package's wire module:

```go pkg/rockets/queries.go theme={null}
func NewQueries(querier csql.Querier) *Queries {
	return &Queries{querier: querier}
}

type Queries struct {
	querier csql.Querier
}
```

### Models

Rows are scanned into plain structs whose `db:` tags map columns to fields. The examples on this page use the following model; to learn more about defining models, tag rules, and custom column types, see [Models](/database/models):

```go pkg/rockets/models.go theme={null}
type Rocket struct {
	ID        int64     `db:"id,readonly"`
	CreatedAt time.Time `db:"created_at,readonly"`
	Name      string    `db:"name"`
	Fuel      int64     `db:"fuel"`
	Note      *string   `db:"note"` // nullable column
}
```

### Reading Rows

The `Get` method scans a single row into a struct, while `Select` scans multiple rows into a slice. Rather than writing `SELECT *` or a hand-maintained column list, render the columns from the model's `db:` tags with [`qb.Columns`](/database/query-builder):

```go theme={null}
func (q *Queries) GetRocket(ctx context.Context, id int64) (*Rocket, error) {
	var rocket Rocket

	query := fmt.Sprintf("SELECT %s FROM rockets WHERE id = ?", qb.Columns(Rocket{}))

	err := q.querier.Get(ctx, &rocket, query, id)
	if err != nil {
		return nil, err
	}

	return &rocket, nil
}

func (q *Queries) ListRockets(ctx context.Context) ([]Rocket, error) {
	var rockets []Rocket

	query := fmt.Sprintf("SELECT %s FROM rockets ORDER BY created_at DESC", qb.Columns(Rocket{}))

	err := q.querier.Select(ctx, &rockets, query)
	if err != nil {
		return nil, err
	}

	return rockets, nil
}
```

<Note>
  You should always write `?` placeholders, regardless of your database. Copper will automatically rebind them to your dialect's native style, such as `$1` for Postgres, before executing the query.
</Note>

### Writing Rows

`Exec` runs INSERT, UPDATE, and DELETE statements:

```go theme={null}
func (q *Queries) RefuelRocket(ctx context.Context, id int64, fuel int64) error {
	result, err := q.querier.Exec(ctx,
		"UPDATE rockets SET fuel = ? WHERE id = ?", fuel, id)
	if err != nil {
		return err
	}

	n, err := result.RowsAffected()
	if err != nil {
		return err
	}

	if n == 0 {
		return ErrRocketNotFound
	}

	return nil
}
```

### Handling Missing Rows

`Get` returns `sql.ErrNoRows` when nothing matches. It is common to alias it as a package sentinel so that callers do not need to import `database/sql`:

```go pkg/rockets/models.go theme={null}
var ErrRocketNotFound = sql.ErrNoRows
```

```go theme={null}
rocket, err := ro.queries.GetRocket(ctx, id)
if errors.Is(err, rockets.ErrRocketNotFound) {
	// respond with 404
}
```

### IN Queries

To pass a slice into an `IN (?)` clause, use `WithIn()`:

```go theme={null}
var rockets []Rocket

query := fmt.Sprintf("SELECT %s FROM rockets WHERE id IN (?)", qb.Columns(Rocket{}))

err := q.querier.WithIn().Select(ctx, &rockets, query, []int64{101, 102})
```

Copper expands the single `?` into one placeholder per element of the slice.

### Connections and Drivers

Copper opens the connection from your config and closes it on shutdown:

```toml config/dev.toml theme={null}
[csql]
dialect = "pgx"
dsn = "postgresql://postgres:dev@127.0.0.1/postgres?sslmode=disable"
```

The database driver is blank-imported by your application rather than by Copper. `copper create` sets this up for you in `cmd/app/wire.go`:

```go theme={null}
import (
	_ "github.com/jackc/pgx/v5/stdlib"
)
```

The pool defaults to 25 open connections, 25 idle connections, and a 5-minute connection lifetime. If you would like to tune these, set `max_open_connections`, `max_idle_connections`, and `conn_max_lifetime_mins` under `[csql]`. All of the available keys are listed in the [Configuration Reference](/reference/configuration).

### Next

Now that you can read and write rows, you may want to learn how Copper wraps mutating requests in automatic [Transactions](/database/transactions), or let [Query Builder](/database/query-builder) write your column lists for you.


# Query Builder
Source: https://docs.gocopper.dev/database/query-builder



Hand-written column lists are tedious to maintain and tend to drift out of sync with your models. The `csql/qb` package derives SQL fragments from your models' `db:` tags, so your queries stay correct as the struct changes.

Throughout this page, let's assume we have the following model:

```go theme={null}
type Rocket struct {
	ID        string    `db:"id,readonly"`
	CreatedAt time.Time `db:"created_at,readonly"`
	Name      string    `db:"name"`
	Fuel      int64     `db:"fuel"`
}
```

### Inserts

`qb.Columns` renders the column list, `qb.ValuePlaceholders` the matching `?`s, and `qb.Values` the arguments:

```go theme={null}
func (q *Queries) InsertRocket(ctx context.Context, rocket Rocket) error {
	query := fmt.Sprintf("INSERT INTO rockets (%s) VALUES (%s)",
		qb.Columns(rocket), qb.ValuePlaceholders(rocket))

	_, err := q.querier.Exec(ctx, query, qb.Values(rocket)...)
	return err
}
```

This renders `INSERT INTO rockets (id, created_at, name, fuel) VALUES (?, ?, ?, ?)`.

### Selects

`qb.Columns` also works on a zero value, which is handy for SELECT statements:

```go theme={null}
func (q *Queries) GetRocket(ctx context.Context, id int64) (*Rocket, error) {
	var rocket Rocket

	query := fmt.Sprintf("SELECT %s FROM rockets WHERE id = ?", qb.Columns(Rocket{}))

	err := q.querier.Get(ctx, &rocket, query, id)
	if err != nil {
		return nil, err
	}

	return &rocket, nil
}
```

For joined queries, you may pass a table alias; `qb.Columns(Rocket{}, "r")` renders `r.id, r.created_at, r.name, r.fuel`.

### Updates and `readonly`

`qb.SetColumns` and `qb.SetValues` render `SET` clauses, and this is where the `,readonly` tag modifier earns its keep. Columns marked `readonly`, such as `id` and `created_at`, are included in inserts but excluded from updates:

```go theme={null}
func (q *Queries) UpdateRocket(ctx context.Context, rocket Rocket) error {
	query := fmt.Sprintf("UPDATE rockets SET %s WHERE id = ?", qb.SetColumns(rocket))

	_, err := q.querier.Exec(ctx, query, append(qb.SetValues(rocket), rocket.ID)...)
	return err
}
```

This renders `UPDATE rockets SET name = ?, fuel = ? WHERE id = ?`. The readonly columns never appear.

### Upserts

`qb.ValuesAndSetValues` returns the insert values followed by the update values, which lines up exactly with an upsert:

```go theme={null}
query := fmt.Sprintf(
	"INSERT INTO rockets (%s) VALUES (%s) ON CONFLICT (id) DO UPDATE SET %s",
	qb.Columns(rocket), qb.ValuePlaceholders(rocket), qb.SetColumns(rocket))

_, err := q.querier.Exec(ctx, query, qb.ValuesAndSetValues(rocket)...)
```

All of the functions above follow the same tag rules: untagged, `db:"-"`, and unexported fields are skipped, while embedded structs are flattened recursively. To learn more, see [Models](/database/models).


# Transactions
Source: https://docs.gocopper.dev/database/transactions



In Copper, transactions travel through `context.Context`. When a transaction is active, every `Get`, `Select`, and `Exec` that receives that context automatically runs inside it. Your queries and services do not need a `tx` parameter, and the same code works identically inside and outside a transaction.

### Automatic Transactions per Request

Apps scaffolded with a database include `csql.TxMiddleware` as a global middleware. It wraps every **mutating** request (POST, PUT, PATCH, DELETE) in a transaction:

* On a 2xx or 3xx response, the transaction commits.
* On a 4xx or 5xx response, it rolls back.
* GET, HEAD, and OPTIONS requests are not wrapped; reads auto-commit against the pool.

As a result, a handler that writes three rows and then fails is atomic by default, without any transaction plumbing in your handlers.

<Note>
  If the commit itself fails on a 2xx response, the middleware will respond with a 500 instead, so a client never sees a success status for data that was not committed.
</Note>

### Explicit Transactions

Outside of HTTP handlers, such as background workers or CLI tasks, you may manage transactions explicitly using `InTx`:

```go theme={null}
err := s.querier.InTx(ctx, func(ctx context.Context) error {
	if err := s.queries.DeductFuel(ctx, rocketID, amount); err != nil {
		return err
	}

	return s.queries.RecordBurn(ctx, rocketID, amount)
})
```

Return `nil` to commit, or an error to roll everything back. Panics are caught by a deferred rollback, so a transaction is never left open.

`InReadOnlyTx` works the same way but always rolls back, which is useful for running multiple reads against one consistent snapshot.

### Running After the Commit

Some side effects, such as publishing an event or sending an email, should only happen if the transaction commits. You may register them using `OnCommit`:

```go theme={null}
func (s *Svc) LaunchRocket(ctx context.Context, id int64) error {
	launch, err := s.queries.InsertLaunch(ctx, id)
	if err != nil {
		return err
	}

	event := LaunchedEvent{LaunchID: launch.ID, RocketID: id}

	return s.querier.OnCommit(ctx, func(ctx context.Context) error {
		return s.pubsub.Publish(ctx, TopicRocketLaunched, event)
	})
}
```

If the transaction rolls back, the callback is discarded. Since callbacks run in the background with a 30-second timeout, you should snapshot the data you need (like `event` above) before registering the callback rather than re-reading it inside.

<Note>
  If there is no transaction in the context, `OnCommit` runs the callback immediately in the background, so the same service code works with or without an ambient transaction.
</Note>

### Escaping the Transaction

Occasionally a write should persist even if the surrounding transaction rolls back, such as an audit log or a failure record. You may use `csql.CtxWithoutTx` to run a query outside the ambient transaction:

```go theme={null}
// Recorded even if the request's transaction rolls back
_ = s.queries.RecordLaunchAttempt(csql.CtxWithoutTx(ctx), rocketID)
```

All other context values, such as deadlines, tracing, and auth, are preserved; only the transaction is removed.

### Dry Runs

Because the request transaction commits or rolls back based on your response, you get dry-run support almost for free: do the real work, then roll back before responding.

```go theme={null}
func (ro *Router) HandleLaunchRocket(w http.ResponseWriter, r *http.Request) {
	var (
		ctx = r.Context()
		id  = chttp.URLParams(r)["id"]
	)

	launch, err := ro.rockets.Launch(ctx, id)
	if err != nil {
		ro.logger.Error("Failed to launch rocket", err)
		w.WriteHeader(http.StatusInternalServerError)
		return
	}

	if r.URL.Query().Get("dry_run") == "true" {
		_ = ro.querier.RollbackTx(ctx)
	}

	ro.rw.WriteJSON(w, chttp.WriteJSONParams{Data: launch})
}
```

The full code path runs, including validations, queries, and computed results, but nothing is persisted, and any `OnCommit` callbacks are discarded with the rollback.

### Next

Next, learn how to define and evolve your schema with [Migrations](/database/migrations).


# Background Work
Source: https://docs.gocopper.dev/digging-deeper/background-work



Not everything happens during a request. This guide covers the patterns for running work in the background, from a quick goroutine to a dedicated worker binary.

### Managed Goroutines

You should avoid starting a bare `go func()` in a Copper application. Instead, use `Lifecycle.Go`; Copper recovers panics for you and will automatically wait for the goroutine to finish during graceful shutdown:

```go theme={null}
s.lifecycle.Go(func(ctx context.Context) {
	s.processTelemetry(ctx, batch)
})
```

### Long-Running Workers

For a worker loop, combine `Lifecycle.Go` with `Lifecycle.Shutdown()`, which closes when the app begins shutting down:

```go pkg/telemetry/poller.go theme={null}
func (p *Poller) Start() {
	p.lifecycle.Go(func(ctx context.Context) {
		ticker := time.NewTicker(30 * time.Second)
		defer ticker.Stop()

		for {
			select {
			case <-p.lifecycle.Shutdown():
				return
			case <-ticker.C:
				if err := p.pollRockets(ctx); err != nil {
					p.logger.Error("Failed to poll rocket telemetry", err)
				}
			}
		}
	})
}
```

To learn more about the shutdown mechanics, see [App Lifecycle](/architecture/app-lifecycle).

### A Dedicated Worker Binary

When background work outgrows the web process, you may give it its own binary. Add a `cmd/jobs` directory with the same `main.go`/`wire.go` shape as `cmd/app`, wire the same `app.WireModule`, and start a runner instead of the HTTP server:

```go cmd/jobs/main.go theme={null}
func main() {
	app := copper.New()

	runner, err := InitRunner(app)
	if err != nil {
		app.Logger.Error("Failed to init jobs runner", err)
		os.Exit(1)
	}

	app.Start(runner)
}
```

A runner is anything with a `Run() error` method (the `copper.Runner` interface). Both binaries share one dependency graph, and `copper build` compiles every target under `cmd/`, so deploying the worker is simply deploying another binary from the same codebase.

### Work Tied to a Transaction

Sometimes background work should only happen if the surrounding database transaction commits, such as sending an email or publishing an event. In that case, register the work with `querier.OnCommit` instead of acting immediately; if the transaction rolls back, the callback never runs. To learn more, see [Transactions](/database/transactions).

### Reacting to Events

When one action should trigger several reactions, you may publish an event and let interested packages subscribe. See [Pub/Sub](/digging-deeper/pubsub).

### Scheduled Work

The simplest cron in a Copper app is an HTTP route. Add an `/internal/...` route that performs the work, and have your scheduler (crontab, Cloud Scheduler, Kubernetes CronJob) POST to it:

```go theme={null}
{
	Path:    "/internal/rebalance-fuel",
	Methods: []string{http.MethodPost},
	Handler: ro.HandleRebalanceFuel,
},
```

```
*/15 * * * * curl -X POST http://localhost:5901/internal/rebalance-fuel
```

This approach gives you request logging, metrics, and manual triggering for free, since running the job by hand is just a `curl`. However, you should keep `/internal/` routes unexposed at the network layer, since the application does not authenticate them.


# Deployment
Source: https://docs.gocopper.dev/digging-deeper/deployment



A Copper application deploys as a single binary, with templates, static assets, and migrations embedded at build time.

### Building

To compile your application for production, run the `build` command:

```
copper build
```

This regenerates wire code, embeds your frontend's built assets, and compiles every target under `cmd/` into `build/`:

```
build/app.out
build/migrate.out
```

If your application has a `web/` frontend, you should run its production build first, since `copper build` embeds the build output but does not run the frontend build itself:

```
cd web && bun run build
```

You may use the `--only` flag to build specific targets:

```
copper build --only=app,migrate
```

### Running in Production

Run migrations first, then start the app with your production config:

```
./build/migrate.out -config config/prod.toml
./build/app.out -config config/prod.toml
```

Copper shuts down gracefully on `SIGINT` and `SIGTERM`: in-flight requests finish, background goroutines are waited on, and cleanup hooks run, all within a 30-second limit. You should point your process manager's stop signal at `SIGTERM` and allow at least that long.

### Production Configuration

You should keep `config/prod.toml` free of secrets. Since config files are templates, you may pull secrets from the environment or a secrets manager at startup:

```toml config/prod.toml theme={null}
extends = ["base.toml"]

[csql]
dsn = "{{ .EnvVars.DATABASE_URL }}"

[rockets]
telemetry_api_key = "{{ exec "gcloud secrets versions access latest --secret=TELEMETRY_API_KEY" }}"

[clogger]
format = "json"
level_filter = ["info", "warn", "error"]
```

JSON logs with a level filter play well with log aggregators. To learn more, see [Configuration](/the-basics/configuration) and [Logging](/the-basics/logging).

### Docker

Copper apps containerize well, since the whole application is a single binary plus a config directory. To learn how to write a multi-stage Dockerfile with proper layer caching, see [Docker](/digging-deeper/docker).

### One-Off Overrides

You may override any config value at the command line without editing files:

```
./build/app.out -config config/prod.toml -set "chttp.port=8080"
```


# Docker
Source: https://docs.gocopper.dev/digging-deeper/docker



Since a Copper application compiles to a single binary, it fits Docker naturally: build the frontend in a JavaScript image, compile the app in a Go image, and run it in a minimal image that contains little more than your binaries and config. Keeping the stages separate also gives you precise layer caching, so a frontend-only change does not rebuild your Go code, and vice versa.

### The Dockerfile

The following multi-stage build covers the default GRIP application:

```docker Dockerfile theme={null}
# Stage 1: build the frontend
FROM oven/bun:1 AS web
WORKDIR /src/web
COPY web/package.json web/bun.lock ./
RUN bun install --frozen-lockfile
COPY web ./
RUN bun run build

# Stage 2: compile the app
FROM golang:1.24-alpine AS build
RUN go install github.com/gocopper/cli/cmd/copper@v1.4.0
WORKDIR /src
COPY go.mod go.sum ./
RUN go mod download
COPY . .
COPY --from=web /src/web/build ./web/build
RUN copper build --only=app,migrate

# Stage 3: the runtime image
FROM alpine:3.21
RUN apk add --no-cache ca-certificates
WORKDIR /app
COPY --from=build /src/build ./build
COPY --from=build /src/config ./config
EXPOSE 5901
CMD ["./build/app.out", "-config", "config/prod.toml"]
```

The frontend stage runs the Vite production build, and its output is copied into the Go stage before `copper build` embeds it. This ordering matters: `copper build` embeds whatever is in `web/build` but does not run the frontend build itself, so the Go image never needs a JavaScript toolchain. If you use npm instead of bun, swap the first stage for a `node` image and copy `package-lock.json` in place of `bun.lock`.

### Caching Dependencies

Each stage copies its dependency manifests and installs before copying the rest of the source. Docker caches those layers, so day-to-day builds skip `bun install` and `go mod download` entirely unless a lockfile changes. You are free to tighten this further with a `.dockerignore`:

```text .dockerignore theme={null}
build/
web/build/
web/node_modules/
config/local.toml
*.db
.git/
```

<Warning>
  Always exclude `config/local.toml` and any other secret-bearing files from the image. Production secrets should reach the app through the environment or a secrets manager, as described in [Deployment](/digging-deeper/deployment).
</Warning>

### Running Migrations

The image includes `migrate.out`, so you may run migrations as a release step before starting the new version:

```
docker run --rm my-app ./build/migrate.out -config config/prod.toml
```

Orchestrators offer a natural home for this: an init container in Kubernetes, a release command in your deploy tool, or simply a step in your pipeline. To learn more, see [Migrations](/database/migrations).

### API-Only Applications

If your application was created with `-frontend none`, drop the first stage and the `COPY --from=web` line; the rest of the Dockerfile works as-is.

<Note>
  If you use the `sqlite3` storage, the binary depends on cgo. Build with `CGO_ENABLED=1` and a C toolchain (`apk add gcc musl-dev` on alpine), and keep the builder and runtime libc in sync. The Postgres and MySQL drivers are pure Go, so the default stack needs none of this.
</Note>

### Graceful Shutdown

Copper shuts down cleanly on `SIGTERM`, which is what `docker stop` and most orchestrators send. Since in-flight requests, background goroutines, and cleanup hooks are given up to 30 seconds, you should allow at least that long before the platform escalates to `SIGKILL`: for example, `docker stop --timeout 35` or `terminationGracePeriodSeconds: 35` in Kubernetes.

### Next

Now that your application is containerized, you may want to review [Deployment](/digging-deeper/deployment) for production configuration and secrets, or [Metrics](/digging-deeper/metrics) to monitor it once it is running.


# Metrics
Source: https://docs.gocopper.dev/digging-deeper/metrics



Copper's `cmetrics` package provides Prometheus metrics with a declare-then-use model: register your counters and histograms up front, then emit them from anywhere. The `cprometheus` package (from [gocopper/pkg](https://github.com/gocopper/pkg)) exposes them over HTTP.

### Declaring Metrics

To declare your application's metrics, provide a `*cmetrics.Registry` and add `cmetrics.WireModule` to your wire set:

```go pkg/app/metrics.go theme={null}
func MetricsRegistry() *cmetrics.Registry {
	return cmetrics.NewRegistry(cmetrics.NewRegistryParams{
		Counters: []cmetrics.Counter{
			{Name: "rocket_launches_total", Labels: []string{"status"}},
		},
		Histograms: []cmetrics.Histogram{
			{Name: "launch_duration_seconds", Labels: []string{"rocket"}, Buckets: []float64{1, 5, 15, 60}},
		},
	})
}
```

Projects scaffolded with `copper create` already include this file and the wiring, so you only need to add your metrics to the registry.

### Emitting Metrics

To emit a metric, inject `cmetrics.Metrics` and reference the metric by name:

```go theme={null}
s.metrics.CounterInc("rocket_launches_total", map[string]string{"status": "success"})

s.metrics.HistogramObserve("launch_duration_seconds", map[string]string{"rocket": rocket.Name}, dur.Seconds())
```

<Note>
  Emitting an unregistered metric name (or a mismatched label set) logs a warning and does nothing; it will never panic or return an error.
</Note>

### Built-in HTTP Metrics

Every registry automatically includes two built-in metrics, which are emitted by `chttp.RequestLoggerMiddleware` (wired in by default):

* `http_requests_total{status_code, path}`
* `http_request_duration_seconds{status_code, path}`

The `path` label is the route template (`/api/rockets/{id}`) rather than the raw URL, so cardinality stays manageable.

### Exposing the Metrics Endpoint

To expose your metrics over HTTP, add `cprometheus.WireModule`, register `*cprometheus.Router` in your handler, and enable the endpoint in your config:

```toml theme={null}
[cprometheus]
http_enabled = true
http_path = "/internal/metrics" # default
```

The endpoint is disabled by default, so you may enable it only in the environments that Prometheus scrapes.


# Pub/Sub
Source: https://docs.gocopper.dev/digging-deeper/pubsub



The `cpubsub` package (from [gocopper/pkg](https://github.com/gocopper/pkg)) allows your packages to publish events without knowing who consumes them. Two backends are included: an in-process local backend, and a Redis backend for when multiple processes need to hear about events. To get started, install the package:

```
go get github.com/gocopper/pkg/cpubsub
```

### The PubSub Interface

Both backends implement the same small interface:

```go theme={null}
type PubSub interface {
	Subscribe(ctx context.Context, topic string, handler Handler) error
	Publish(ctx context.Context, topic string, payload any) error
}
```

Choose a backend by adding the corresponding wire module to your app:

```go theme={null}
cpubsub.WireModuleLocal // in-process, no dependencies

cpubsub.WireModuleRedis // requires you to provide a *redis.Client
```

### Publishing Events

You should define topics as package constants so that subscribers may import them:

```go theme={null}
const TopicRocketLaunched = "rockets.launched"

err := s.pubsub.Publish(ctx, TopicRocketLaunched, LaunchedEvent{
	RocketID: rocket.ID,
})
```

If you are publishing as part of a database transaction, you may wish to publish from an `OnCommit` callback so that the event is only sent once the transaction commits. To learn more, see [Transactions](/database/transactions).

### Subscribing to Topics

It is most common to subscribe in a constructor so that the subscription is in place when the app starts:

```go theme={null}
func NewTelemetry(p NewTelemetryParams) (*Telemetry, error) {
	t := &Telemetry{logger: p.Logger}

	err := p.PubSub.Subscribe(context.Background(), rockets.TopicRocketLaunched, t.handleRocketLaunched)
	if err != nil {
		return nil, cerrors.New(err, "failed to subscribe to rocket launches", nil)
	}

	return t, nil
}

func (t *Telemetry) handleRocketLaunched(ctx context.Context, payload any) error {
	// ...
	return nil
}
```

Handlers run on managed background goroutines, and subscriptions remain active until the app shuts down.

### Payloads Across Backends

The local backend hands your handler the exact Go value you published. The Redis backend, however, serializes payloads as JSON, so handlers receive the decoded form (a `map[string]any` for structs). If a handler needs the typed struct, you may convert it by marshaling and unmarshaling again:

```go theme={null}
func (t *Telemetry) handleRocketLaunched(ctx context.Context, payload any) error {
	var event rockets.LaunchedEvent

	raw, err := json.Marshal(payload)
	if err != nil {
		return cerrors.New(err, "failed to marshal payload", nil)
	}

	if err := json.Unmarshal(raw, &event); err != nil {
		return cerrors.New(err, "failed to unmarshal launched event", nil)
	}

	// ...
	return nil
}
```

<Warning>
  `cpubsub` is fire-and-forget: handler errors are logged but not retried, and there are no delivery guarantees or acknowledgments. In addition, the Redis backend broadcasts to every subscribed process. For work that must not be lost, or must run exactly once, consider persisting a job row and letting a worker claim it instead. See [Background Work](/digging-deeper/background-work).
</Warning>


# Sending Email
Source: https://docs.gocopper.dev/digging-deeper/sending-email



The `cmailer` package (from [gocopper/pkg](https://github.com/gocopper/pkg)) provides a simple `Mailer` interface with two backends: AWS SES for production and a log mailer for development. To get started, install the package:

```
go get github.com/gocopper/pkg/cmailer
```

### Setup

`cmailer` does not ship a wire module, so you should provide the constructor for the backend you would like to use directly in your app's wire set:

```go pkg/app/wire.go theme={null}
var WireModule = wire.NewSet(
	// ...
	cmailer.NewLogMailer, // dev: logs emails instead of sending them
)
```

In production, you may use `cmailer.NewAWSMailer` instead and configure your SES credentials:

```toml config/prod.toml theme={null}
[aws]
region = "us-east-1"
access_key_id = "{{ .EnvVars.AWS_ACCESS_KEY_ID }}"
secret_access_key = "{{ .EnvVars.AWS_SECRET_ACCESS_KEY }}"
```

### Sending

To send an email, inject `cmailer.Mailer` wherever you need it and call its `Send` method:

```go theme={null}
err := s.mailer.Send(ctx, cmailer.SendParams{
	From:     "mission-control@rocketlog.dev",
	To:       []string{crew.Email},
	Subject:  "Launch confirmed",
	HTMLBody: cvars.Ptr("<p>Your rocket launches at T-minus 10.</p>"),
})
```

`HTMLBody` and `PlainBody` are both optional pointers, and you may set either or both. The `cvars.Ptr` helper (from `github.com/gocopper/pkg/cvars`) saves you a temporary variable.

<Note>
  The log mailer writes the full email to your app's logs, so you can develop email flows without an SES account or a real inbox.
</Note>


# Testing
Source: https://docs.gocopper.dev/digging-deeper/testing



Copper applications are plain Go, so testing is plain `go test`. Copper helps in two ways: every package's dependencies are explicit, so test doubles drop in naturally, and most Copper packages ship a `<pkg>test` sibling with ready-made test helpers.

### Testing Handlers

Since handlers are exported methods on a router you construct yourself, you may unit-test them directly with `httptest`, without starting a server:

```go pkg/rockets/router_test.go theme={null}
func TestHandleLaunchRocket(t *testing.T) {
	t.Parallel()

	router := rockets.NewRouter(rockets.NewRouterParams{
		Rockets: &rocketstest.MockSvc{},
		RW:      chttptest.NewJSONReaderWriter(t),
		Logger:  clogger.NewNoop(),
	})

	req := httptest.NewRequest(http.MethodPost, "/api/rockets/falcon/launch", nil)
	req = mux.SetURLVars(req, map[string]string{"id": "falcon"})
	resp := httptest.NewRecorder()

	router.HandleLaunchRocket(resp, req)

	require.Equal(t, http.StatusOK, resp.Code)
}
```

<Note>
  `mux.SetURLVars` (from `github.com/gorilla/mux`, Copper's router) injects path parameters when you call a handler directly, since no routing happened. You may skip it for routes without `{params}`.
</Note>

If you would like to exercise routing, middleware, and handlers together, build a real handler with `chttp.NewHandler` and serve it with `httptest.NewServer`.

### Test Helpers

Most helpers live in a `<pkg>test` sibling package; a few (like `clogger`'s and `cmetrics`'s) ship in the package itself:

| Helper                                                        | Use                                                            |
| ------------------------------------------------------------- | -------------------------------------------------------------- |
| `clogger.NewNoop()`                                           | A logger that discards everything; the workhorse of test setup |
| `clogger.NewRecorder(&logs)`                                  | Records logs into a slice so you can assert on them            |
| `chttptest.NewJSONReaderWriter(t)` / `NewHTMLReaderWriter(t)` | Ready-made reader/writers for router tests                     |
| `chttptest.NewRouter(routes)` / `PingRoutes(t, routes)`       | Wrap ad-hoc routes; assert every route responds                |
| `cconfigtest.SetupDirWithConfigs(t, files)`                   | Temp config dir from a map of file contents                    |
| `clifecycletest.New()`                                        | A lifecycle for tests, no signal handling                      |
| `cmetrics.NewNoopMetrics()`                                   | Metrics that go nowhere                                        |

To assert on your application's logs, record them with `clogger.NewRecorder`:

```go theme={null}
var logs []clogger.RecordedLog

svc := rockets.NewSvc(rockets.NewSvcParams{
	Logger: clogger.NewRecorder(&logs),
})

// ...

require.Len(t, logs, 1)
require.Equal(t, clogger.LevelError, logs[0].Level)
```

### Mocking Your Own Packages

You may follow the same convention for your own services. Define an interface in the package, and place a hand-written mock in a `<pkg>test` sibling so that other packages can use it:

```go pkg/rockets/rocketstest/svc.go theme={null}
package rocketstest

var _ rockets.Svc = (*MockSvc)(nil)

type MockSvc struct {
	LaunchErr   error
	LaunchCalls []string
}

func (m *MockSvc) Launch(ctx context.Context, id string) (*rockets.Launch, error) {
	m.LaunchCalls = append(m.LaunchCalls, id)

	if m.LaunchErr != nil {
		return nil, m.LaunchErr
	}

	return &rockets.Launch{RocketID: id}, nil
}
```

The `var _ rockets.Svc = (*MockSvc)(nil)` line asks the compiler to verify that the mock stays in sync with the interface, while exported fields like `LaunchErr` allow each test to force the failure it needs.


# Inertia
Source: https://docs.gocopper.dev/frontend/inertia



[Inertia](https://inertiajs.com) lets you build a modern React frontend with classic server-side routing. Your Go routers decide which page to show and what data it receives, while React renders it. Since the server drives navigation, there is no client-side router to maintain and no REST layer between your pages and your services. This is the default stack for new Copper projects.

The `inertia` package (from [gocopper/pkg](https://github.com/gocopper/pkg)) provides the server-side adapter, wired in automatically by `copper create`.

### Rendering a Page

Inject `*inertia.Renderer` into your router and call `Render` with a component name and props:

```go pkg/rockets/router.go theme={null}
func (ro *Router) HandleRocketsPage(w http.ResponseWriter, r *http.Request) {
	rockets, err := ro.rockets.List(r.Context())
	if err != nil {
		ro.logger.Error("Failed to list rockets", err)
		w.WriteHeader(http.StatusInternalServerError)
		return
	}

	ro.inertia.Render(w, r, inertia.RenderParams{
		Component: "rockets",
		Props: map[string]any{
			"rockets": rockets,
		},
	})
}
```

Components live in `web/src/pages/` and receive props directly:

```tsx web/src/pages/rockets.tsx theme={null}
export default function Rockets({ rockets }) {
  return (
    <ul>
      {rockets.map((rocket) => (
        <li key={rocket.id}>{rocket.name}</li>
      ))}
    </ul>
  )
}
```

On a full page load, Copper renders the HTML shell with the page data embedded. On navigation, Inertia requests only the JSON; the renderer will detect which is which automatically.

### Forms

You may read and validate a form submission using `ReadForm`, which decodes the JSON body and validates its `valid:` tags ([govalidator](https://github.com/asaskevich/govalidator)). On validation failure, the error is flashed automatically and `ReadForm` returns `false`, so you simply redirect back:

```go theme={null}
func (ro *Router) HandleCreateRocket(w http.ResponseWriter, r *http.Request) {
	var form struct {
		Name string `json:"name" valid:"required"`
	}

	if !ro.inertia.ReadForm(w, r, &form) {
		ro.inertia.Redirect303(w, r, "/rockets")
		return
	}

	rocket, err := ro.rockets.Create(r.Context(), form.Name)
	if err != nil {
		ro.inertia.FlashProps(r, map[string]any{
			"error": "Could not create the rocket. Please try again.",
		})
		ro.inertia.Redirect303(w, r, "/rockets")
		return
	}

	ro.inertia.Redirect303(w, r, "/rockets/"+rocket.ID)
}
```

This is the classic post/redirect/get pattern: mutations always end in `Redirect303`, and the next render picks up any flashed props. Validation errors appear on the client under `flash.validationError`.

<Warning>
  `ReadForm`'s two failure modes differ: a body that fails validation flashes the error and leaves the response for you to write, but a body that can't be decoded as JSON at all writes an error response itself. Both return `false`.
</Warning>

### Flash Props

`FlashProps` stores props for a single upcoming render, which is perfect for success and error messages across a redirect:

```go theme={null}
ro.inertia.FlashProps(r, map[string]any{
	"success": "Rocket launched!",
})
ro.inertia.Redirect303(w, r, "/rockets")
```

The next page render receives them under the `flash` prop, after which they are gone:

```tsx theme={null}
export default function Rockets({ rockets, flash }) {
  return (
    <>
      {flash?.success && <Banner>{flash.success}</Banner>}
      {/* ... */}
    </>
  )
}
```

### Shared Props

`ShareProps` adds props to the current request's render from anywhere. It is typically called from a middleware so that every page in a section receives common data:

```go theme={null}
func (mw *PropsMiddleware) Handle(next http.Handler) http.Handler {
	return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
		mw.inertia.ShareProps(r.Context(), map[string]any{
			"missionName": mw.config.MissionName,
		})

		next.ServeHTTP(w, r)
	})
}
```

You may attach the middleware per-route via `Middlewares`, or globally in `pkg/app/handler.go`.

<Note>
  `ShareProps` identifies the request via its request ID, so `chttp.SetRequestIDInCtxMiddleware()` must be in your global middlewares. Scaffolded projects include it by default. Successive calls for the same request replace previously shared props rather than merging them, so you should share everything in a single call.
</Note>

### Partial Reloads

When the client reloads only specific props (`router.reload({ only: ["rockets"] })`), you may skip computing everything else with `ShouldLoadProp`:

```go theme={null}
props := map[string]any{}

if inertia.ShouldLoadProp(r, "telemetry") {
	props["telemetry"] = ro.rockets.LoadTelemetry(ctx)
}
```

`ShouldLoadProp` returns `true` on full renders and only for the requested props on partial reloads.

### Deferred Props

Deferred props let a page render immediately while slow data loads in a follow-up request. Declare them in `DeferredProps`, and guard the expensive work with `ShouldLoadDeferredProp`:

```go theme={null}
func (ro *Router) HandleMissionControl(w http.ResponseWriter, r *http.Request) {
	props := map[string]any{
		"mission": ro.rockets.Mission(r.Context()),
	}

	if inertia.ShouldLoadDeferredProp(r, "telemetry") {
		props["telemetry"] = ro.rockets.LoadTelemetry(r.Context())
	}

	ro.inertia.Render(w, r, inertia.RenderParams{
		Component: "mission-control",
		Props:     props,
		DeferredProps: map[string][]string{
			"default": {"telemetry"},
		},
	})
}
```

Unlike `ShouldLoadProp`, `ShouldLoadDeferredProp` returns `false` on the initial render: the prop is stripped from the first response and fetched immediately afterwards. On the client, wrap the slow section in Inertia's `<Deferred>`:

```tsx theme={null}
<Deferred data="telemetry" fallback={<Spinner />}>
  <TelemetryPanel />
</Deferred>
```

### Customizing the Renderer

The renderer is immutable; each `With*` method returns a copy, so you may configure it once in your constructor:

```go theme={null}
func NewRouter(p NewRouterParams) *Router {
	return &Router{
		inertia: p.Inertia.WithBasePath("/admin"),
	}
}
```

* `WithBasePath(path)` mounts a section under a URL prefix. Redirects and page URLs have the prefix stripped so that client-side paths stay clean; it pairs with [`chttp.base_path`](/http/routing#serving-under-a-base-path).
* `WithLayoutTemplate(name)` renders pages inside a different layout than `main.html`.
* `WithComponent(name)` sets a default component for all renders.

`RenderParams` accepts per-render `LayoutTemplate` and `BasePath` overrides too.

### Server-Side Rendering

SSR is opt-in. Run the Inertia SSR server (see the [Inertia SSR guide](https://inertiajs.com/server-side-rendering)) and enable it in config:

```toml theme={null}
[inertia]
ssr = true
ssr_server = "http://localhost:13714"
```

Copper sends each page to the SSR server and injects the rendered HTML. If the SSR server is down or errors, Copper logs a warning and falls back to client-side rendering, so SSR will never take your pages down.

### Configuration

| Key          | Default                  | Description                                |
| ------------ | ------------------------ | ------------------------------------------ |
| `ssr`        | `false`                  | Render pages through an Inertia SSR server |
| `ssr_server` | `http://localhost:13714` | Address of the SSR server                  |


# Overview
Source: https://docs.gocopper.dev/frontend/overview



Copper treats the frontend as part of your application rather than an afterthought. React and Inertia are the R and I of the [GRIP stack](/): the dev server, asset pipeline, and production builds are all handled by the CLI, and your Go routers render React pages directly.

### Choosing a Stack

`copper create` supports two frontend stacks via the `-frontend` flag:

* **`inertia:react`** (default) is a React app powered by [Vite](/frontend/vite) and [Inertia](/frontend/inertia). Your Go routers render React pages directly, giving you server-side routing and client-side interactivity without a separate API layer or client router to maintain.
* **`none`** creates no `web/` directory, which is ideal for JSON APIs or for classic server-rendered [HTML views](/http/html-views) using Go templates.

```
copper create -frontend=inertia:react github.com/gocopper/rockets
```

### Development

A single command runs everything:

```
copper run -watch
```

This starts your app on `http://localhost:5901` and the Vite dev server on port `3000`. Copper injects the Vite client into your pages, so hot module replacement works out of the box: edit a React component and the browser updates without a reload. Go changes will trigger a rebuild and restart automatically.

The scaffolded `config/dev.toml` enables the dev-mode behavior:

```toml config/dev.toml theme={null}
[vitejs]
dev_mode = true

[chttp]
use_local_html = true
render_html_error = true
```

### Production Builds

To build for production, run the frontend build followed by `copper build`:

```
cd web && npm run build && cd ..
copper build
```

`npm run build` (or `bun run build`) runs the Vite production build, outputting hashed assets into `web/build/static`. `copper build` then copies `web/public` in alongside them and generates `web/build/embed.go` so that all assets compile into your binary. Deploying a Copper app, frontend included, is a matter of copying a single file.

### The web Directory

```
web/
├── wire.go              # embeds src/ and registers render funcs
├── public/              # static files served as-is under /static
├── src/
│   ├── layouts/main.html    # HTML shell rendered by the server
│   ├── pages/               # your React page components
│   ├── main.tsx             # frontend entrypoint
│   └── styles.css
├── vite.config.ts
└── package.json
```

`web/wire.go` is the bridge between the frontend and Go: it embeds the templates and registers the [Vite render func](/frontend/vite) that emits the right script tags:

```go web/wire.go theme={null}
//go:embed src
var HTMLDir embed.FS

func HTMLRenderFuncs(vite *vitejs.Assets) []chttp.HTMLRenderFunc {
	return []chttp.HTMLRenderFunc{
		vite.HTMLRenderFunc(),
	}
}
```

<Note>
  Copper uses [bun](https://bun.sh) when it is installed and falls back to npm, both for installing dependencies at scaffold time and for running the dev server.
</Note>


# Vite
Source: https://docs.gocopper.dev/frontend/vite



The `vitejs` package (from [gocopper/pkg](https://github.com/gocopper/pkg)) connects your Go templates to [Vite](https://vitejs.dev): the dev server during development, and hashed production assets in a release build. Your templates do not change between the two.

### viteAssets

The layout calls a single template function in its `<head>`:

```html web/src/layouts/main.html theme={null}
<!doctype html>
<html>
<head>
    <meta charset="utf-8" />
    {{ viteAssets }}
</head>
<body>
    {{ template "content" . }}
</body>
</html>
```

`viteAssets` emits whatever the current mode needs, so you never write script tags by hand.

### Development Mode

With `dev_mode` enabled, `viteAssets` points the page at the Vite dev server:

```toml config/dev.toml theme={null}
[vitejs]
dev_mode = true
```

It injects the Vite client and your entrypoint as module scripts, along with the React fast-refresh preamble, so HMR works without any frontend configuration. Copper discovers your entrypoint by convention: `src/main.js`, `.ts`, `.jsx`, or `.tsx`.

### Production Mode

When `dev_mode` is off (the default), `viteAssets` reads the Vite build manifest from the assets embedded in your binary and emits the hashed `<script>` and `<link rel="stylesheet">` tags for your entrypoint. There is nothing to configure: the frontend build (`npm run build`) emits the manifest into `web/build/static`, and `copper build` embeds it.

### Wiring

The scaffolded project wires this up for you: `vitejs.WireModule` provides `*vitejs.Assets`, and `web/wire.go` registers its render func:

```go web/wire.go theme={null}
func HTMLRenderFuncs(vite *vitejs.Assets) []chttp.HTMLRenderFunc {
	return []chttp.HTMLRenderFunc{
		vite.HTMLRenderFunc(),
	}
}
```

### Configuration

| Key        | Default                 | Description                                                         |
| ---------- | ----------------------- | ------------------------------------------------------------------- |
| `dev_mode` | `false`                 | Serve assets from the Vite dev server instead of the embedded build |
| `host`     | `http://localhost:3000` | Where the Vite dev server runs                                      |

<Note>
  The dev-mode integration currently targets React, since the HMR preamble it injects is React's fast refresh. Production mode is framework-agnostic.
</Note>


# Create a Project
Source: https://docs.gocopper.dev/getting-started/create-project



You may create a new Copper project using the `copper create` command, passing your Go module path:

```
copper create github.com/gocopper/rocketlog
```

This scaffolds a complete application into `./rocketlog` on the [GRIP stack](/): a **G**olang server and **R**eact frontend, connected by **I**nertia and backed by **P**ostgres with migrations. GRIP is the stack Copper is optimized for, and every piece can be swapped using the flags below.

Once the project is created, you can start it in watch mode:

```
cd rocketlog && copper run -watch
```

Your application is now accessible in your browser at [http://localhost:5901](http://localhost:5901). Copper rebuilds and restarts it whenever you save a Go file under `pkg/`, and the Vite dev server runs alongside on port 3000 so that frontend changes hot-reload as well.

### Choosing a Frontend

The `-frontend` flag controls the frontend stack:

```
copper create -frontend=none github.com/gocopper/rocketlog
```

| Value                     | What you get                                                                                 |
| ------------------------- | -------------------------------------------------------------------------------------------- |
| `inertia:react` (default) | React + TypeScript + Vite, rendered from your Go routers via [Inertia.js](/frontend/inertia) |
| `none`                    | No frontend; ideal for JSON APIs and services                                                |

Copper uses [bun](https://bun.sh) to install and run the frontend if you have it, and falls back to npm otherwise.

### Choosing Storage

The `-storage` flag controls the database:

```
copper create -storage=sqlite3 github.com/gocopper/rocketlog
```

| Value                | What you get                                  |
| -------------------- | --------------------------------------------- |
| `postgres` (default) | Postgres via the `pgx` driver                 |
| `sqlite3`            | SQLite; zero setup, great for getting started |
| `mysql`              | MySQL                                         |
| `none`               | No database layer                             |

Every storage option (except `none`) includes a `migrations/` directory and a `migrate` binary, and `copper run` applies pending migrations on startup.

### Next Steps

Now that you have created your application, you may want to follow the [tutorial](/getting-started/tutorial) to build your first feature, or take a tour of the [directory structure](/getting-started/directory-structure).


# Directory Structure
Source: https://docs.gocopper.dev/getting-started/directory-structure



A freshly created Copper project, using the default `inertia:react` frontend and a database, looks like this:

```
rocketlog/
├── cmd/
│   ├── app/            # HTTP server binary
│   └── migrate/        # database migration binary
├── config/
│   ├── base.toml       # shared config
│   ├── dev.toml        # development overrides
│   └── prod.toml       # production overrides
├── migrations/
│   ├── 0001_initial.sql
│   └── wire.go         # embeds *.sql into the migrate binary
├── pkg/
│   └── app/
│       ├── handler.go  # assembles routers & global middleware
│       ├── logger.go   # logger hooks
│       ├── metrics.go  # metrics registry
│       ├── router.go   # root router (renders the index page)
│       └── wire.go     # composes your packages' wire modules
├── web/
│   ├── public/         # static files served at /static
│   ├── src/
│   │   ├── layouts/    # HTML layout templates
│   │   ├── pages/      # React pages (Inertia components)
│   │   └── main.tsx    # frontend entrypoint
│   ├── package.json
│   ├── vite.config.ts
│   └── wire.go         # embeds templates into the app binary
├── go.mod
├── .gitignore
└── .golangci.yaml
```

### cmd/

Each subdirectory is a binary. `cmd/app` runs the HTTP server, while `cmd/migrate` applies database migrations. Both are thin `main.go` files plus a `wire.go` describing their dependencies; all real logic lives in `pkg/`. `copper build` compiles every `cmd/*` target into `build/`.

### config/

TOML configuration, layered with `extends`. Both `dev.toml` and `prod.toml` extend `base.toml`. See [Configuration](/the-basics/configuration) for more.

### migrations/

Sequentially numbered SQL files, embedded into the `migrate` binary so that production deploys are self-contained. See [Migrations](/database/migrations).

### pkg/

Your application code. Each feature gets its own package, and `copper scaffold:pkg rockets` creates one and registers it in `pkg/app/wire.go`. The `app` package is the composition root, collecting every package's routers into the HTTP handler and every package's wire module into the application.

### web/

The frontend. Everything under `src/` (templates and React code) and `public/` is embedded into the application binary at build time, so you ship a single executable. During development, `use_local_html = true` in `dev.toml` serves these files from disk instead, giving you live reload.

<Note>
  After `copper build`, you'll also see `build/` (compiled binaries) and `web/build/` (compiled frontend assets plus a generated `embed.go`). Both are gitignored.
</Note>


# Installation
Source: https://docs.gocopper.dev/getting-started/installation



Copper ships with a CLI that scaffolds projects, generates code, runs database migrations, and rebuilds your application as you work.

### Installing the Copper CLI

Before creating your first Copper application, make sure your local machine has Go 1.24 or newer installed. You may then install the CLI via `go install`:

```
go install github.com/gocopper/cli/cmd/copper@latest
```

You can verify the installation by running the `copper` command:

```
copper -h
```

### Troubleshooting

If your shell can't find `copper`, your Go bin directory is not on your `PATH`. You may add it to your shell profile (`~/.zshrc` or `~/.bashrc`):

```bash theme={null}
export PATH="$PATH:$(go env GOPATH)/bin"
```

After restarting your shell, `copper -h` should work as expected.

### Database

New projects use Postgres, the P in the GRIP stack, so you should have a server running locally before creating one. If you have Docker installed, a single command starts a database that matches the scaffolded development config out of the box:

```bash theme={null}
docker run -d --name copper-db -p 5432:5432 -e POSTGRES_PASSWORD=dev postgres:16
```

If you would prefer zero setup, you may pass `-storage sqlite3` to `copper create`, or `-storage none` if you don't need a database at all.


# Tutorial: Your First App
Source: https://docs.gocopper.dev/getting-started/tutorial



In this tutorial, we'll build **rocketlog**, a small application on the [GRIP stack](/) that tracks a fleet of rockets. Along the way, you'll touch every layer of a Copper application: migrations, queries, routing, and a React page rendered from your Go handlers.

You'll need the [Copper CLI installed](/getting-started/installation) and Postgres running. If you don't have Postgres handy, Docker can start one:

```bash theme={null}
docker run -d --name rocketlog-db -p 5432:5432 -e POSTGRES_PASSWORD=dev postgres:16
```

### Creating the Project

Let's create the project and start it in watch mode:

```
copper create github.com/gocopper/rocketlog
cd rocketlog
copper run -watch
```

Once it starts, your application will be accessible in your browser at [http://localhost:5901](http://localhost:5901). Leave `copper run -watch` running while you work; it rebuilds and restarts the application whenever you save a Go file under `pkg/`, and the Vite dev server hot-reloads your React changes.

### Defining the Schema

New projects come with an empty first migration. Let's add a `rockets` table to it:

```sql migrations/0001_initial.sql theme={null}
-- +migrate Up
CREATE TABLE rockets (
    id         SERIAL PRIMARY KEY,
    name       TEXT NOT NULL,
    status     TEXT NOT NULL DEFAULT 'ready',
    created_at TIMESTAMPTZ NOT NULL DEFAULT now()
);

-- +migrate Down
DROP TABLE rockets;
```

`copper run` applies pending migrations each time it starts, so restart it (or run `copper migrate`) to create the table. Later migrations get their own sequentially numbered files; see [Migrations](/database/migrations) for more.

### Scaffolding the Feature Package

Each feature in a Copper application lives in its own package under `pkg/`. Let's scaffold one for rockets, along with a queries struct for database access:

```
copper scaffold:pkg rockets
copper scaffold:queries rockets
```

This creates `pkg/rockets/` with `models.go`, `queries.go`, and `wire.go`, and registers the package with the application. Next, define the model:

```go pkg/rockets/models.go theme={null}
package rockets

import "time"

type Rocket struct {
	ID        int64     `db:"id" json:"id"`
	Name      string    `db:"name" json:"name"`
	Status    string    `db:"status" json:"status"`
	CreatedAt time.Time `db:"created_at" json:"createdAt"`
}
```

The `db` tags map database columns to fields, while the `json` tags shape the props your React page receives.

### Writing Queries

Now let's add two methods to the scaffolded `Queries` struct:

```go pkg/rockets/queries.go theme={null}
func (q *Queries) ListRockets(ctx context.Context) ([]Rocket, error) {
	query := fmt.Sprintf("SELECT %s FROM rockets ORDER BY created_at DESC", qb.Columns(Rocket{}))

	var rockets []Rocket

	err := q.querier.Select(ctx, &rockets, query)
	if err != nil {
		return nil, err
	}

	return rockets, nil
}

func (q *Queries) InsertRocket(ctx context.Context, name string) error {
	const query = "INSERT INTO rockets (name) VALUES (?)"

	_, err := q.querier.Exec(ctx, query, name)

	return err
}
```

You may write placeholders as `?` regardless of your database; Copper rebinds them to the right style (`$1` for Postgres) automatically. The `qb.Columns` helper (from `github.com/gocopper/copper/csql/qb`) renders the column list from the model's `db:` tags, so the query never drifts from the struct; see [Query Builder](/database/query-builder) for more.

### Adding Routes

Next, scaffold a router for the package:

```
copper scaffold:router rockets
```

This creates `pkg/rockets/router.go` and registers it in `pkg/app/handler.go`. The scaffolded router only receives a logger, but our handlers also need the queries and the Inertia renderer. Add them to `NewRouterParams`, and Copper's dependency injection provides them:

```go pkg/rockets/router.go theme={null}
type NewRouterParams struct {
	Queries *Queries
	Inertia *inertia.Renderer
	Logger  clogger.Logger
}

func NewRouter(p NewRouterParams) *Router {
	return &Router{
		queries: p.Queries,
		inertia: p.Inertia,
		logger:  p.Logger,
	}
}

type Router struct {
	queries *Queries
	inertia *inertia.Renderer
	logger  clogger.Logger
}
```

There is no registration or container configuration to write. Since dependencies are resolved at compile time, Copper sees the new fields and provides them automatically. To learn more, see [Dependency Injection](/architecture/dependency-injection).

Now let's declare the routes and handlers, one to render the page and one to handle the form:

```go pkg/rockets/router.go theme={null}
func (ro *Router) Routes() []chttp.Route {
	return []chttp.Route{
		{
			Path:    "/rockets",
			Methods: []string{http.MethodGet},
			Handler: ro.HandleRocketsPage,
		},
		{
			Path:    "/rockets",
			Methods: []string{http.MethodPost},
			Handler: ro.HandleCreateRocket,
		},
	}
}

func (ro *Router) HandleRocketsPage(w http.ResponseWriter, r *http.Request) {
	rockets, err := ro.queries.ListRockets(r.Context())
	if err != nil {
		ro.logger.Error("Failed to list rockets", err)
		w.WriteHeader(http.StatusInternalServerError)
		return
	}

	ro.inertia.Render(w, r, inertia.RenderParams{
		Component: "rockets",
		Props: map[string]any{
			"rockets": rockets,
		},
	})
}

func (ro *Router) HandleCreateRocket(w http.ResponseWriter, r *http.Request) {
	var form struct {
		Name string `json:"name" valid:"required"`
	}

	if ok := ro.inertia.ReadForm(w, r, &form); !ok {
		ro.inertia.Redirect303(w, r, "/rockets")
		return
	}

	err := ro.queries.InsertRocket(r.Context(), form.Name)
	if err != nil {
		ro.logger.Error("Failed to create rocket", err)
		w.WriteHeader(http.StatusInternalServerError)
		return
	}

	ro.inertia.Redirect303(w, r, "/rockets")
}
```

`ReadForm` decodes the request and enforces the `valid` tags. If validation fails, it flashes the validation error and returns `false`, and the redirect sends the user back to the form. This POST-then-redirect shape is the standard Inertia flow; see [Inertia](/frontend/inertia) for the details.

### Building the Page

The `Component: "rockets"` above resolves to `web/src/pages/rockets.tsx`. Let's create it:

```tsx web/src/pages/rockets.tsx theme={null}
import { useForm } from "@inertiajs/react";

type Rocket = { id: number; name: string; status: string };

export default function Rockets({ rockets }: { rockets: Rocket[] }) {
  const form = useForm({ name: "" });

  return (
    <div>
      <h1>Fleet</h1>

      <ul>
        {rockets.map((rocket) => (
          <li key={rocket.id}>
            {rocket.name} — {rocket.status}
          </li>
        ))}
      </ul>

      <form
        onSubmit={(e) => {
          e.preventDefault();
          form.post("/rockets", { onSuccess: () => form.reset() });
        }}
      >
        <input
          value={form.data.name}
          onChange={(e) => form.setData("name", e.target.value)}
          placeholder="Rocket name"
        />
        <button type="submit">Add rocket</button>
      </form>
    </div>
  );
}
```

The props come straight from your handler, so there is no fetch call or API client to write. Inertia's `useForm` posts the form and re-renders the page with fresh props after the redirect.

### Trying It Out

Open [http://localhost:5901/rockets](http://localhost:5901/rockets), type a name, and add a rocket. The list updates instantly. If you submit an empty name, `valid:"required"` rejects it and the redirect brings you back.

You've now built a full-stack feature, from the database to React, without writing an API.

### Next Steps

* Go deeper on [Inertia](/frontend/inertia): flash messages, shared props, partial reloads
* Wrap multi-step writes in [Transactions](/database/transactions)
* Expose the same data as a [JSON API](/http/json)
* Add [Middleware](/http/middleware) for auth or logging
* Understand the [App Lifecycle](/architecture/app-lifecycle) behind `copper.New()`


# HTML Views
Source: https://docs.gocopper.dev/http/html-views



Copper renders server-side HTML using Go templates. Layouts, pages, and partials are all embedded into your binary.

<Note>
  New projects default to a React frontend with Inertia; see [Frontend](/frontend/overview). This page covers classic server-rendered Go templates, which are a great fit for simpler apps and HTMX-style interactivity.
</Note>

### Template Directory

Templates live under `web/src` in three conventional directories:

```
web/src/
├── layouts/
│   └── main.html        # page shell: <html>, <head>, nav
├── pages/
│   ├── index.html
│   └── rocket.html
└── partials/
    └── rocket-card.html # reusable fragments
```

A layout defines the shell and renders the page inside it:

```html web/src/layouts/main.html theme={null}
<!DOCTYPE html>
<html>
<head>
    <title>Mission Control</title>
</head>
<body>
    {{ template "content" . }}
</body>
</html>
```

```html web/src/pages/rocket.html theme={null}
{{ define "content" }}
<h1>{{ .Rocket.Name }}</h1>
<p>Status: {{ .Rocket.Status }}</p>
{{ end }}
```

### Rendering Pages

Copper provides `chttp.HTMLReaderWriter` for writing HTML responses. Inject it into your router and call `WriteHTML`:

```go theme={null}
type NewRouterParams struct {
	Rockets *Svc
	HTML    *chttp.HTMLReaderWriter
	Logger  clogger.Logger
}
```

```go theme={null}
func (ro *Router) HandleRocketPage(w http.ResponseWriter, r *http.Request) {
	rocket, err := ro.rockets.Get(r.Context(), chttp.URLParams(r)["id"])
	if err != nil {
		ro.html.WriteHTMLError(w, r, err)
		return
	}

	ro.html.WriteHTML(w, r, chttp.WriteHTMLParams{
		PageTemplate: "rocket.html",
		Data:         map[string]any{"Rocket": rocket},
	})
}
```

`LayoutTemplate` defaults to `main.html` and `StatusCode` to `200`; you may set either explicitly when needed. On errors, an appropriate page will automatically be chosen for you: `internal-error.html` for 500s and `not-found.html` for 404s.

### Template Functions

Every template has the full [Sprig](https://masterminds.github.io/sprig/) function library available, including `upper`, `date`, and `mustToRawJson`.

You may add your own functions using `chttp.HTMLRenderFunc`. Since render funcs receive the current request, they can expose per-request state such as the signed-in user:

```go web/wire.go theme={null}
func HTMLRenderFuncs() []chttp.HTMLRenderFunc {
	return []chttp.HTMLRenderFunc{
		{
			Name: "currentUser",
			Func: func(r *http.Request) (any, error) {
				return func() *sessions.User {
					return sessions.UserFromCtx(r.Context())
				}, nil
			},
		},
	}
}
```

```html theme={null}
<p>Welcome back, {{ (currentUser).Name }}</p>
```

### Partials

Partials in `web/src/partials` are reusable fragments. Render one inside any template with the built-in `partial` function:

```html theme={null}
{{ range .Rockets }}
    {{ partial "rocket-card" . }}
{{ end }}
```

You may also write a partial directly as a response, which works well for [HTMX](https://htmx.org)-style updates that swap a fragment into the page:

```go theme={null}
func (ro *Router) HandleRocketStatus(w http.ResponseWriter, r *http.Request) {
	rocket, err := ro.rockets.Get(r.Context(), chttp.URLParams(r)["id"])
	if err != nil {
		ro.html.WriteHTMLError(w, r, err)
		return
	}

	ro.html.WritePartial(w, r, chttp.WritePartialParams{
		Name: "rocket-card",
		Data: rocket,
	})
}
```

### Static Assets

Files in `web/public` are served under `/static/`. For example, `web/public/logo.svg` is available at `/static/logo.svg`. In production these files are embedded into your binary, while in development they are read from disk.

### Local Development

Two config flags make template development pleasant, and both are enabled in `config/dev.toml` for new projects:

```toml theme={null}
[chttp]
use_local_html = true     # read templates & static files live from ./web — no rebuild
render_html_error = true  # show the actual error in the browser instead of a blank 500
```

### Single-Page Apps

If your frontend handles its own routing, you may configure every unmatched GET request to render `index.html`:

```toml theme={null}
[chttp]
enable_single_page_routing = true
```

### API-Only Apps

If your application doesn't serve HTML at all, use `chttp.WireModuleEmptyHTML` in place of the HTML and static dir bindings; it satisfies wire with empty stand-ins. Projects created with `-frontend=none` are configured this way.


# JSON APIs
Source: https://docs.gocopper.dev/http/json



Copper provides `chttp.JSONReaderWriter` to read, validate, and write JSON. Add it to your router's params and wire will inject it for you:

```go theme={null}
type NewRouterParams struct {
	Rockets *Svc
	RW      *chttp.JSONReaderWriter
	Logger  clogger.Logger
}
```

<Note>
  `copper scaffold:router` generates a router with only a `Logger`. Add the `RW` field yourself when your router serves JSON.
</Note>

### Reading JSON

`ReadJSON` decodes the request body into a struct. If the body is empty, malformed, or fails validation, the `400 Bad Request` response will automatically be written for you and `ReadJSON` returns `false`, so your handler only needs to return:

```go theme={null}
func (ro *Router) HandleLaunchRocket(w http.ResponseWriter, r *http.Request) {
	var body struct {
		Destination string `json:"destination"`
	}

	if ok := ro.rw.ReadJSON(w, r, &body); !ok {
		return
	}

	// ...
}
```

### Validating

`ReadJSON` validates the body with [govalidator](https://github.com/asaskevich/govalidator) `valid:` tags before your handler sees it:

```go theme={null}
var body struct {
	Destination string  `json:"destination" valid:"required"`
	Contact     string  `json:"contact"     valid:"required,email"`
	Mode        string  `json:"mode"        valid:"in(orbital|suborbital)"`
	Payload     *string `json:"payload"     valid:"length(1|64)"`
}
```

For your own domain types, you may register a custom validator once and use it like any other tag:

```go theme={null}
func init() {
	govalidator.CustomTypeTagMap.Set("launchpad", func(i any, _ any) bool {
		pad, ok := i.(Launchpad)
		return ok && pad.Valid()
	})
}
```

```go theme={null}
Pad Launchpad `json:"pad" valid:"required,launchpad"`
```

Of course, some rules span multiple fields and don't fit in tags. You may check these at the top of your handler and respond early:

```go theme={null}
if body.Mode == "orbital" && body.Payload == nil {
	ro.rw.WriteJSON(w, chttp.WriteJSONParams{
		StatusCode: http.StatusBadRequest,
		Data:       map[string]string{"error": "orbital launches require a payload"},
	})
	return
}
```

### Writing JSON

`WriteJSON` marshals your data and sets the `Content-Type` header. The status code defaults to `200 OK`:

```go theme={null}
ro.rw.WriteJSON(w, chttp.WriteJSONParams{Data: launch})

ro.rw.WriteJSON(w, chttp.WriteJSONParams{
	StatusCode: http.StatusCreated,
	Data:       launch,
})
```

If `Data` is an `error`, it will be encoded as `{"error": "<message>"}`, which is convenient for 4xx responses.

For a bare `401`, you may use the `Unauthorized` shorthand:

```go theme={null}
ro.rw.Unauthorized(w)
```

### Putting It Together

Let's put it all together in a complete handler that reads and validates the body, calls the service, maps known errors to status codes, and responds:

```go theme={null}
func (ro *Router) HandleLaunchRocket(w http.ResponseWriter, r *http.Request) {
	var (
		ctx  = r.Context()
		id   = chttp.URLParams(r)["id"]
		body struct {
			Destination string `json:"destination" valid:"required"`
		}
	)

	if ok := ro.rw.ReadJSON(w, r, &body); !ok {
		return
	}

	launch, err := ro.rockets.Launch(ctx, id, body.Destination)
	switch {
	case errors.Is(err, ErrRocketNotFound):
		ro.rw.WriteJSON(w, chttp.WriteJSONParams{
			StatusCode: http.StatusNotFound,
			Data:       map[string]string{"error": "rocket not found"},
		})
		return
	case errors.Is(err, ErrAlreadyLaunched):
		ro.rw.WriteJSON(w, chttp.WriteJSONParams{
			StatusCode: http.StatusConflict,
			Data:       map[string]string{"error": "rocket has already launched"},
		})
		return
	case err != nil:
		ro.logger.Error("Failed to launch rocket", err)
		w.WriteHeader(http.StatusInternalServerError)
		return
	}

	ro.rw.WriteJSON(w, chttp.WriteJSONParams{
		StatusCode: http.StatusCreated,
		Data:       launch,
	})
}
```

Sentinel errors like `ErrRocketNotFound` are declared in the service package with `errors.New`. To learn more, see [Error Handling](/the-basics/error-handling).


# Middleware
Source: https://docs.gocopper.dev/http/middleware



Middleware wraps your handlers to run code before or after them, which is a natural home for concerns like authentication, logging, and transactions. In Copper, a middleware is anything that implements a single-method interface:

```go theme={null}
type Middleware interface {
	Handle(next http.Handler) http.Handler
}
```

### Writing Middleware

A middleware is typically a struct so that its dependencies can be injected by wire. For example, the following middleware protects internal routes with a bearer token:

```go pkg/rockets/middleware.go theme={null}
type NewAuthMiddlewareParams struct {
	Config Config
}

func NewAuthMiddleware(p NewAuthMiddlewareParams) *AuthMiddleware {
	return &AuthMiddleware{config: p.Config}
}

type AuthMiddleware struct {
	config Config
}

func (mw *AuthMiddleware) Handle(next http.Handler) http.Handler {
	return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
		token := strings.TrimPrefix(r.Header.Get("Authorization"), "Bearer ")

		if token != mw.config.APIToken {
			w.WriteHeader(http.StatusUnauthorized)
			return
		}

		next.ServeHTTP(w, r)
	})
}
```

For simple middleware without dependencies, you may wrap a plain function with `chttp.HandleMiddleware`:

```go theme={null}
var noCacheMW = chttp.HandleMiddleware(func(next http.Handler) http.Handler {
	return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
		w.Header().Set("Cache-Control", "no-store")
		next.ServeHTTP(w, r)
	})
})
```

### Registering Middleware

You may attach middleware to a single route using the `Middlewares` field:

```go theme={null}
{
	Path:        "/internal/rockets/refuel",
	Methods:     []string{http.MethodPost},
	Handler:     ro.HandleRefuelRockets,
	Middlewares: []chttp.Middleware{ro.authMW},
}
```

To run middleware on every request, add it to `GlobalMiddlewares` in `pkg/app/handler.go`:

```go pkg/app/handler.go theme={null}
GlobalMiddlewares: []chttp.Middleware{
	chttp.SetRequestIDInCtxMiddleware(),
	p.DatabaseTxMW,
	p.RequestLoggerMW,
},
```

Middleware runs in the order it is listed, so the first entry sees the request first. Global middleware always runs before route middleware.

### Built-in Middleware

Copper ships the middleware most apps need, already wired into new projects:

* **`chttp.SetRequestIDInCtxMiddleware()`** puts a unique request ID in the context. You may read it anywhere with `chttp.GetRequestID(ctx)`.
* **`chttp.RequestLoggerMiddleware`** logs every request's method, path, status code, and duration, and also records the built-in `http_requests_total` and `http_request_duration_seconds` Prometheus metrics. See [Metrics](/digging-deeper/metrics).
* **`csql.TxMiddleware`** wraps mutating requests in a database transaction that commits or rolls back based on the response status. See [Transactions](/database/transactions).

<Note>
  Panic recovery is built into the handler itself, so there is no recovery middleware to register. A panicking handler is logged with its stack trace and the client receives a `500`; you never need to add this yourself.
</Note>


# Routing
Source: https://docs.gocopper.dev/http/routing



In Copper, each package that serves HTTP defines a **router**, which is any type that implements a single-method interface:

```go theme={null}
type Router interface {
	Routes() []chttp.Route
}
```

When the app starts, Copper collects every router into a single handler.

### Defining Routes

To add routes to a package, scaffold a router with the CLI:

```
copper scaffold:router rockets
```

This creates `pkg/rockets/router.go`, registers the router in `pkg/app/handler.go`, and adds it to the package's wire module. A router looks like this:

```go pkg/rockets/router.go theme={null}
type NewRouterParams struct {
	Logger clogger.Logger
}

func NewRouter(p NewRouterParams) *Router {
	return &Router{logger: p.Logger}
}

type Router struct {
	logger clogger.Logger
}

func (ro *Router) Routes() []chttp.Route {
	return []chttp.Route{
		{
			Path:    "/api/rockets",
			Methods: []string{http.MethodGet},
			Handler: ro.HandleListRockets,
		},
		{
			Path:    "/api/rockets/{id}",
			Methods: []string{http.MethodGet},
			Handler: ro.HandleGetRocket,
		},
	}
}
```

Handlers are plain `http.HandlerFunc`s. Anything your handlers need, such as services, a `*chttp.JSONReaderWriter`, or config, may be added as a field on `NewRouterParams`, and wire will inject it for you.

### Path Parameters

Parameters are declared in the path with `{name}` and read using `chttp.URLParams`:

```go theme={null}
func (ro *Router) HandleGetRocket(w http.ResponseWriter, r *http.Request) {
	var (
		ctx = r.Context()
		id  = chttp.URLParams(r)["id"]
	)

	// ...
}
```

You may also constrain a parameter with a regular expression; for example, `{id:[0-9]+}` only matches numeric IDs. Since routing is backed by [gorilla/mux](https://github.com/gorilla/mux), its full pattern syntax is available.

### Query Parameters

Query parameters may be read directly from the request:

```go theme={null}
status := r.URL.Query().Get("status")
```

### Route Matching

You never need to worry about the order in which routes are declared. Copper will automatically sort them so that deeper paths match first and literal segments take priority over parameters at the same depth. For example, `/rockets/featured` always wins over `/rockets/{id}`, while a catch-all such as `/{path:.*}` matches last.

### Registering Routers

`copper scaffold:router` handles this for you, but it is useful to know where routers live. The app's HTTP handler is assembled in `pkg/app/handler.go`:

```go pkg/app/handler.go theme={null}
func NewHTTPHandler(p NewHTTPHandlerParams) http.Handler {
	return chttp.NewHandler(chttp.NewHandlerParams{
		Routers: []chttp.Router{
			p.Rockets,
		},
		GlobalMiddlewares: []chttp.Middleware{
			chttp.SetRequestIDInCtxMiddleware(),
			p.DatabaseTxMW,
			p.RequestLoggerMW,
		},
		Logger: p.Logger,
	})
}
```

### Serving Under a Base Path

If you would like to mount your entire app under a prefix, you may set `base_path` in your config:

```toml theme={null}
[chttp]
base_path = "/admin"
```

Declare your route paths with the prefix included; Copper strips it at registration time.

<Note>
  When `base_path` is set, routes that don't start with the prefix are skipped. You may set `RegisterWithBasePath: true` on a route to have the prefix joined onto its path instead, which is how Copper's static file routes work.
</Note>


# Introduction
Source: https://docs.gocopper.dev/index



Copper is a batteries-included web toolkit for Go. It provides everything you need to build a complete web application, including an HTTP server, routing, dependency injection, configuration, logging, structured errors, and SQL queries with migrations, along with a CLI that scaffolds your project, rebuilds it as you work, and compiles the entire application into a single binary.

At the same time, Copper stays out of your way. It relies on the standard library as much as possible, so handlers are plain `http.HandlerFunc`s and models are plain structs. There is no ORM and no reflection magic, and your business logic is never locked in. You own `main.go`, and every scaffolded file lands in your repo as code you are free to edit.

### The GRIP Stack

Copper is opinionated about one thing: the stack. It's built and optimized for **GRIP**:

* **G**olang for your server, services, and data layer
* **R**eact for your pages
* **I**nertia to connect the two with server-side routing
* **P**ostgres for your data

GRIP is a stack rather than a product, and you could assemble it by hand. Copper is the fastest way to build it: a single `copper create` gives you all four pieces, wired together and ready to build on. Of course, every piece is swappable. You may build [JSON APIs](/http/json) with no frontend at all, render classic [Go templates](/http/html-views), or use SQLite or MySQL instead of Postgres.

### Why Copper?

#### A Complete Toolkit

Routing, dependency injection, configuration, logging, structured errors, SQL migrations, and a Vite-powered React frontend with hot module replacement are all included, so you can start building features instead of assembling libraries.

#### No API Layer to Maintain

With [Inertia](/frontend/inertia), your Go routers render React pages directly and pass props the same way you would pass template data. You get a modern React frontend without writing an API client, a REST layer, or a client-side router.

#### Idiomatic Go

You write regular handlers, structs, and interfaces, and Copper wires them together with [google/wire](https://github.com/google/wire). Dependency injection happens at compile time, so there is no runtime container to configure or debug.

#### A Single Binary

Frontend assets, templates, and migrations are all compiled into one executable, so deploying is copying one file.

### A Taste of Copper

A page in a Copper application is a Go handler and a React component. The handler loads data and renders the component with props:

```go pkg/rockets/router.go theme={null}
func (ro *Router) HandleFleetPage(w http.ResponseWriter, r *http.Request) {
	rockets, err := ro.queries.ListRockets(r.Context())
	if err != nil {
		ro.logger.Error("Failed to list rockets", err)
		w.WriteHeader(http.StatusInternalServerError)
		return
	}

	ro.inertia.Render(w, r, inertia.RenderParams{
		Component: "fleet",
		Props: map[string]any{
			"rockets": rockets,
		},
	})
}
```

```tsx web/src/pages/fleet.tsx theme={null}
type Rocket = { id: number; name: string; status: string };

export default function Fleet({ rockets }: { rockets: Rocket[] }) {
  return (
    <ul>
      {rockets.map((rocket) => (
        <li key={rocket.id}>
          {rocket.name} — {rocket.status}
        </li>
      ))}
    </ul>
  );
}
```

There is no fetch call, serialization layer, or duplicated routing to maintain, since the server decides what to render and which data it receives.

### Next Steps

To get started, [install the Copper CLI](/getting-started/installation) and [create your first project](/getting-started/create-project). If you would like to see everything working together, the [tutorial](/getting-started/tutorial) walks through building your first application end to end. We can't wait to see what you build.


# CLI
Source: https://docs.gocopper.dev/reference/cli



The `copper` CLI scaffolds projects, builds binaries, runs your app with hot reload, and manages database migrations. Run `copper help` to see all commands.

### copper create

```
copper create [-frontend=] [-storage=] github.com/user/myapp
```

Creates a new project in `./myapp` (the last segment of the module path).

| Flag        | Default         | Options                                |
| ----------- | --------------- | -------------------------------------- |
| `-frontend` | `inertia:react` | `inertia:react`, `none`                |
| `-storage`  | `postgres`      | `postgres`, `sqlite3`, `mysql`, `none` |

With the default stack you get a React + Inertia + Vite frontend and a Postgres-backed data layer with migrations. `-frontend=none` creates a JSON API server; `-storage=none` skips the database entirely.

### copper run

```
copper run [target] [-migrate] [-web] [-watch]
```

Builds and runs a target from `cmd/`, defaulting to `app`. On the first run, it also runs database migrations and starts the Vite dev server.

| Flag       | Default                             | Description                              |
| ---------- | ----------------------------------- | ---------------------------------------- |
| `-migrate` | `true`                              | Run database migrations before starting  |
| `-web`     | `true` for `app`, `false` otherwise | Start the frontend dev server in `./web` |
| `-watch`   | `false`                             | Rebuild and restart on source changes    |

<Note>
  `-migrate` only exists in projects with a `cmd/migrate` target, and `-web` only in projects with a `web/` frontend.
</Note>

With `-watch`, Copper watches `.go` files under `pkg/` (and `web/wire.go`), debounces changes, then rebuilds and restarts the target, sending desktop notifications on build success and failure.

```
copper run              # runs app with migrations and web
copper run jobs         # runs the jobs target (no web by default)
copper run app -web=false
```

### copper build

```
copper build [--only=<targets>]
```

Builds every binary under `cmd/` into `./build/<target>.out`. If the project has a frontend, it copies the static assets from `web/public` and embeds the frontend's production build output (`web/build`) into the binary. Note that you should run the frontend build itself (`npm run build` in `web/`) beforehand. You may use `--only` to build specific targets:

```
copper build --only=app,migrate
```

### copper migrate

```
copper migrate [-direction=up|down]
```

Builds the `migrate` target and runs database migrations.

| Flag         | Default | Description                                                                |
| ------------ | ------- | -------------------------------------------------------------------------- |
| `-direction` | `up`    | `up` applies all pending migrations; `down` rolls back the most recent one |

### copper scaffold:pkg

```
copper scaffold:pkg rockets
```

Creates a new feature package:

* `pkg/rockets/wire.go` — the package's `WireModule`
* `pkg/rockets/models.go` — a home for your models

It also registers `rockets.WireModule` in `pkg/app/wire.go`.

### copper scaffold:queries

```
copper scaffold:queries rockets
```

Creates `pkg/rockets/queries.go` with a `Queries` struct wrapping `csql.Querier`, and adds `NewQueries` to the package's wire module. Run `scaffold:pkg` first if the package doesn't exist yet.

### copper scaffold:router

```
copper scaffold:router rockets
```

Creates `pkg/rockets/router.go` with an empty router, adds `NewRouter` to the package's wire module, and registers the router in `pkg/app/handler.go` so its routes are served immediately.

### copper version

```
copper version
```

Prints the CLI version.


# Configuration Reference
Source: https://docs.gocopper.dev/reference/configuration



Every configurable Copper package reads its own TOML table from your config files. All keys are optional; sensible defaults apply when a key, or the whole table, is missing. To learn how config files are loaded and layered, see [Configuration](/the-basics/configuration).

### Command-Line Flags

Every Copper binary accepts two flags:

| Flag      | Default             | Description                                                                                                                                           |
| --------- | ------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
| `-config` | `./config/dev.toml` | Path to the config file                                                                                                                               |
| `-set`    | —                   | Inline overrides, e.g. `-set "chttp.port=5902"`. Values are parsed as TOML, so quote strings: `-set 'csql.dialect="pgx"'`. Separate multiple with `;` |

### \[chttp]

| Key                                      | Type   | Default | Description                                                                                           |
| ---------------------------------------- | ------ | ------- | ----------------------------------------------------------------------------------------------------- |
| `port`                                   | uint   | `7501`  | HTTP server port (`copper create` sets `5901` in generated config)                                    |
| `read_timeout_seconds`                   | uint   | `10`    | `http.Server` read timeout                                                                            |
| `use_local_html`                         | bool   | `false` | Read templates and static files from `./web` on disk instead of the embedded copies — for development |
| `render_html_error`                      | bool   | `false` | Render a detailed error page in the browser — for development                                         |
| `enable_single_page_routing`             | bool   | `false` | Serve `index.html` for all unmatched GET routes (SPA mode)                                            |
| `redirect_url_for_unauthorized_requests` | string | —       | Where `HTMLReaderWriter.Unauthorized` redirects; plain `401` if unset                                 |
| `base_path`                              | string | —       | Mount the app under a path prefix                                                                     |

### \[clogger]

| Key             | Type      | Default | Description                                           |
| --------------- | --------- | ------- | ----------------------------------------------------- |
| `out`           | string    | stdout  | File path for debug/info logs                         |
| `err`           | string    | stderr  | File path for warn/error logs                         |
| `format`        | string    | `plain` | `plain` or `json`                                     |
| `level_filter`  | \[]string | all     | Allow-list of levels to log, e.g. `["info", "error"]` |
| `redact_fields` | \[]string | —       | Tag field names to redact — JSON format only          |

### \[csql]

| Key                      | Type   | Default | Description                                         |
| ------------------------ | ------ | ------- | --------------------------------------------------- |
| `dialect`                | string | —       | `postgres`, `pgx`, `sqlite3`, or `mysql`            |
| `dsn`                    | string | —       | Database connection string                          |
| `max_open_connections`   | int    | `25`    | Connection pool: max open connections               |
| `max_idle_connections`   | int    | `25`    | Connection pool: max idle connections               |
| `conn_max_lifetime_mins` | int    | `5`     | Connection pool: max connection lifetime in minutes |

### \[csql.migrations]

| Key         | Type   | Default | Description                                                                    |
| ----------- | ------ | ------- | ------------------------------------------------------------------------------ |
| `direction` | string | `up`    | `up` applies all pending migrations; `down` rolls back one                     |
| `source`    | string | `embed` | `embed` reads migrations from the binary; `dir` reads `./migrations` from disk |

### \[aws]

Used by `cmailer`'s AWS SES backend. See [Sending Email](/digging-deeper/sending-email).

| Key                 | Type   | Default | Description           |
| ------------------- | ------ | ------- | --------------------- |
| `region`            | string | —       | AWS region            |
| `access_key_id`     | string | —       | AWS access key ID     |
| `secret_access_key` | string | —       | AWS secret access key |

### \[inertia]

| Key          | Type   | Default                  | Description                            |
| ------------ | ------ | ------------------------ | -------------------------------------- |
| `ssr`        | bool   | `false`                  | Render pages via an Inertia SSR server |
| `ssr_server` | string | `http://localhost:13714` | SSR server URL                         |

### \[vitejs]

| Key        | Type   | Default                 | Description                                   |
| ---------- | ------ | ----------------------- | --------------------------------------------- |
| `dev_mode` | bool   | `false`                 | Load assets from the Vite dev server with HMR |
| `host`     | string | `http://localhost:3000` | Vite dev server URL                           |

### \[cprometheus]

| Key            | Type   | Default             | Description                           |
| -------------- | ------ | ------------------- | ------------------------------------- |
| `http_enabled` | bool   | `false`             | Serve the Prometheus metrics endpoint |
| `http_path`    | string | `/internal/metrics` | Path for the metrics endpoint         |


# Package Index
Source: https://docs.gocopper.dev/reference/packages



The guides on this site cover how the pieces fit together; the complete API reference for every package lives on pkg.go.dev.

### github.com/gocopper/copper

The core toolkit module.

| Package      | Description                                                            | Reference                                                              |
| ------------ | ---------------------------------------------------------------------- | ---------------------------------------------------------------------- |
| `copper`     | App container — composes config, logging, and lifecycle; runs your app | [pkg.go.dev](https://pkg.go.dev/github.com/gocopper/copper)            |
| `chttp`      | HTTP server, routing, middleware, JSON and HTML rendering              | [pkg.go.dev](https://pkg.go.dev/github.com/gocopper/copper/chttp)      |
| `csql`       | SQL queries, context-scoped transactions, and migrations               | [pkg.go.dev](https://pkg.go.dev/github.com/gocopper/copper/csql)       |
| `csql/qb`    | Query helpers that derive column lists from `db:` struct tags          | [pkg.go.dev](https://pkg.go.dev/github.com/gocopper/copper/csql/qb)    |
| `cconfig`    | Layered TOML configuration with template support                       | [pkg.go.dev](https://pkg.go.dev/github.com/gocopper/copper/cconfig)    |
| `clogger`    | Leveled, structured logging with tags, redaction, and hooks            | [pkg.go.dev](https://pkg.go.dev/github.com/gocopper/copper/clogger)    |
| `cerrors`    | Errors with structured tags and cause chains                           | [pkg.go.dev](https://pkg.go.dev/github.com/gocopper/copper/cerrors)    |
| `clifecycle` | App lifecycle — managed goroutines, graceful shutdown, cleanup hooks   | [pkg.go.dev](https://pkg.go.dev/github.com/gocopper/copper/clifecycle) |
| `cmetrics`   | Prometheus counters and histograms with a declare-then-use registry    | [pkg.go.dev](https://pkg.go.dev/github.com/gocopper/copper/cmetrics)   |

### github.com/gocopper/pkg

Optional add-on packages.

| Package       | Description                                                                                               | Reference                                                            |
| ------------- | --------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------- |
| `cmailer`     | Email sending via AWS SES, with a log backend for development                                             | [pkg.go.dev](https://pkg.go.dev/github.com/gocopper/pkg/cmailer)     |
| `cpubsub`     | Publish/subscribe with in-process and Redis backends                                                      | [pkg.go.dev](https://pkg.go.dev/github.com/gocopper/pkg/cpubsub)     |
| `cprometheus` | Mounts the Prometheus metrics endpoint as a Copper router                                                 | [pkg.go.dev](https://pkg.go.dev/github.com/gocopper/pkg/cprometheus) |
| `inertia`     | Server-side adapter for Inertia.js v2                                                                     | [pkg.go.dev](https://pkg.go.dev/github.com/gocopper/pkg/inertia)     |
| `vitejs`      | Vite asset integration — dev server with HMR in development, embedded manifest-based assets in production | [pkg.go.dev](https://pkg.go.dev/github.com/gocopper/pkg/vitejs)      |
| `crandom`     | Crypto-rand helpers for random codes and strings                                                          | [pkg.go.dev](https://pkg.go.dev/github.com/gocopper/pkg/crandom)     |
| `cvars`       | `cvars.Ptr` — take a pointer to any value inline                                                          | [pkg.go.dev](https://pkg.go.dev/github.com/gocopper/pkg/cvars)       |

### Test Helpers

Most packages ship a sibling `<pkg>test` package with test doubles and utilities: `chttptest`, `cconfigtest`, and `clifecycletest`, plus `clogger.NewNoop`, `clogger.NewRecorder`, and `cmetrics.NewNoopMetrics`. See [Testing](/digging-deeper/testing).


# Configuration
Source: https://docs.gocopper.dev/the-basics/configuration



Copper reads configuration from TOML files in the `./config` directory. A new project ships with `base.toml`, `dev.toml`, and `prod.toml`. Shared values go in `base.toml`, while each environment's file overrides what it needs.

### Extending Files

Config files declare what they build on with the `extends` key:

```toml config/dev.toml theme={null}
extends = ["base.toml"]

[rockets]
launch_site = "canaveral"
enable_telemetry = true
```

Running with `dev.toml` loads everything from `base.toml` plus the values above. The extending file itself wins when keys collide with an extended file; between files in the `extends` list, earlier ones win.

<Warning>
  Avoid top-level configuration values. Group everything under a section so that each package can load its own config without a shared "global" struct.
</Warning>

### Choosing a Config File

The `-config` flag selects which file to load. It defaults to `./config/dev.toml`:

```
./build/app.out -config=./config/prod.toml
```

For one-off overrides, you may use `-set` with TOML syntax. Separate multiple overrides with `;`:

```
./build/app.out -set "chttp.port=5902;clogger.format='json'"
```

### Reading Config in Your Package

Each package loads its own section with `cconfig.Loader`. By convention this lives in `config.go`:

```go pkg/rockets/config.go theme={null}
package rockets

import (
	"github.com/gocopper/copper/cconfig"
	"github.com/gocopper/copper/cerrors"
)

type Config struct {
	LaunchSite      string `toml:"launch_site"`
	EnableTelemetry bool   `toml:"enable_telemetry"`
}

func LoadConfig(configs cconfig.Loader) (Config, error) {
	var config Config

	err := configs.Load("rockets", &config)
	if err != nil {
		return Config{}, cerrors.New(err, "failed to load rockets config", nil)
	}

	return config, nil
}
```

Add `LoadConfig` to the package's `WireModule` and take `Config` as a field on any params struct that needs it.

If the section is missing from the config file, `Load` is a no-op and your struct keeps its zero values. For keys omitted from a section that is present, you may set defaults with the `default` tag. If you would like to cover a missing section as well, apply defaults after loading:

```go theme={null}
type Config struct {
	MaxCrew int `toml:"max_crew" default:"6"`
}
```

### Environment Variables

Config files are rendered as Go templates before parsing, with all environment variables available under `.EnvVars`:

```toml config/prod.toml theme={null}
[csql]
dsn = "{{ .EnvVars.DATABASE_URL }}"
```

### Secrets

There are two patterns for keeping secrets out of your repository.

**For development**, put secrets in a gitignored file and pull it in via `extends`:

```toml config/dev.toml theme={null}
extends = ["base.toml", "local.toml"]
```

Consider checking in a `local_example.toml` with the shape of the file and blank values, so that new teammates know what to fill in.

**For production**, use the `exec` template function to fetch secrets from a secret manager at startup. The command runs through `sh -c` and its trimmed stdout is substituted in:

```toml config/prod.toml theme={null}
[csql]
dsn = "{{ exec "gcloud secrets versions access latest --secret=DATABASE_URL" }}"
```

Since the secret is fetched when the app boots, it never touches your repository or your process environment.


# Error Handling
Source: https://docs.gocopper.dev/the-basics/error-handling



Copper provides the `cerrors` package, which adds two things to Go's plain errors: a message chain and **structured tags**. If you wrap errors on the way up, by the time one reaches your logs it will tell the whole story.

### Wrapping Errors

You may wrap an error with `cerrors.New(cause, message, tags)`:

```go theme={null}
launch, err := s.queries.GetLaunch(ctx, id)
if err != nil {
	return nil, cerrors.New(err, "failed to get launch", map[string]any{
		"launchId": id,
	})
}
```

Tags carry the context that a message alone cannot, such as IDs, states, and attempt counts. You should pass values directly rather than formatting them into the message.

If you would like to create a new error rather than wrap one, pass a `nil` cause:

```go theme={null}
if rocket.Fuel < required {
	return cerrors.New(nil, "insufficient fuel for launch", map[string]any{
		"have": rocket.Fuel,
		"need": required,
	})
}
```

When rendered, a wrapped error reads as a chain:

```
failed to launch rocket where rocketId=falcon-9 because
> failed to get launch where launchId=lc-42 because
> sql: no rows in result set
```

### Sentinel Errors

You should keep sentinel errors as plain `errors.New` values so that callers can match them with `errors.Is`:

```go theme={null}
var (
	ErrLaunchNotFound  = errors.New("launch not found")
	ErrAlreadyLaunched = errors.New("rocket has already launched")
)
```

You may return them directly or wrapped. Since `cerrors.Error` implements `Unwrap`, `errors.Is` and `errors.As` see through the chain either way.

### Handling Errors in Routers

At the HTTP boundary, you may switch on sentinels to map errors to status codes, treating everything else as a 500:

```go theme={null}
launch, err := ro.rockets.Launch(ctx, id)
switch {
case errors.Is(err, ErrLaunchNotFound):
	ro.rw.WriteJSON(w, chttp.WriteJSONParams{
		StatusCode: http.StatusNotFound,
		Data:       map[string]string{"error": "launch not found"},
	})
	return
case err != nil:
	ro.logger.Error("Failed to launch rocket", err)
	w.WriteHeader(http.StatusInternalServerError)
	return
}
```

Expected failures receive a helpful response body, while unexpected ones are logged with the full chain and return a bare 500. For the complete handler pattern, including request validation, see [JSON APIs](/http/json).

### Errors in Logs

You never need to log tags separately. When an error is passed to the logger, tags from the entire error chain are merged into the log's structured output automatically. See [Logging](/the-basics/logging) for more information.

<Note>
  `cerrors.Error` is a value type, not a pointer. If you ever need `errors.As`, match against `cerrors.Error`, not `*cerrors.Error`.
</Note>


# Logging
Source: https://docs.gocopper.dev/the-basics/logging



Copper provides the `clogger` package for structured, leveled logging. You may inject `clogger.Logger` anywhere you need it, and every scaffolded router and service already has one.

### Writing Logs

There are four levels. `Debug` and `Info` take just a message, while `Warn` and `Error` also take an error, which may be `nil`:

```go theme={null}
logger.Info("Rocket launched")
logger.Warn("Telemetry delayed", nil)
logger.Error("Failed to launch rocket", err)
```

Structured context comes from `WithTags`:

```go theme={null}
logger.WithTags(map[string]any{
	"rocketId": id,
	"attempt":  attempt,
}).Info("Launch scheduled")
```

When you pass an error, tags from its entire [cerrors](/the-basics/error-handling) chain are merged into the log automatically, so if you wrap errors well, your logs arrive pre-annotated:

```
2026/08/24 10:15:04 [ERROR] Failed to launch rocket where rocketId=falcon-9 because
> failed to get launch where launchId=lc-42 because
> sql: no rows in result set
```

### Configuration

The logger is configured under the `[clogger]` section:

```toml theme={null}
[clogger]
format = "json"
level_filter = ["info", "warn", "error"]
```

| Key             | Default    | Description                                    |
| --------------- | ---------- | ---------------------------------------------- |
| `format`        | `plain`    | `plain` for development, `json` for production |
| `out`           | stdout     | File path for Debug/Info logs                  |
| `err`           | stderr     | File path for Warn/Error logs                  |
| `level_filter`  | all levels | Which levels to log                            |
| `redact_fields` | none       | Tag fields to redact (JSON format only)        |

In JSON format, each log is a single object with `ts`, `level`, `msg`, `error`, and `tags`, ready for a log aggregator.

<Warning>
  `level_filter` is an allow-list, not a threshold. `level_filter = ["error"]` logs *only* errors. If you would like warnings as well, list both.
</Warning>

### Redacting Sensitive Fields

In JSON format, `redact_fields` replaces matching tag values with `"redacted"` anywhere in the tag tree, including nested objects. Field names match loosely, so `redact_fields = ["email"]` also catches `user_email` and `emailAddress`:

```toml theme={null}
[clogger]
format = "json"
redact_fields = ["password", "email"]
```

<Warning>
  Redaction only works with `format = "json"`. In plain format, setting `redact_fields` replaces every log message with a placeholder rather than risk leaking a field.
</Warning>

### Hooks

If you would like to ship logs to an external service, such as an error tracker or a cloud logging platform, implement `clogger.Hook`:

```go theme={null}
type Hook interface {
	OnLog(level Level, msg string, tags map[string]any, err error)
}
```

Hooks run for every log that passes the level filter. You may provide them as a `[]clogger.Hook` in your app's wire module:

```go pkg/app/logger.go theme={null}
func ProvideLoggerHooks(tracker *errtracker.Hook) []clogger.Hook {
	return []clogger.Hook{tracker}
}
```


# Feature Packages
Source: https://docs.gocopper.dev/the-basics/packages



Every feature in a Copper application lives in its own package under `pkg/`, named after the domain it owns: `pkg/rockets`, `pkg/launches`, `pkg/telemetry`. A package holds everything the feature needs — its models, business logic, database access, and routes — organized into a small set of conventional files.

You may scaffold a new package with the CLI, which creates the essentials and registers the package with the app:

```
copper scaffold:pkg rockets
```

### The Conventional Files

Not every package needs every file; start small and add files as the feature grows.

| File         | Contents                                                           |
| ------------ | ------------------------------------------------------------------ |
| `models.go`  | Structs, sentinel errors, and constants for the domain             |
| `svc.go`     | The business logic: a single `Svc` struct                          |
| `queries.go` | Database access: a single `Queries` struct wrapping `csql.Querier` |
| `router.go`  | HTTP routes: a single `Router` struct                              |
| `client.go`  | Integration with an external service: a single `Client` struct     |
| `config.go`  | The package's `Config` struct and `LoadConfig`                     |
| `utils.go`   | Pure package-level functions with no injected dependencies         |
| `wire.go`    | The package's `WireModule`, registering its constructors           |

### The Single-Struct Rule

`svc.go`, `router.go`, `queries.go`, and `client.go` each contain exactly one struct, its constructor, and its methods. This keeps every file's purpose obvious: when you open `svc.go`, you are looking at the feature's business logic and nothing else. If a second service is growing inside a package, that is usually a sign it wants to be its own package.

### Services

Business logic lives in the `Svc` struct, constructed like every other Copper component with a params struct:

```go pkg/rockets/svc.go theme={null}
type NewSvcParams struct {
	Queries *Queries
	Logger  clogger.Logger
}

func NewSvc(p NewSvcParams) *Svc {
	return &Svc{
		queries: p.Queries,
		logger:  p.Logger,
	}
}

type Svc struct {
	queries *Queries
	logger  clogger.Logger
}

func (s *Svc) LaunchRocket(ctx context.Context, id int64) (*Launch, error) {
	rocket, err := s.queries.GetRocket(ctx, id)
	if err != nil {
		return nil, cerrors.New(err, "failed to get rocket", map[string]any{
			"id": id,
		})
	}

	if rocket.Fuel < minLaunchFuel {
		return nil, ErrInsufficientFuel
	}

	return s.queries.InsertLaunch(ctx, rocket.ID)
}
```

The layering reads top to bottom: **routers** translate HTTP to and from Go (read the request, call the service, write the response), **services** own the business rules, and **queries** own the SQL. For simple pass-through endpoints, a router may call `Queries` directly; a service earns its place as soon as there are rules to enforce.

<Note>
  If other packages depend on your service, consider defining a `Svc` interface and returning it from `NewSvc`, keeping the implementation unexported. A hand-written mock in a `rocketstest` sibling package then drops in anywhere the interface is used — see [Testing](/digging-deeper/testing).
</Note>

### Utilities

`utils.go` is for pure functions: helpers that take arguments and return results, with no injected dependencies and no state. Anything that needs a logger, a querier, or config belongs on one of the structs instead.

### Wiring It Together

Each constructor is registered in the package's `wire.go`, and the module is added to `pkg/app/wire.go` (the scaffold does this for you):

```go pkg/rockets/wire.go theme={null}
var WireModule = wire.NewSet(
	LoadConfig,
	wire.Struct(new(NewSvcParams), "*"),
	NewSvc,
	NewQueries,
	wire.Struct(new(NewRouterParams), "*"),
	NewRouter,
)
```

To learn how the pieces are provided to each other, see [Dependency Injection](/architecture/dependency-injection).