⚡ NestSync

The Type-Safe Bridge for NestJS Monorepos.

NestSync is a compiler-tier developer tool that automatically generates fully typed, production-ready frontend SDKs directly from your NestJS controllers and DTOs.

By leveraging deep Static Analysis (AST), NestSync completely eliminates API contract drift without requiring you to run your NestJS server or rely on clunky OpenAPI/Swagger YAML files.

✨ Features

• Zero-Runtime Overhead: Parses TypeScript AST (ts-morph) directly. No need to boot your backend to generate the client.
• End-to-End Type Safety: Shares exact types, DTOs, and interfaces between backend and frontend.
• Smart JSDoc Extraction: Backend comments on DTOs are automatically carried over to the frontend interfaces for flawless developer experience (DX).
• Pluggable Architecture: Generate SDKs for native fetch, axios, or even React Query custom hooks.
• Lightning Fast Watch Mode: Recompiles your SDK in milliseconds when a backend controller or DTO changes.
• Monorepo Ready: Designed from the ground up to work seamlessly in pnpm, Turborepo, and Nx workspaces.

---

📊 Performance Benchmark (Real-World Test)

In a stress test simulating a large-scale enterprise application (50 Modules and 100+ DTOs), NestSync significantly outperformed traditional OpenAPI-based workflows by eliminating the runtime overhead.

Metric	Swagger/OpenAPI Flow	NestSync (AST)
Generation Time	9.17s	1.73s
Requirements	Running Server + Complex Config	Source Code Only
Process	Boot + JSON Export + Generation	Direct Static Analysis

Tip

Result: NestSync is 5.3x faster than traditional methods. Since it doesn't require a running backend, it's perfect for CI/CD pipelines and fast local development loops.

---

🚀 Quick Start

1. Installation

Install NestSync globally or as a dev dependency in your workspace:

npm install -g @nestsync/cli
# or
pnpm add -D @nestsync/cli

2. Generate your SDK

Run the CLI, pointing to your NestJS source folder and specifying the output path for your frontend:

npx nestsync --input ./apps/backend/src --output ./apps/frontend/src/api/sdk.gen.ts --client=fetch

3. Watch Mode (Development)

Keep the generated SDK perfectly synced with your backend in real-time:

npx nestsync -i ./src -o ../client/sdk.gen.ts --client=react-query --watch

---

🛠 Supported Clients (Plugins)

NestSync uses a strict Strategy Pattern to emit code. You can choose your target transport layer using the --client flag:

Client Flag	Output	Best For
--client=fetch	Native Fetch	APIEdge runtimes, Next.js App Router, modern web.
--client=axios	Axios Client	Legacy enterprise apps, complex interceptors.
--client=react-query	TanStack Query Hooks	React SPA/SSR apps requiring advanced caching.

---

📖 Usage Example

The Backend (NestJS)

You write your standard NestJS code with decorators and JSDoc:

import { Controller, Get, Post, Body, Param } from '@nestjs/common';
import { CreateUserDto } from './users.dto';

@Controller('users')
export class UsersController {
  @Post(':id')
  updateUser(@Param('id') id: string, @Body() data: CreateUserDto): Promise<CreateUserDto> {
    // ...
  }
}

The Frontend Setup (React/Next.js)

NestSync generates a setNestSyncConfig function so you can inject your Base URL and Auth Tokens globally at application boot.

import { setNestSyncConfig } from './api/sdk.gen';

// Setup once in your App.tsx or main.ts
setNestSyncConfig({
  baseUrl: '[https://api.drewtech.com.br/v1](https://api.drewtech.com.br/v1)',
  getToken: async () => localStorage.getItem('access_token'),
});

The Frontend Usage (React Query Example)

If you used --client=react-query, you get perfectly typed, ready-to-use hooks:

import { useUpdateUserMutation } from './api/sdk.gen';

function UserProfile() {
  const mutation = useUpdateUserMutation();

  const handleSave = () => {
    // Fully type-safe! Requires both 'id' and 'data'
    mutation.mutate({
      id: '123',
      data: { name: 'Andrew', email: 'andrew@example.com' }
    });
  };

  return <button onClick={handleSave}>Save</button>;
}

---

🏗 Architecture

NestSync operates as a modern 3-stage compiler pipeline:

1. Analyzer: Crawls the NestJS AST to resolve decorators and follow DTO imports recursively.
2. Intermediate Representation (IR): Transforms the AST into a clean, framework-agnostic JSON schema.
3. Emitter: Consumes the IR and passes it to the selected Transport Plugin to generate TypeScript strings.

---

🤝 Contributing

We welcome contributions! The repository is managed as a pnpm workspace.

1. Clone the repository.
2. Run pnpm install at the root.
3. Run pnpm run build to compile the packages.
4. Run pnpm run test to execute the Vitest AST snapshot tests.Ensure pnpm run lint passes before submitting a Pull Request.

📄 License

MIT © Andrew Souza