@nestjstools/apisix-client

A lightweight and strongly-typed NestJS module for integrating with Apache APISIX Admin API. It allows you to manage routes, services, upstreams, consumers and plugins programmatically from your NestJS application. Designed for infrastructure automation, dynamic gateway configuration, and platform tooling.

Features

• Simple forRoot() configuration
• Fully typed Admin API client
• Global module support
• Configurable prefix and port
• Designed for automation & platform services
• Clean NestJS integration

Installation

This library requires @nestjs/axios to communicate with the APISIX Admin API.

npm install @nestjstools/apisix-client @nestjs/axios

or

yarn add @nestjstools/apisix-client @nestjs/axios

Quick Start

Register Module

import { Module } from '@nestjs/common';
import { ApisixClientModule } from '@nestjstools/apisix-client';

@Module({
  imports: [
    ApisixClientModule.forRoot({
      url: 'http://localhost',
      adminSecret: process.env.APISIX_ADMIN_SECRET,
      global: true, // optional (default: true)
      prefix: 'apisix', // optional (default: 'apisix')
      port: 9180, // optional (default: 9180)
      // Base URL becomes:
      // http://localhost:9180/apisix
    }),
  ],
})
export class AppModule {
}

Usage Example

Inject Client

import { Injectable, OnModuleInit } from '@nestjs/common';
import { ApisixClient, ApisixRouteRequest } from '@nestjstools/apisix-client';

@Injectable()
export class GatewaySyncService implements OnModuleInit {
  constructor(private readonly apisix: ApisixClient) {}

  async onModuleInit() {
    await this.ensureUserRoute();
  }

  private async ensureUserRoute() {
    const routeId = 'users-route';

    const desiredRoute = {
      id: routeId,
      uri: '/users',
      methods: ['GET', 'POST'],
      upstream: {
        type: 'roundrobin',
        nodes: {
          'host.docker.internal:3000': 1,
        },
      },
    } as ApisixRouteRequest;

    try {
      await this.apisix.route().upsertRoute(routeId, desiredRoute);
      console.log('APISIX route updated');
    } catch (err) {
      console.log(err);
    }
  }
}

Configuration

| Property | Description | Default | |---------------|--------------------------|----------| | url | Base APISIX host | required | | adminSecret | APISIX Admin API key | required | | port | Admin API port | 9180 | | prefix | Admin API prefix | apisix | | global | Register module globally | true |

This library supports most of the commonly used Apache APISIX plugins, including authentication, traffic control, transformation, and security plugins.

🧪 Tests

This library is covered by end-to-end (E2E) tests to ensure real integration behavior with Apache APISIX.

The E2E test suite validates:

• Route creation and updates
• Plugin configuration
• Consumer management
• Admin API communication
• Error handling scenarios

All critical gateway operations are tested against a running APISIX instance to ensure production-level reliability.