NitroStack Logo
/cli
/configuration

Configuration Guide

Overview

NitroStack uses a zero-config-file approach for tooling, paired with declarative TypeScript modules and standard .env environment variables for application runtime settings.

There is no proprietary configuration file (such as nitrostack.config.ts). Everything is configured via:

  1. CLI Flags: For development ports, build targets, and scaffolding options.
  2. package.json: For project scripts, dependencies, and agent skills tracking.
  3. Environment Variables (.env): For application secrets, server ports, and third-party credentials.
  4. ConfigModule: For type-safe in-code configuration management in @nitrostack/core.

CLI Configuration

CLI commands accept command-line options directly:

Bash
# Set widget dev server port
nitrostack-cli dev --port 3001

# Set production server port
nitrostack-cli start --port 3000

# Custom build output directory
nitrostack-cli build --output dist

# Cursor integration options
nitrostack-cli cursor --type streamable-http --url http://localhost:3000/mcp

# Packaging options
nitrostack-cli pack --include-env --output release.zip

Environment Variables (.env)

NitroStack applications read runtime configuration from .env files in the project root:

Bash
# Server Port (default: 3000)
PORT=3000

# MCP Protocol Era ('auto' | '2026-07-28' | 'legacy')
NITRO_MCP_PROTOCOL_VERSION=auto

# Logging Level ('debug' | 'info' | 'warn' | 'error')
LOG_LEVEL=info

# OAuth 2.1 Configuration (for typescript-oauth template)
RESOURCE_URI=http://localhost:3000
AUTH_SERVER_URL=https://auth.example.com
OAUTH_REQUIRED=false
JWKS_URI=https://auth.example.com/.well-known/jwks.json

# API Key Authentication (for ApiKeyModule)
API_KEY_1=sk_live_prod_abc123
API_KEY_2=sk_test_dev_xyz789

# External Service Credentials
DUFFEL_API_KEY=duffel_test_xyz
MAPBOX_ACCESS_TOKEN=pk.eyJ1...

Type-Safe In-Code Configuration (ConfigModule)

For structured, validated access to environment variables within your services and tools, use ConfigModule.forRoot():

Typescript
// src/app.module.ts
import { McpApp, Module, ConfigModule } from '@nitrostack/core';
import { CalculatorModule } from './modules/calculator/calculator.module.js';

@McpApp({
  module: AppModule,
  server: {
    name: 'my-mcp-server',
    version: '1.0.0',
  },
})
@Module({
  imports: [
    ConfigModule.forRoot({
      envFilePath: process.env.NODE_ENV === 'production' ? '.env.production' : '.env',
      defaults: {
        PORT: '3000',
        LOG_LEVEL: 'info',
      },
      validate: (config) => {
        // Enforce required settings during server startup
        return Boolean(config.PORT);
      },
    }),
    CalculatorModule,
  ],
})
export class AppModule {}

Then inject ConfigService into any service or controller:

Typescript
import { Injectable, ConfigService } from '@nitrostack/core';

@Injectable({ deps: [ConfigService] })
export class ApiService {
  constructor(private configService: ConfigService) {
    const port = this.configService.get('PORT', '3000');
    const secret = this.configService.getOrThrow('API_SECRET');
  }
}

Project Metadata (package.json)

Project scripts and skills metadata are maintained in package.json:

JSON
{
  "name": "my-mcp-server",
  "version": "1.0.0",
  "type": "module",
  "scripts": {
    "dev": "nitrostack-cli dev",
    "build": "nitrostack-cli build",
    "start": "nitrostack-cli start",
    "upgrade": "nitrostack-cli upgrade",
    "install:all": "nitrostack-cli install"
  },
  "dependencies": {
    "@nitrostack/core": "^1.0.16"
  },
  "nitrostack": {
    "skillsVersion": "1.0.0"
  }
}

Next Steps

Documentation Home•View All Docs•GitHub