Configuration ⚙️

AzuraJS uses a file-based configuration system that supports TypeScript, JSON, and YAML formats.

Configuration File 📄

Create an azura.config.ts file in your project root:

azura.config.ts

import type { ConfigTypes } from "azurajs/config";

const config: ConfigTypes = {
  environment: "development",
  server: {
    port: 3000,
    cluster: false,
    ipHost: true,
    https: false,
  },
  logging: {
    enabled: true,
    showDetails: true,
  },
  plugins: {
    cors: {
      enabled: true,
      origins: ["*"],
      methods: ["GET", "POST", "PUT", "DELETE", "PATCH"],
      allowedHeaders: ["Content-Type", "Authorization"],
    },
    rateLimit: {
      enabled: false,
      limit: 100,
      timeframe: 60000,
    },
  },
};

export default config;

Configuration Options 🔧

Environment

environment: "development" | "production" | "test"

Sets the application environment. Affects logging behavior and other environment-specific features.

In production mode, detailed logging is automatically disabled for better performance.

Server Configuration

port

port: number

The port number your server will listen on. Default: 3000

server: {
  port: 8080
}

cluster

cluster: boolean

Enable cluster mode to utilize all CPU cores. Default: false

server: {
  cluster: true  // Spawns a worker for each CPU core
}

Cluster mode is recommended for production but not necessary for development.

ipHost

ipHost: boolean

Display local network IP address on startup. Default: false

server: {
  ipHost: true  // Shows: http://192.168.1.100:3000
}

https

https: boolean

Indicates if the server is running behind HTTPS. Affects the req.protocol property. Default: false

Logging Configuration 📝

enabled

enabled: boolean

Enable/disable request logging. Default: true

showDetails

showDetails: boolean

Show detailed request/response information including:

Request method and path
Response status code
Response time
Request body (in development)

logging: {
  enabled: true,
  showDetails: true
}

Example output:

→ POST /api/users 201 Created (15ms)

CORS Plugin 🌐

Configure Cross-Origin Resource Sharing for your API.

enabled

enabled: boolean

Enable/disable CORS plugin. Default: false

origins

origins: string | string[]

Allowed origins for CORS requests.

cors: {
  enabled: true,
  origins: ["https://example.com", "https://app.example.com"]
  // or allow all: origins: ["*"]
}

methods

methods: string | string[]

Allowed HTTP methods.

cors: {
  methods: ["GET", "POST", "PUT", "DELETE", "PATCH", "OPTIONS"]
}

allowedHeaders

allowedHeaders: string | string[]

Allowed request headers.

cors: {
  allowedHeaders: ["Content-Type", "Authorization", "X-Requested-With"]
}

Rate Limiting Plugin 🛡️

Protect your API from abuse with built-in rate limiting.

enabled

enabled: boolean

Enable/disable rate limiting. Default: false

limit

limit: number

Maximum number of requests per timeframe.

rateLimit: {
  enabled: true,
  limit: 100  // 100 requests per timeframe
}

timeframe

timeframe: number

Timeframe in milliseconds.

rateLimit: {
  limit: 100,
  timeframe: 60000  // 100 requests per minute
}

When rate limit is exceeded, the server responds with 429 Too Many Requests

Environment-Specific Configuration 🌍

Use environment variables for different deployment environments:

azura.config.ts

import type { ConfigTypes } from "azurajs/config";

const isDev = process.env.NODE_ENV !== "production";
const port = process.env.PORT ? parseInt(process.env.PORT) : 3000;

const config: ConfigTypes = {
  environment: isDev ? "development" : "production",
  server: {
    port,
    cluster: !isDev,  // Enable cluster only in production
    ipHost: isDev,    // Show IP only in development
    https: !isDev,
  },
  logging: {
    enabled: true,
    showDetails: isDev,  // Detailed logs only in development
  },
  plugins: {
    cors: {
      enabled: true,
      origins: isDev 
        ? ["*"] 
        : ["https://yourdomain.com"],
    },
    rateLimit: {
      enabled: !isDev,  // Rate limit only in production
      limit: 100,
      timeframe: 60000,
    },
  },
};

export default config;

JSON Configuration 📋

You can also use JSON format:

azura.config.json

{
  "environment": "development",
  "server": {
    "port": 3000,
    "cluster": false
  },
  "logging": {
    "enabled": true,
    "showDetails": true
  }
}

YAML Configuration 📄

Or YAML format:

azura.config.yaml

environment: development
server:
  port: 3000
  cluster: false
logging:
  enabled: true
  showDetails: true

Accessing Configuration at Runtime 🔍

You can access the configuration in your application:

const app = new AzuraClient();
const config = app.getConfig();

console.log(`Server port: ${config.server?.port}`);
console.log(`Environment: ${config.environment}`);

Full Configuration Example 📚

Here's a complete production-ready configuration:

azura.config.ts

import type { ConfigTypes } from "azurajs/config";

const config: ConfigTypes = {
  environment: "production",
  server: {
    port: 8080,
    cluster: true,
    ipHost: false,
    https: true,
  },
  logging: {
    enabled: true,
    showDetails: false,
  },
  plugins: {
    cors: {
      enabled: true,
      origins: [
        "https://yourdomain.com",
        "https://app.yourdomain.com"
      ],
      methods: ["GET", "POST", "PUT", "DELETE", "PATCH"],
      allowedHeaders: [
        "Content-Type", 
        "Authorization",
        "X-API-Key"
      ],
    },
    rateLimit: {
      enabled: true,
      limit: 1000,
      timeframe: 60000, // 1000 requests per minute
    },
  },
};

export default config;

Next Steps 📖

Controllers

Learn about controller patterns

Middleware

Add custom middleware

CORS

Deep dive into CORS configuration

Rate Limiting

Advanced rate limiting patterns

Configuration

Controllers

Middleware

CORS

Rate Limiting

On this page