ts-rs

With the serde-compat feature (enabled by default), ts-rs respects many serde attributes to ensure your TypeScript types match your serialized data.

Supported attributes:

• rename, rename-all, rename-all-fields
• tag, content, untagged (for enums)
• skip, skip_serializing, skip_serializing_if, flatten, default

Important Notes:

• skip_serializing and skip_serializing_if only work correctly if used with #[serde(default)] to ensure the generated type is valid for both serialization and deserialization.
• skip_deserializing is ignored.
• If you want to exclude a field from the TypeScript type but cannot use #[serde(skip)], use #[ts(skip)] instead.

Add ts-rs to your Cargo.toml dependencies to start generating TypeScript type declarations from your Rust structs and enums.

[dependencies]
ts-rs = "12.0"

You can fine-tune how individual fields in a struct are represented in TypeScript:

• #[ts(type = "...")]: Overrides the TypeScript type used for this field.
• #[ts(as = "...")]: Overrides the type used in TypeScript, often used with custom serializers (e.g., #[ts(as = "Option<_>")]).
• #[ts(rename = "...")]: Renames the field in the generated TypeScript object.
• #[ts(inline)]: Inlines the type definition instead of using a named type.
• #[ts(skip)]: Omits this field from the generated TypeScript type.
• #[ts(flatten)]: Flattens the field, inlining all its keys into the parent object.
• #[ts(optional)]: Changes Option<T> from t: T | null to t?: T.
• #[ts(optional = "nullable")]: Changes Option<T> to t?: T | null.
• #[ts(optional = false)]: Overrides a struct-level #[ts(optional_fields)] setting for this specific field.

If the serde-compat feature is enabled, ts-rs will automatically merge certain #[serde] attributes into the TypeScript generation logic. This allows you to control TypeScript output using familiar Serde patterns.

Supported #[serde] attributes that affect ts-rs:

• #[serde(rename = "...")]: Affects field/type renaming.
• #[serde(rename_all = "...")]: Affects field naming conventions.
• #[serde(tag = "...")]: Affects how tags are handled.
• #[serde(bound = "...")]: Affects trait bounds.

Note: #[serde(default)], #[serde(deny_unknown_fields)], and #[serde(crate = "...")] are recognized to prevent warnings but do not change the TypeScript output directly.

# <project-root>/.cargo/config.toml
[env]
TS_RS_EXPORT_DIR = { value = "bindings", relative = true }
TS_RS_LARGE_INT = "number"

Control how specific variants of an enum are represented:

• #[ts(rename = "...")]: Renames the variant.
• #[ts(skip)]: Omits the variant from the generated TypeScript type.
• #[ts(untagged)]: Treats the variant as untagged, regardless of the enum's global tag/content settings.
• #[ts(rename_all = "...")]: Renames all fields within a struct variant.

By default, ts-rs maps large integer types (i64, u64, i128, u128) to the TypeScript bigint type. You can change this behavior using the TS_RS_LARGE_INT environment variable or the Config::with_large_int method.

This is useful if your frontend environment does not support bigint and you prefer using number (though note that precision may be lost for values exceeding $2^{53}-1$).

The core of ts-rs is the TS trait. You can implement this trait for your Rust types using the #[derive(TS)] macro. This allows you to generate TypeScript type declarations that match your Rust data structures.

Automatic Exporting via Tests

Because Rust procedural macros run before compilation, ts-rs cannot export files during the normal build process. Instead, it generates a test that writes the bindings to disk when you run cargo test.

To trigger an automatic export, add the #[ts(export)] attribute to your type:

#[derive(ts_rs::TS)]
#[ts(export)]
struct User {
    user_id: i32,
    first_name: String,
    last_name: String,
}

When you run cargo test, the following TypeScript type will be exported to ./bindings/User.ts (by default):

export type User = { user_id: number, first_name: string, last_name: string, };

To export a type, derive the ts_rs::TS trait and use the #[ts(export)] attribute. When you run cargo test or cargo test export_bindings, ts-rs will automatically generate the corresponding TypeScript file in your configured export directory.

Example:

#[derive(ts_rs::TS)]
#[ts(export)]
struct User {
    user_id: i32,
    first_name: String,
    last_name: String,
}

This will produce a file (e.g., bindings/User.ts) containing:

export type User = { user_id: number, first_name: string, last_name: string, };

If you do not want to rely on running tests to generate your files, you can use the TS trait methods to export bindings manually in your code:

• TS::export_all()
• TS::export()
• TS::export_to_string()