Skip to content

Deriving the TS trait

Jump to bottom
escritorio-gustavo edited this page Feb 8, 2024 · 26 revisions

#[derive(TS)]

The TS trait can be easily derived through its #[derive(TS)] macro, which will automatically handle mapping a Rust type into TypeScript type definitions.

The #[derive(TS)] macro provides an attribute helper macro called #[ts(...)] which can help you control how the types will be generated

#[ts(...)] attributes

Container attributes

These are attributes that can be used both with structs and enums

#[ts(export)]

This attribute causes the generation of a test which will create a ts file containing the TypeScript declaration for your type, as well as any types it depends on (as long as they implement TS)

#[ts(export_to = "...")]

Allows you to change where your TypeScript file will be generated (default is ./bindings/TypeName.ts).

Usage:

#[derive(ts_rs::TS)]
#[ts(export)]
struct MyStruct {
    foo: String
}

This must be either:

  • An absolute path
  • A path relative to your crate's Cargo.toml

The given path will be treated as a directory if it ends with a / character, in which case a file called TypeName.ts will be created within the given directory, otherwise the path will be treated as a file (even without an extension).

Usage:

#[derive(ts_rs::TS)]
#[ts(export, export_to = "../ts_project/bindings/")] // Note that #[ts(export)] is still required
struct MyStruct {
    foo: String
}

#[ts(rename = "...")]

Changes the name of your type's TypeScript representation.

If the feature flag serde-compat is enabled (default), using #[serde(rename = "...")] will have the same effect.

Usage:

#[derive(ts_rs::TS)]
#[ts(export, rename = "MyType")]
struct MyStruct {
    foo: String
}

Generates:

export type MyType = { foo: string, }

#[ts(rename_all = "...")]

Renames all the fields in your struct or variants in your enum to use a given inflection.

Accepted values are lowercase, snake_case, kebab-case, UPPERCASE, camelCase, PascalCase and SCREAMING_SNAKE_CASE.

If the feature flag serde-compat is enabled (default), using #[serde(rename_all = "...")] will have the same effect.

Usage:

#[derive(ts_rs::TS)]
#[ts(export, rename_all = "camelCase")]
struct MyStruct {
    foo_bar: String
}

Generates:

export type MyStruct = { fooBar: string, }

Struct field attributes

#[ts(inline)]

#[ts(flatten)]

#[ts(as = "...")]

#[ts(type = "...")]

#[ts(optional)]

#[ts(optional = nullable)]

#[ts(skip)]

#[ts(rename = "...")]

Enum attibutes

#[ts(rename_all_fields)]

Equivalent to adding #[ts(rename_all = "..."] to every variant.

Accepted values are lowercase, snake_case, kebab-case, UPPERCASE, camelCase, PascalCase and SCREAMING_SNAKE_CASE.

#[ts(tag = "...")]

#[ts(tag = "...", content = "...")]

#[ts(untagged)]

Enum variant attributes

#[ts(inline)]

#[ts(skip)]

#[ts(rename = "...")]

#[ts(rename_all = "...")]

Clone this wiki locally