Hi, today I'll introduce you to a library called ts-rest. A library that supports API organization while integrating with the typesafe API. ## What is TS-Rest ? In short, TS-Rest is a library help you define your API and give you an end to end safe API. In addition, TS-Rest can help you define API normally (you can define Put, Patch, Delete, Get, Post Method). If you work with a Third Party API. TS-Rest is a good choice to leverages TypeScript's type system to provide strong typing for API endpoints, request/response payloads, and data models. This ensures that you're working with the correct data types and minimizes the risk of runtime errors due to incorrect data handling. ## How to use TS-Rest ? In this part, I will be creating a simple Todo app to introduce TS-Rest on the client side. In this project, I will use CRA for initilizing my React app. These are libraries I will use in this project : - React Query - @ts-rest/core for creating contract,router - @ts-rest/react-query So let's get started 🚀 **Installation** Before we're going to project please make sure you have installed @ts-rest library and react-query library. `yarn add @ts-rest/react-query @tanstack/react-query @ts-rest/core` **Setup fake API server** In this project I will use json-server for creating fake API server. Steps: 1. Install json-server : `yarn add json-server` 2. Next create a db.json in your project ``` { "data": [ { "title": "Todo 1", "id": 1 }, { "title": "todo 2", "id": 2 } ] } ``` 3. In `package.json` add this script: ``` scripts : { ..... "server": "json-server --watch db.json --port 5000" ..... } ``` So let's run `yarn server`. This will start out server in this project. **Setup ts-rest router** First create `src/constants/index.ts` for defining some API Route and Server URL. ``` src/constants/index.ts export const SERVER_URL = 'http://localhost:5000/data'; export const API_ROUTE = { GET: '/', CREATE: '/', UPDATE: '/:id', DELETE: '/:id', }; ``` Next, create `lib/ts-rest` folder in your src directory. Inside that we will create two file : ``` //lib/ts-rest/router.ts import { initContract } from '@ts-rest/core'; import { API_ROUTE } from '../../constants'; import { z } from 'zod'; const c = initContract(); export const router = c.router({ getAllTodo: { method: 'GET', path: API_ROUTE.GET, responses: { 200: z.array( z.object({ id: z.number(), title: z.string(), }), ), }, }, createTodo: { method: 'POST', path: API_ROUTE.CREATE, responses: { 201: z.object({ id: z.number(), title: z.string(), }), }, body: z.object({ title: z.string(), }), }, updateTodo: { method: 'PATCH', path: API_ROUTE.UPDATE, responses: { 204: z.object({ id: z.number(), title: z.string(), }), }, pathParams: z.object({ id: z.number() }).required(), body: z.object({ title: z.string(), }), }, deleteTodo: { method: 'DELETE', path: API_ROUTE.DELETE, responses: { 200: z.object({ id: z.number(), title: z.string(), }), }, pathParams: z.object({ id: z.number() }).required(), body: z.undefined(), }, }); ``` This code is simply the define route of API. For each property in router we have : - method : Definition of that API's method - path : Definition of that API's path - reponses : Definition of that API's return data type (for example : in getAllTodo's response when fetch data success. It's will return an array have type `{id:number;title:string}[]`. - pathParams : Definition of that API's path param type. If that API Route uses path params, you must define this. For example in `deleteTodo`'s path I have declared the path is `/:id`. So I need create a pathParams like this `z.object({ id: z.number() }).required()`. (If you define your path like this : `/:idPost` your pathParams must be `z.object({ idPost: z.number() }).required()` - body : Definition of that API's body type. Finally in `lib/ts-rest/client-provider` ,let create a clientProvider to query and mutate data from server. ``` import { initQueryClient } from '@ts-rest/react-query'; import { router } from './router'; import { SERVER_URL } from '../../constants/'; export const clientProvider = initQueryClient(router, { baseUrl: SERVER_URL, baseHeaders: {}, }); ``` If you want custom your api (override). You can use `api` property in initQueryClient's options. Please refer [here](https://ts-rest.com/docs/core/custom) So that's all. We have configured our TS-Rest client provider completely. **Setup react-query and create some component** First in `App.tsx` let's setup `react-query` provider. ``` import { QueryClient, QueryClientProvider } from '@tanstack/react-query'; import { Toaster } from 'react-hot-toast'; const queryClient = new QueryClient() export const App = () => { return (

); }; ``` Let's create `TodoList,InputTodo` component ``` src/components/TodoList.tsx import { clientProvider } from "../lib/ts-rest/client-provider" import TodoItem from "./TodoItem" const TodoList = () => { const { data, isLoading, } = clientProvider.getAllTodo.useQuery(['GET_ALL_TODO']) return ( isLoading ?

{data?.body.map(todoItem => )}

) } export default TodoList ``` ``` src/components/TodoList.tsx import { clientProvider } from "../lib/ts-rest/client-provider" import TodoItem from "./TodoItem" const TodoList = () => { const { data, isLoading, } = clientProvider.getAllTodo.useQuery(['GET_ALL_TODO']) return ( isLoading ?

{data?.body.map(todoItem => )}

) } export default TodoList ``` In `TodoList` component we have use clientProvider to query the data from server. Thanks to Ts-Rest, every time call clientProvider.getAllTodo you will ensure the Safe API, making it easier for maintaining and debugging. ``` src/components/TodoItem.tsx const TodoItem = ({ id, title }: { id: number, title: string }) => { const { mutateAsync } = clientProvider.deleteTodo.useMutation(); const queryClient = useQueryClient() const onDelete = async () => { try { await mutateAsync({ params: { id } }) queryClient.invalidateQueries({ queryKey: ['GET_ALL_TODO'] }) toast.success("Delete success") } catch (error) { toast.error(JSON.stringify(error)) } } return (

{title}

) } ``` Also this is an example of using useMutation with TS-Rest. It helps you control the type of pathParams input. Finally let's create a `InputTodo` component. ``` const InputTodo = () => { const inputRef = useRef(null); const { mutateAsync } = clientProvider.createTodo.useMutation() const queryClient = useQueryClient() const onAddTodo = async () => { try { if (inputRef.current) { await mutateAsync({ body: { title: inputRef.current?.value } }) toast.success('Add todo success'); queryClient.invalidateQueries({ queryKey: ['GET_ALL_TODO'] }) } } catch (error) { toast(JSON.stringify(error)) } } return (

) } export default InputTodo ``` In addition to `pathParams` TS-Rest can also type safe for body input. So's that all 🙏 about demo project. ## Summary TS-Rest is great in helping you manage your API Design and easy to maintain. However, it still has some points I am not satisfied with Ts-Rest. - It is still a library being developed so the community is not much. - Document has not been written clearly (this is my opinion). - Currently, it is still not used with React-Query V5. So I hope they will update in the next time. Thanks for reading. 👏 Repo link : https://github.com/quangnmwork/ts-rest-tutorial

quangnmwork

Typesafe API with TS-Rest, React Query

Join Our Newsletter. No Spam, Only the good stuff.