Getting Started

nexus-nf is a TypeScript framework for building NATS-based microservices with a decorator-driven approach. It provides automatic request/response handling, validation, and error management.

Prerequisites

Before you use nexus-nf to build microservices, you will need to

Have a basic understanding of TypeScript and NodeJS
Understand NATS on at least a surface level

The nexus-nf documentation will not teach you TypeScript, NodeJS or NATS. Basic level knowledge is expected and assumed.

Installation

Use the project generator

npx create-nexus-service

Create your first controller

Create a controller by extending ControllerBase and decorating methods with @Endpoint:

import { ControllerBase, Endpoint } from 'nexus-nf';
import { z } from 'zod';

// Create a zod schema for data validation
const addSchema = z.object({
  firstNumber: z.number(),
  secondNumber: z.number()
});

export class MathController extends ControllerBase {
  constructor() {
    super('math');
  }

  @Endpoint('add', { schema: addSchema })
  async add(data: z.infer<typeof addSchema>): Promise<number> {
    return data.firstNumber + data.secondNumber;
  }
}

Initialize the application

Connect to NATS and register your controllers:

import { connect } from 'nats';
import { NexusApp } from 'nexus-nf';
import { MathController } from './controllers/math';

async function main() {
  // Connect to NATS
  const nc = await connect({
    servers: 'nats://localhost:4222'
  });

  // Create a NATS service
  const service = await nc.services.add({
    name: 'math-service',
    version: '1.0.0',
    description: 'Mathematical operations service'
  });

  // Initialize NexusApp
  const app = new NexusApp(nc, service);

  // Register controllers
  app.registerController(new MathController());

  console.log('Service running...');
}

main();

Make requests

Your endpoints are now available at {group}.{endpoint}:

nats request "math.add" '{"firstNumber": 10, "secondNumber": 15}'

Project Structure

A typical nexus-nf project follows this structure:

index.ts

math.controller.ts

tsconfig.json

package.json

Controllers are the main building blocks of your application. Each controller groups related endpoints under a common namespace.

Response Format

All nexus-nf endpoints return responses in a standardized format:

Success Response

{
  "error": false,
  "data": 8
}

Error Response

nats request "math.add" '{"firstNumber": "invalid", "secondNumber": 15}'

{
  "error": true,
  "message": "Bad Request: Validation failed.",
  "code": "400",
  "details": [
    {
      "path": ["firstNumber"],
      "message": "Expected number, received string"
    }
  ]
}

In production mode, error details like stack traces are automatically omitted. Set NODE_ENV=dev during development to see full error information.

Next Steps

Learn about Controllers and how to organize your endpoints
Explore Validation with Zod schemas
Understand Error Handling patterns

Getting Started

On this page