Generate Command

Overview

The generate command creates boilerplate code for common NitroStack components, saving time and ensuring consistency.

Usage

nitrostack generate <type> [name] [options]

Types

Options

Examples

Generate Types

Auto-generate TypeScript types from your tool definitions:

nitrostack generate types

Output: src/types/generated-tools.ts

export type GetProductInput = {
  product_id: string;
};

export type GetProductOutput = {
  id: string;
  name: string;
  price: number;
};

export interface ToolInputs {
  'get_product': GetProductInput;
}

export interface ToolOutputs {
  'get_product': GetProductOutput;
}

Custom output path:

nitrostack generate types --output src/types/custom.ts

Generate Module

Create a new feature module:

nitrostack generate module payments

Creates:

• src/modules/payments/payments.module.ts
• src/modules/payments/payments.tools.ts
• src/modules/payments/payments.resources.ts
• src/modules/payments/payments.prompts.ts

Generated Code:

// payments.module.ts
import { Module } from 'nitrostack';
import { PaymentsTools } from './payments.tools.js';
import { PaymentsResources } from './payments.resources.js';
import { PaymentsPrompts } from './payments.prompts.js';

@Module({
  name: 'payments',
  description: 'Payments module',
  controllers: [PaymentsTools, PaymentsResources, PaymentsPrompts]
})
export class PaymentsModule {}

Generate Tool

Add a tool to an existing module:

nitrostack generate tool process-payment --module payments

Creates: src/modules/payments/process-payment.tool.ts

import { ToolDecorator as Tool, z, ExecutionContext } from 'nitrostack';

export class ProcessPaymentTool {
  @Tool({
    name: 'process_payment',
    description: 'TODO: Add description',
    inputSchema: z.object({
      // TODO: Add input fields
    })
  })
  async processPayment(input: any, context: ExecutionContext) {
    // TODO: Implement logic
    return {};
  }
}

Generate Resource

nitrostack generate resource payment-status --module payments

Creates: src/modules/payments/payment-status.resource.ts

import { ResourceDecorator as Resource, ExecutionContext } from 'nitrostack';

export class PaymentStatusResource {
  @Resource({
    uri: 'payment://status/{id}',
    name: 'Payment Status',
    description: 'TODO: Add description'
  })
  async getPaymentStatus(uri: string, context: ExecutionContext) {
    // Extract ID from URI
    const id = uri.split('/').pop();
    
    // TODO: Implement logic
    return {
      contents: [{
        uri,
        mimeType: 'application/json',
        text: JSON.stringify({ id, status: 'pending' })
      }]
    };
  }
}

Generate Prompt

nitrostack generate prompt payment-reminder --module payments

Creates: src/modules/payments/payment-reminder.prompt.ts

import { PromptDecorator as Prompt, ExecutionContext } from 'nitrostack';

export class PaymentReminderPrompt {
  @Prompt({
    name: 'payment_reminder',
    description: 'TODO: Add description',
    arguments: [
      {
        name: 'customer_name',
        description: 'Customer name',
        required: true
      }
    ]
  })
  async getPaymentReminder(args: Record<string, string>, context: ExecutionContext) {
    return {
      messages: [
        {
          role: 'system',
          content: 'You are a payment reminder assistant.'
        },
        {
          role: 'user',
          content: `Create a payment reminder for ${args.customer_name}`
        }
      ]
    };
  }
}

Generate Guard

Create an authentication guard:

nitrostack generate guard admin

Creates: src/guards/admin.guard.ts

import { Guard, ExecutionContext } from 'nitrostack';

export class AdminGuard implements Guard {
  async canActivate(context: ExecutionContext): Promise<boolean> {
    // TODO: Implement admin check
    const user = context.auth?.user;
    return user?.role === 'admin';
  }
}

Generate Middleware

nitrostack generate middleware logging

Creates: src/middleware/logging.middleware.ts

import { Middleware, MiddlewareInterface, ExecutionContext } from 'nitrostack';

@Middleware()
export class LoggingMiddleware implements MiddlewareInterface {
  async use(context: ExecutionContext, next: () => Promise<any>) {
    const start = Date.now();
    console.log(`[${context.toolName}] Started`);
    
    const result = await next();
    
    const duration = Date.now() - start;
    console.log(`[${context.toolName}] Completed in ${duration}ms`);
    
    return result;
  }
}

Generate Interceptor

nitrostack generate interceptor transform

Creates: src/interceptors/transform.interceptor.ts

import { Interceptor, InterceptorInterface, ExecutionContext } from 'nitrostack';

