Getting Started with Apinni

The apinni package enables type-safe API generation for TypeScript projects, integrating with decorators like @ApinniController, @ApinniEndpoint, @ApinniDomain, and @ApinniDisabled. This guide covers the prerequisites, installation, setup, and running of apinni in your project, along with configuration options and troubleshooting tips.

What is Apinni?

Apinni is a powerful tool for generating type definitions from TypeScript controllers and endpoints, ensuring type safety and streamlined API development. It’s ideal for projects requiring robust API documentation and client-side type integration.

Prerequisites

Before installing apinni, ensure your project meets the following requirements:

Requirement	Version/Description
Node.js	>= 18 (LTS recommended for stability)
TypeScript	>= 4.5 (with a valid tsconfig.json)
Package Manager	npm, Yarn, or pnpm
Project Setup	A TypeScript project with decorators enabled (experimentalDecorators and emitDecoratorMetadata in tsconfig.json)

Configuring tsconfig.json

Ensure your tsconfig.json includes the following settings to support Apinni’s decorator-based workflow:

tsconfig.json

{
  "compilerOptions": {
    ...
    "experimentalDecorators": true,
    "emitDecoratorMetadata": true,
    "outDir": "./dist",
    "rootDir": "./src",
    ...
  }
}

warning

Apinni relies on TypeScript decorators. Omitting experimentalDecorators or emitDecoratorMetadata in tsconfig.json can cause type generation to fail.

Installation

Install apinni as a development dependency using your preferred package manager.

npm

npm install @apinni/client-ts --save-dev

Yarn

yarn add -D @apinni/client-ts

pnpm

pnpm add -D @apinni/client-ts

tip

Installing apinni as a dev dependency (--save-dev, -D) is recommended, as it’s typically used during development for type generation.

Setup

To integrate apinni into your project, add a script to your package.json to run the type generation command.

Step 1: Add apinni Script

Modify your package.json to include a apinni script:

package.json

{
  "scripts": {
    "apinni": "apinni"
  }
}

Step 2: Create a Controller

Create a basic controller using Apinni decorators to test the setup. For example:

src/controllers/user.controller.ts

import { ApinniController, ApinniEndpoint } from '@apinni/client-ts';

@ApinniController({ path: '/api/users' })
class UserController {
  @ApinniEndpoint({ path: '/:id', method: 'GET' })
  getUserById() {
    return { id: '123', name: 'Alice' };
  }
}

Step 3: Run Apinni

Run the apinni generate command to generate type definitions:

npm

npm run apinni generate

Yarn

yarn apinni generate

pnpm

pnpm run apinni generate

This generates type definition files (e.g., api-types.d.ts) in your project’s output directory, based on your controllers and endpoints.

export type GetApiUsersByIdResponse = {
    id: string;
    name: string;
};

export type BuildApi<T extends IApi> = T;

export type Api = {
    ['/api/users/:id']: {
        GET: {
            request: never;
            responses: {
                200: GetApiUsersByIdResponse;
            };
        };
    };
}

example

Output: After running apinni generate, a file like api-types.d.ts will be generated, containing type definitions for the /api/users/:id endpoint and other utility types.

Configuration Options

CommonJS

Create a apinni.config.cjs file in your project root:

module.exports = {
    outputPath: "./types",
    plugins: [], // Your plugins here
}

ESM

Create a apinni.config.js(or mjs) file in your project root:

export default {
    outputPath: "./types",
    plugins: [], // Your plugins here
}

Typescript

Create a apinni.config.ts file in your project root:

import type { ApinniConfig } from "@apinni/client-ts";

export default {
    outputPath: "./types",
    plugins: [], // Your plugins here
} satisfies ApinniConfig

Property	Type	Description
outputPath	string	Directory for generated type files (e.g., ./types).
include	string[]	Glob patterns for files to process (e.g., ["src/controllers/**/*.ts"]).
plugins	PluginTypes[]	List plugins which will affect generation logic.

Try It Out

Experiment with a sample Apinni project in a live TypeScript environment: CodeSandbox Link.

Troubleshooting

Common Issues

Issue	Solution
No types generated	Ensure tsconfig.json has experimentalDecorators and emitDecoratorMetadata enabled. Check that controllers use @ApinniController.
Types generated in wrong directory	Verify the outputPath in your config file.
Decorator errors	Confirm @apinni/client-ts is installed and imported correctly (import { ApinniController } from '@apinni/client-ts').
Endpoints missing or incorrect	Ensure you haven't used named imports (import { ApinniController as Controller } from '@apinni/client-ts')

Debugging Tips

• Run apinni with --verbose to see detailed logs:
• Check the output directory for generated .d.ts files.
• Verify that your tsconfig.json includes the correct include and exclude patterns.

warning

Ensure your TypeScript project is compiled with tsc or a compatible build tool before running apinni, as it relies on TypeScript metadata.

Next Steps

• Define Controllers: Learn how to create controllers with @ApinniController.
• Add Endpoints: Define endpoints using @ApinniEndpoint.
• Organize Types: Group endpoints with @ApinniDomain.
• Exclude Endpoints: Use @ApinniDisabled for selective type generation.

info

For advanced use cases, check the API Reference or contact the Apinni community.