> ## Documentation Index
> Fetch the complete documentation index at: https://repost.sh/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Go Code Generation

> Configure Go output, understand the generated package, regenerate safely, and keep generated descriptors compatible with the runtime.

The Go generator writes a complete package into your repository. Your schema owns its public models and method tree. `github.com/repost-sh/repost-go` owns send behavior, which keeps generated code small and reviewable.

## Configure the output

```jssm repost/schema.repost theme={"languages":{"custom":["/languages/repost.json"]}}
generator sdk {
  language = "go"
  output   = "../internal/repostclient"
}
```

`output` is required and resolves relative to the schema file. Generated files always declare `package repostclient`; the directory controls the import path. Give every generator its own output directory.

The output directory is engine-owned. Do not hand-edit generated files or place application code in that directory. Generation stages the complete package and replaces it as one unit. It refuses to overwrite an unrecognized non-empty directory.

## What gets emitted

| File                  | Purpose                                                                                             |
| --------------------- | --------------------------------------------------------------------------------------------------- |
| `types.go`            | Model structs, enum types, and enum constants.                                                      |
| `descriptors.go`      | Field order, wire names, defaults, enum mappings, and event bindings consumed by the runtime.       |
| `client.go`           | `Client`, `NewClient`, `Diagnostics`, `Close`, typed input structs, and the `Webhooks` method tree. |
| `schema.repost`       | The merged schema text used for this generation.                                                    |
| `schemas.json`        | JSON Schema catalog for the event versions in the migration lineage.                                |
| `.repost-client.json` | Managed-output marker with the generator identity, schema hash, file list, and content hashes.      |

Commit the whole directory with the schema migration that produced it. A generated package does not contain a separate HTTP implementation. Every typed method delegates to the shared Go runtime.

## Generated models and methods

For this schema:

```jssm theme={"languages":{"custom":["/languages/repost.json"]}}
model Order {
  id       String
  nickname String?
}

type Order {
  created
}
```

the package exports `Order`, `OrderCreatedInput`, and `client.Webhooks.Order.Created(ctx, input)`. Every input has `CustomerID`, typed `Data`, and an optional `IdempotencyKey`.

Optional fields use `repost.Optional[T]`, which preserves the difference between omission, a value, and JSON null:

```go theme={"languages":{"custom":["/languages/repost.json"]}}
order := repostclient.Order{
    ID:       "order_1001",
    Nickname: repost.Present("priority"),
}

order.Nickname = repost.Absent[string]() // omit, or apply a schema default
order.Nickname = repost.Null[string]()   // send null when the schema permits it
```

The zero value of `Optional[T]` is absent. Payload keys follow schema declaration order and use their `@map` wire names. Unknown struct fields are not part of generated models and cannot enter the payload.

## Regenerate and check drift

<CodeGroup>
  ```bash Record a migration and generate theme={"languages":{"custom":["/languages/repost.json"]}}
  repost schema migrate dev --name add_order_nickname
  ```

  ```bash Regenerate without a migration theme={"languages":{"custom":["/languages/repost.json"]}}
  repost schema generate
  ```

  ```bash Verify committed output theme={"languages":{"custom":["/languages/repost.json"]}}
  repost schema migrate status
  repost schema generate --check
  ```
</CodeGroup>

`migrate dev` records a schema change and regenerates every configured language. `generate --check` writes nothing and exits non-zero when committed output differs from current generation. Use both status and generation checks in CI.

In a monorepo, one schema can contain several generators. A single CLI run stages every output before replacing any of them. See [Polyglot monorepos](/docs/send/monorepos) for ownership and commit rules.

## Runtime compatibility

`NewClient` validates the generated descriptor format before constructing the runtime. If generated code is older than the runtime expects, regenerate with the current CLI. If generated code is newer, upgrade `github.com/repost-sh/repost-go`. A mismatch fails during construction, before any send can start.

Regenerate the full package after upgrading the schema engine. Do not copy an older generated client forward or patch descriptor constants by hand.

## Continue

<Columns cols={3} className="gap-y-4">
  <Card title="Configuration" icon="sliders-horizontal" href="/docs/send/go/configuration" cta="Configure" arrow="true">
    Configure the runtime created by the generated client.
  </Card>

  <Card title="Testing" icon="flask-conical" href="/docs/send/go/testing" cta="Test" arrow="true">
    Exercise generated methods with deterministic Go helpers.
  </Card>

  <Card title="Migrations & deploys" icon="git-branch" href="/docs/send/deployments" cta="Version" arrow="true">
    Version and deploy the schema that drives generation.
  </Card>
</Columns>