Skip to main content

Introduction

Apinni is a TypeScript library for building type-safe APIs with decorators. It automatically generates TypeScript definitions from your backend code, ensuring type safety between your API and clients.

What is Apinni?​

Apinni bridges the gap between your backend and frontend by:

  1. Scanning your TypeScript controllers decorated with @ApinniController and @ApinniEndpoint
  2. Analyzing the types used in your endpoints
  3. Generating type-safe definitions that can be imported in your frontend

This means your API contracts are always in sync, catching errors at compile-time rather than runtime.

// Backend: Define your API
@ApinniController({ path: '/api/users' })
class UserController {
  @ApinniEndpoint({ path: '/:id', method: 'GET' })
  async getUserById(): Promise<User> {
    return { id: '123', name: 'Alice', email: 'alice@example.com' };
  }
}

// Frontend: Use generated types
import type { ApiRequest, ApiResponsesByStatus } from './api-types';

type UserResponse = ApiResponsesByStatus<'/api/users/:id', 'GET', '200'>;
// Type: { id: string; name: string; email: string }

Why Apinni?​

End-to-End Type Safety​

No more manual type definitions or API documentation that goes out of sync. Changes in your backend are immediately reflected in your frontend types.

Framework Agnostic​

Works with any TypeScript backend framework (Express, NestJS, Fastify, Hono) and any frontend framework (React, Vue, Angular, Svelte).

Developer Experience First​

Built-in CLI with watch mode, comprehensive utility types, and plugin system for extensibility. Designed to feel natural in your existing workflow.

Extensible Plugin System​

Create custom plugins to extend functionality, integrate with tools like Swagger, or add your own decorators and metadata.

How It Works​

Apinni operates in three phases:

  1. Compilation Phase: Compiles your TypeScript code and extracts decorator metadata
  2. Analysis Phase: Processes decorators and builds a schema of your API structure
  3. Generation Phase: Outputs type definition files with utility types for consumption
info

The generated types include not just your request/response shapes, but also utility types for path building, query parameters, and status-specific responses.

Use Cases​

Apinni is perfect for:

  • Full-stack TypeScript applications where you want type safety across the stack
  • Monorepo projects sharing types between backend and frontend packages
  • API-first development where contracts are defined before implementation
  • Teams wanting to reduce API-related bugs and improve collaboration
  • Migration projects gradually adding type safety to existing APIs

Next Steps​

Ready to get started? Follow our step-by-step guide:

  • Installation - Install Apinni and configure your project
  • Decorators - Learn about the core decorators
  • CLI - Understand the CLI commands and options
  • Guides - Integrate with your backend framework