# ts-rs
<h1 align="center" style="padding-top: 0; margin-top: 0;">
<img width="150px" src="https://raw.githubusercontent.com/Aleph-Alpha/ts-rs/main/logo.png" alt="logo">
<br/>
ts-rs
</h1>
<p align="center">
Generate typescript type declarations from rust types
</p>
<div align="center">
<img src="https://img.shields.io/github/actions/workflow/status/Aleph-Alpha/ts-rs/test.yml?branch=main" alt="actions status" />
<a href="https://crates.io/crates/ts-rs">
<img src="https://img.shields.io/crates/v/ts-rs.svg?style=flat-square"
alt="Crates.io version" />
</a>
<a href="https://docs.rs/ts-rs">
<img src="https://img.shields.io/badge/docs-latest-blue.svg?style=flat-square"
alt="docs.rs docs" />
</a>
<a href="https://crates.io/crates/ts-rs">
<img src="https://img.shields.io/crates/d/ts-rs.svg?style=flat-square"
alt="Download" />
</a>
</div>
### 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](https://github.com/Aleph-Alpha/ts-rs/blob/main/example/src/lib.rs) and [the docs](https://docs.rs/ts-rs/latest/ts_rs/).
### Get started
```toml
[dependencies]
ts-rs = "12.0"
```
```rust
#[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`:
```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*:
| `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](https://doc.rust-lang.org/cargo/reference/config.html#env) to make it persistent:
```toml
# <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](https://github.com/rust-lang/rust/issues/54140), which will improve the ergonomics arund these diagnostics.
### Cargo Features
| serde-compat | **Enabled by default** <br/>See the *"serde compatibility"* section below for more information. |
| format | Enables formatting of the generated TypeScript bindings. <br/>Currently, this unfortunately adds quite a few dependencies. |
| no-serde-warnings | By default, warnings are printed during build if unsupported serde attributes are encountered. <br/>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](https://github.com/Aleph-Alpha/ts-rs/blob/main/CONTRIBUTING.md)
### MSRV
The Minimum Supported Rust Version for this crate is 1.88.0
License: MIT