Generate, Package, and Publish - A TypeScript API Client for NestJS

Leveraging Swagger and OpenAPI to Generate a TypeScript Client for NestJS

Whether you’re developing a frontend application, a microservice, or a third-party integration, a well-structured TypeScript API client ensures type-safe, consistent, and efficient communication with your API.

Manually building an API client can be tedious and error-prone, which is why more projects are adopting auto-generated API clients for improved reliability and efficiency.

This tutorial will guide you through creating a TypeScript API client for a NestJS server. The process consists of three main steps:

• Generate an OpenAPI JSON file using the Swagger module in a NestJS app.
• Create TypeScript client files with the swagger-typescript-api library.
• Package and publish the client as an npm module.

By the end, you’ll have a reusable TypeScript API client that can be easily shared and integrated into frontend applications or other services.

Generate OpenAPI JSON File Using Swagger in NestJS

First, install the @nestjs/swagger package in your NestJS project:

1

npm install @nestjs/swagger

In your main.ts file, configure Swagger to generate OpenAPI documentation:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21

import { NestFactory } from '@nestjs/core';
import { SwaggerModule, DocumentBuilder } from '@nestjs/swagger';
import { AppModule } from './app.module';

async function bootstrap() {
  const app = await NestFactory.create(AppModule);

  // Configure Swagger
  const config = new DocumentBuilder()
    .setTitle('Real Estate API')
    .setDescription('API for managing real estate clients')
    .setVersion('1.0')
    .addTag('clients')
    .build();

  const document = SwaggerModule.createDocument(app, config);
  SwaggerModule.setup('api', app, document);

  await app.listen(3000);
}
bootstrap();

After starting the NestJS app, visit http://localhost:3000/api-json in your browser or use a tool like curl to download the OpenAPI JSON file:

1

curl http://localhost:3000/api-json -o openapi.json

If you want to auto-generate and save the JSON file every time starting the API, then add the following lines into the bootstrap method:

1
2

const document = SwaggerModule.createDocument(app, config);
fs.writeFileSync("./swagger-spec.json", JSON.stringify(document));  

The OpenAPI specification will be used in the following steps to generate the client.

Generate TypeScript Client Files

There are several tools available for generating a TypeScript API client from an OpenAPI specification, such as:

• OpenAPI Generator
• NSwag
• swagger-codegen
  Here, we choose swagger-typescript-api because it is light-weight, simple, easy to use, and being actively maintained.

First step is to install the swagger-typescript-api library globally :

1

npm install -g swagger-typescript-api

Then, run the following command to generate TypeScript client files from the openapi JSON file from step 1.

1

swagger-typescript-api -p ./openapi.json -o ./output -modular

• -p: Path to the OpenAPI JSON file.
• -o: Output directory for the generated files.
• -modular: Generate separated files for http client, data contracts.

Note that you can replace -modular with -n option to specify the name of generated API client file, and make all the output into a single file. I prefer to have separated files, which is easier to navigate.

The generated file will include TypeScript types and methods for interacting with your NestJS API. For example:

1
2
3
4
5
6
7
8
9
10
11
12
13

import { HttpClient } from './http-client';

export class RealEstateApi {
  constructor(private http: HttpClient) {}

  async getClients() {
    return this.http.get('/clients');
  }

  async addClient(client: ClientDto) {
    return this.http.post('/clients', client);
  }
}

Now, we have the API client files generated, they can be packaged and published as an npm package.

Package and Publish the Client as an npm Package

Publishing the API client as an npm package makes the client easier to be shared between multiple front-end projects, and we can manage the client versions better.

Firstly, we need to initialize it as an npm package.

1
2

npm init -y
npm install axios // install the dependencies for the client

Update the package.json file to include basic metadata.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

{
  "name": "real-estate-client",
  "version": "1.0.0",
  "description": "TypeScript client for Real Estate API",
  "main": "client.ts",
  "scripts": {
    "build": "tsc"
  },
  "dependencies": {
    "axios": "^1.5.0"
  },
  "devDependencies": {
    "typescript": "^5.0.0"
  }
}

The next step is to add the TypeScript configuration file tsconfig.json.

1
2
3
4
5
6
7
8
9
10

{
  "compilerOptions": {
    "target": "ES6",
    "module": "CommonJS",
    "outDir": "./dist",
    "strict": true,
    "esModuleInterop": true
  },
  "include": ["**/*.ts"]
}

Now, we can build and publish the package.

1
2
3

npm run build
npm login // login to npm
npm publish // publish the package

Now, we should have a published npm package containing the generated API client, and it can be used in any JavaScript-based front-end Apps!

Summary

In the article, we walk through the steps to generate an OpenAPI JSON file from a NestJS app, then use it for generating the TypeScript client, and finally package and publish the client as an npm package.

We can easily integrate these steps into a CI pipeline to ensure that your API client stays in sync with your backend API and can be easily shared across projects.

I hope you find this article useful. Happy coding!