Documentation
Indroduction

Indroduction

tsdk is a code share and type-safe API development tool for TypeScript projects. With tsdk, developers could easily share code between projects, and develop end-to-end type-safe API that ensure types consistency, reducing potential errors and increasing development efficiency.

Features

  • Type-safe: end-to-end type-safe API development
  • Code share: Easily sharing code between different part of projects
  • Code gen: API call functions, SWR and ReactQuery hooks generate
  • More: based on the fe-sdk/permissions.json we can do more things: check auth, import API permissions...

Motivation

Let's start with the traditional API development process:

  1. the backend to write APIs and the documentation;
  2. front-end then write the code of requesting API according to the documentation. tsdk can help us eliminate the second step.

How to reduce the second step? Let's start with a simple Hello World example.

Hello world

Here's an example of Hello World (opens in a new tab) from expressjs.com (opens in a new tab) to illustrate what an end-to-end type-safe API is and how tsdk basically works.

Code:

const express = require('express');
const app = express();
const port = 3000;
 
app.get('/', (req, res) => {
  res.send('Hello World!');
});
 
app.listen(port, () => {
  console.log(`Example app listening on port ${port}`);
});

Write the API request function

From the hello world API, we know get path /, will get the string result:

function HelloWorld(): Promise<string> {
  return fetch('/').then((res) => res.text());
}

What if we can skip the request code, just like this：

import { HelloWorld } from 'fe-sdk';
 
HelloWorld().then((res) => {
  console.log(res);
});

That's what tsdk means: type-safe API in backend and frontend.

Implement type-safe API by hand

First, we need reorganize our code,

Put the core information of API to HelloWorld.apiconf.ts:

export const HelloWorldConfig = {
  path: '/',
  method: 'get',
};
export type HelloWorldReq = any;
export type HelloWorldRes = string;

Change the original API write according to above configuration (to maintain consistency)：

import express from 'express';
import { HelloWorldConfig, HelloWorldReq, HelloWorldRes } from './HelloWorld.apiconf';
 
const app = express();
const port = 3000;
 
app[HelloWorldConfig.method](HelloWorldConfig.path, (req, res) => {
  const result: HelloWorldRes = 'Hello World!';
  res.send(result);
});
 
app.listen(port, () => {
  console.log(`Example app listening on port ${port}`);
});

Generate the API request code

Now that we know the API request method, request path, request parameter type, and response type, we can generate the API request code as shown below:

import { HelloWorldConfig, HelloWorldReq, HelloWorldRes } from './HelloWorld.apiconf';
 
export function HelloWorld(req: HelloWorldReq): Promise<HelloWorldRes> {
  return fetch(HelloWorldConfig.path, { method: HelloWorldConfig.method }).then((res) =>
    res.text()
  );
}

Summary

How tsdk works is not complicated. Next, we'll write a full hello world example with tsdk, for a quick start.

Quick start