ts-rs

ts-rs

Generate typescript type declarations from rust types

Why?

When building a web application in rust, data structures have to be shared between backend and frontend. Using this library, you can easily generate TypeScript bindings to your rust structs & enums so that you can keep your types in one place.

ts-rs might also come in handy when working with webassembly.

How?

ts-rs exposes a single trait, TS. Using a derive macro, you can implement this interface for your types. Then, you can use this trait to obtain the TypeScript bindings. We recommend doing this in your tests. See the example and the docs.

Get started

[dependencies]
ts-rs = "12.0"

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

When running cargo test or cargo test export_bindings, the following TypeScript type will be exported to bindings/User.ts:

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

Features

• generate type declarations from rust structs
• generate union declarations from rust enums
• works with generic types
• compatible with serde
• generate necessary imports when exporting to multiple files
• precise control over generated types

If there's a type you're dealing with which doesn't implement TS, you can use either #[ts(as = "..")] or #[ts(type = "..")], enable the appropriate cargo feature, or open a PR.

Configuration

When using #[ts(export)] on a type, ts-rs generates a test which writes the bindings for it to disk.
The following environment variables may be set to configure how and where:

Variable	Description	Default
TS_RS_EXPORT_DIR	Base directory into which bindings will be exported	./bindings
TS_RS_IMPORT_EXTENSION	File extension used in import statements	none
TS_RS_LARGE_INT	Binding used for large integer types (i64, u64, i128, u128)	bigint

We recommend putting this configuration in the project's config.toml to make it persistent:

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

To export bindings programmatically without the use of tests, TS::export_all, TS::export, and TS::export_to_string can be used instead.

Serde Compatibility

With the serde-compat feature (enabled by default), serde attributes are parsed for enums and structs.
Supported serde attributes: rename, rename-all, rename-all-fields, tag, content, untagged, skip, skip_serializing, skip_serializing_if, flatten, default

Note: skip_serializing and skip_serializing_if only have an effect when used together with #[serde(default)]. This ensures that the generated type is correct for both serialization and deserialization.

Note: skip_deserializing is ignored. If you wish to exclude a field from the generated type, but cannot use #[serde(skip)], use #[ts(skip)] instead.

When ts-rs encounters an unsupported serde attribute, a warning is emitted, unless the feature no-serde-warnings is enabled.
We are currently waiting for #54140, which will improve the ergonomics arund these diagnostics.

Cargo Features

Feature	Description
serde-compat	Enabled by default See the "serde compatibility" section below for more information.
format	Enables formatting of the generated TypeScript bindings. Currently, this unfortunately adds quite a few dependencies.
no-serde-warnings	By default, warnings are printed during build if unsupported serde attributes are encountered. Enabling this feature silences these warnings.
serde-json-impl	Implement TS for types from serde_json
chrono-impl	Implement TS for types from chrono
bigdecimal-impl	Implement TS for types from bigdecimal
url-impl	Implement TS for types from url
uuid-impl	Implement TS for types from uuid
bson-uuid-impl	Implement TS for bson::oid::ObjectId and bson::uuid
bytes-impl	Implement TS for types from bytes
indexmap-impl	Implement TS for types from indexmap
ordered-float-impl	Implement TS for types from ordered_float
heapless-impl	Implement TS for types from heapless
semver-impl	Implement TS for types from semver
smol_str-impl	Implement TS for types from smol_str
tokio-impl	Implement TS for types from tokio
jiff-impl	Implement TS for types from jiff
arrayvec-impl	Implement TS for types from arrayvec

Contributing

Contributions are always welcome! Feel free to open an issue, discuss using GitHub discussions or open a PR. See CONTRIBUTING.md

MSRV

The Minimum Supported Rust Version for this crate is 1.88.0

License: MIT