# Type generation

surrealkit typegen introspects a live database and emits a structured JSON schema document, with optional TypeScript types for the SurrealDB JavaScript SDK.

`surrealkit typegen` introspects a live database and emits a structured description of its schema. JSON is the primary output; TypeScript interfaces for the [SurrealDB JavaScript SDK](/docs/reference/javascript.md) can be generated alongside it.

```bash
surrealkit typegen --user root --pass secret
```

By default this writes a JSON document to `database/types/schema.json`. SurrealKit's internal bookkeeping tables (`__entity`, `__rollout`) are excluded from the output.

## Command flags

| Flag | Default | Description |
|---|---|---|
| `--out <path>` | `{folder}/types/schema.json` | Write the JSON to a specific path |
| `--stdout` | off | Print the JSON to stdout instead of writing a file |
| `--compact` | off | Emit compact, single-line JSON instead of pretty-printed |

```bash
# Pretty-printed JSON to the default location
surrealkit typegen --user root --pass secret

# Pipe compact JSON into another tool
surrealkit typegen --stdout --compact --user root --pass secret
```

The JSON document includes the namespace, database, generation timestamp, and a typed description of every table, field, and function in the schema.

## TypeScript output

TypeScript generation is opt-in through the `[typegen]` section of `surrealkit.toml`. Set `typescript` to the directory where the generated `index.ts` should be written:

```toml
[typegen]
typescript = "./src/types"
format = "biome check --write"
```

| Key | Description |
|---|---|
| `typescript` | Directory for the generated `index.ts`. Setting it enables TypeScript output for `typegen` and `sync --watch`. |
| `format` | Optional formatter command run on the generated file after writing (for example `biome check --write`, `prettier --write`, or `eslint --fix`). |

With `typescript` configured, `surrealkit typegen` writes both the JSON document and an `index.ts`:

```ts
// Generated by SurrealKit - do not edit.
// Run `surrealkit typegen` to regenerate.

import type { RecordId } from 'surrealdb';

export interface User {
  id: RecordId<'user'>;
  name: string;
  email: string;
}
```

The emitter targets the SurrealDB JavaScript SDK (v2): one interface per table, every record carrying a typed `id: RecordId<'table'>`, with schema field types mapped to the SDK's wrapper types.

### Formatter

When `format` is set, SurrealKit appends the generated file path to the command and runs it, so the output matches your project's house style. The command inherits the working directory so the formatter discovers your project's own config. Formatter failures (a missing binary or a non-zero exit) are reported as warnings and never fail `typegen` or `sync --watch`.

## Regenerating on sync

When `[typegen] typescript` is configured, `surrealkit sync --watch` regenerates the TypeScript types whenever the schema changes, so your types stay current with the schema during local development:

```bash
surrealkit sync --watch --user root --pass secret
```

Regeneration is gated on actual schema changes (or a missing output file), so idle watch ticks do not re-introspect the database.

## Library API

Type generation is also available from the [`surrealkit::typegen`](/docs/manage/schema-migration/library.md) module when embedding SurrealKit in Rust:

```rust
use surrealkit::typegen::{generate, render_typescript, write_typescript};
use surrealkit::Surreal;
use surrealkit::engine::any::Any;

async fn run(db: &Surreal<Any>) -> anyhow::Result<()> {
    // Introspect the database into a structured document (no filesystem IO).
    let doc = generate(db).await?;

    // Render TypeScript as a string …
    let ts = render_typescript(&doc)?;
    println!("{ts}");

    // … or write it to `<dir>/index.ts`.
    write_typescript(&doc, std::path::Path::new("src/types"))?;
    Ok(())
}
```

`generate` returns a `SchemaTypes` document that the JSON and TypeScript emitters share, so a single introspection can produce both formats. `write_typescript_formatted` writes the file and runs an optional formatter command in the same call.

## Next steps

- [Sync](/docs/manage/schema-migration/sync.md): keep the database aligned with your schema files
- [Using SurrealKit as a library](/docs/manage/schema-migration/library.md): drive SurrealKit from Rust
</content>