@Interceptor()
export class TransformInterceptor implements InterceptorInterface {
  async intercept(context: ExecutionContext, next: () => Promise<any>) {
    const result = await next();
    
    return {
      success: true,
      data: result,
      timestamp: new Date().toISOString()
    };
  }
}

Generate Pipe

nitrostack generate pipe validation

Creates: src/pipes/validation.pipe.ts

import { Pipe, PipeInterface, ArgumentMetadata } from 'nitrostack';

@Pipe()
export class ValidationPipe implements PipeInterface {
  transform(value: any, metadata: ArgumentMetadata) {
    // TODO: Implement validation
    return value;
  }
}

Generate Filter

nitrostack generate filter http-exception

Creates: src/filters/http-exception.filter.ts

import { ExceptionFilter, ExceptionFilterInterface, ExecutionContext } from 'nitrostack';

@ExceptionFilter()
export class HttpExceptionFilter implements ExceptionFilterInterface {
  catch(exception: any, context: ExecutionContext) {
    return {
      statusCode: exception.status || 500,
      message: exception.message || 'Internal server error',
      timestamp: new Date().toISOString(),
      tool: context.toolName
    };
  }
}

Generate Service

nitrostack generate service email

Creates: src/services/email.service.ts

import { Injectable } from 'nitrostack';

@Injectable()
export class EmailService {
  async send(to: string, subject: string, body: string) {
    // TODO: Implement email sending
    console.log(`Sending email to ${to}: ${subject}`);
  }
}

Workflow Examples

Adding a New Feature

# 1. Generate module
nitrostack generate module notifications

# 2. Generate tools
nitrostack generate tool send-notification --module notifications
nitrostack generate tool get-notifications --module notifications

# 3. Generate service
nitrostack generate service notification

# 4. Generate types
nitrostack generate types

# 5. Register module in app.module.ts
# Import and add to imports array

# 6. Start dev mode
nitrostack dev

Adding Authentication

# 1. Generate guard
nitrostack generate guard jwt

# 2. Implement guard logic
# Edit src/guards/jwt.guard.ts

# 3. Use on tools
# @UseGuards(JWTGuard)

# 4. Test in Studio
nitrostack dev

Refactoring to Services

# 1. Generate service
nitrostack generate service user

# 2. Move business logic from tools to service
# 3. Inject service in tools via constructor
# 4. Register service in module providers

Best Practices

1. Generate Before Manual Creation

Always use generators for consistency:

# ✅ Good
nitrostack generate module users

# ❌ Avoid
# Manually creating files

2. Regenerate Types Frequently

After changing tools:

nitrostack generate types

This ensures type safety between backend and widgets.

3. Use Module Flag

Keep code organized:

# ✅ Good - organized
nitrostack generate tool get-user --module users

# ❌ Avoid - scattered
nitrostack generate tool get-user

4. Review Generated Code

Generators create boilerplate - customize it:

// Generated
@Tool({
  name: 'my_tool',
  description: 'TODO: Add description',  // ← Update this
  inputSchema: z.object({
    // TODO: Add fields  // ← Add fields
  })
})

5. Commit Generated Files

Generated files are part of your codebase:

git add src/types/generated-tools.ts
git commit -m "chore: update generated types"

Troubleshooting

File Already Exists

Error: File already exists

Solution:

# Use --force to overwrite
nitrostack generate tool my-tool --force

# Or rename/delete existing file
rm src/modules/my-module/my-tool.tool.ts

Module Not Found

Error: Module 'payments' not found

Solution:

# Create module first
nitrostack generate module payments

# Then add tools
nitrostack generate tool process-payment --module payments

Types Generation Failed

Error: No tool files found

Solution:

# Ensure tools exist
ls src/modules/*/tools.ts

# Check file naming
# Should be: *.tools.ts (not *.tool.ts)

Permission Denied

Error: EACCES: permission denied

Solution:

# Fix permissions
chmod +w src/

# Or run with sudo (not recommended)
sudo nitrostack generate types

Advanced Usage

Custom Templates

Coming soon: Custom generator templates

Batch Generation

# Generate multiple at once
nitrostack generate module payments && \
nitrostack generate tool create-payment --module payments && \
nitrostack generate tool get-payment --module payments && \
nitrostack generate types

Integration with IDE

Many IDEs support running npm scripts:

{
  "scripts": {
    "gen:types": "nitrostack generate types",
    "gen:module": "nitrostack generate module"
  }
}

Next Steps

• Testing Guide
• Module Organization
• Type Safety

Pro Tip: Create aliases for frequent commands:

# In .bashrc or .zshrc
alias smg='nitrostack generate'
alias smgt='nitrostack generate types'
alias smgm='nitrostack generate module'