# 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](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 = "9.0"
```
```rust
use ts_rs::TS;
#[derive(TS)]
#[ts(export)]
struct User {
user_id: i32,
first_name: String,
last_name: String,
}
```
When running `cargo test`, the TypeScript bindings will be exported to the file `bindings/User.ts`.
### Features
- generate type declarations from rust structs
- generate union declarations from rust enums
- inline types
- flatten structs/types
- generate necessary imports when exporting to multiple files
- serde compatibility
- generic types
- support for ESM imports
### 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. |
| import-esm | When enabled,`import` statements in the generated file will have the `.js` extension in the end of the path to conform to the ES Modules spec.
Example: `import { MyStruct } from "./my_struct.js"` |
| 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 types from *bson* |
| 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* |
If there's a type you're dealing with which doesn't implement `TS`, use either
`#[ts(as = "..")]` or `#[ts(type = "..")]`, or open a PR.
### `serde` compatability
With the `serde-compat` feature (enabled by default), serde attributes can be parsed for enums and structs.
Supported serde attributes:
- `rename`
- `rename-all`
- `rename-all-fields`
- `tag`
- `content`
- `untagged`
- `skip`
- `flatten`
- `default`
Note: `skip_serializing` and `skip_deserializing` are 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.
### 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.63.0
License: MIT
