Configuration

Configure your Frame-Master application through the frame-master.config.ts file. Learn about HTTP server settings, plugin configuration, and advanced options.

Overview

Frame-Master uses a single configuration file to define your application's behavior. This file exports a FrameMasterConfig object that controls the HTTP server and plugins.

frame-master.config.ts

import type { FrameMasterConfig } from "frame-master/server/types";

const config: FrameMasterConfig = {
  HTTPServer: {
    port: 3000,
    hostname: "localhost",
  },
  plugins: [],
  pluginsOptions: {
    disableHttpServerOptionsConflictWarning: false,
  },
};

export default config;

💡

TypeScript Support

Frame-Master is built with TypeScript and provides full type definitions. Use the FrameMasterConfig type to get autocomplete and type checking in your configuration file.

HTTPServer Configuration

The HTTPServer property configures the underlying Bun HTTP server. Frame-Master uses Bun.serve() under the hood, so most Bun.serve options are available.

Basic Server Options

frame-master.config.ts

const config: FrameMasterConfig = {
  HTTPServer: {
    // Server address
    port: 3000,
    hostname: "localhost",
    
    // Development mode (enables Chrome DevTools)
    development: true,
    
    // Server identity
    id: "my-server-id",
    
    // Maximum request body size (in bytes)
    maxRequestBodySize: 1024 * 1024 * 10, // 10MB
  },
  plugins: [],
};

portnumber | string

The port number the server listens on. Can be a number or string.

Default: 3000

hostnamestring

The hostname to bind to. Use '0.0.0.0' to listen on all interfaces, or 'localhost' for local only.

Default: "0.0.0.0"

developmentboolean

Enables development mode with Chrome DevTools integration and better error messages.

Default: false

idstring

Optional identifier for the server instance.

maxRequestBodySizenumber

Maximum size of request body in bytes. Default is 128MB.

Default: 1024 * 1024 * 128

TLS/SSL Configuration

Enable HTTPS by providing TLS configuration:

frame-master.config.ts

import { readFileSync } from "fs";

const config: FrameMasterConfig = {
  HTTPServer: {
    port: 443,
    hostname: "example.com",
    
    // TLS/SSL configuration
    tls: {
      key: readFileSync("./certs/private-key.pem"),
      cert: readFileSync("./certs/certificate.pem"),
      // Optional: CA certificate
      ca: readFileSync("./certs/ca-cert.pem"),
      // Optional: passphrase for encrypted key
      passphrase: "my-secret-passphrase",
    },
  },
  plugins: [],
};

⚠️

Certificate Management

Never commit private keys to version control
Use environment variables for sensitive paths
Consider using Let's Encrypt for production certificates
Test SSL configuration locally before deploying

WebSocket Configuration

Configure WebSocket behavior for real-time communication:

frame-master.config.ts

const config: FrameMasterConfig = {
  HTTPServer: {
    port: 3000,
    
    // WebSocket configuration
    websocket: {
      // Maximum message size (in bytes)
      maxPayloadLength: 16 * 1024 * 1024, // 16MB
      
      // Idle timeout (in seconds)
      idleTimeout: 120,
      
      // Backpressure limit
      backpressureLimit: 1024 * 1024, // 1MB
      
      // Enable per-message deflate compression
      perMessageDeflate: true,
    },
  },
  plugins: [],
};

💡

Plugin WebSockets

Most WebSocket functionality in Frame-Master is handled by plugins. See the Creating Plugins documentation for implementing WebSocket handlers.

Error Handling

Customize error responses and handling:

frame-master.config.ts

const config: FrameMasterConfig = {
  HTTPServer: {
    port: 3000,
    
    // Custom error handler
    error(error: Error) {
      console.error("Server error:", error);
      
      return new Response("Internal Server Error", {
        status: 500,
        headers: { "Content-Type": "text/plain" },
      });
    },
  },
  plugins: [],
};

Low-Level Options

Advanced server configuration for specific use cases:

frame-master.config.ts

const config: FrameMasterConfig = {
  HTTPServer: {
    port: 3000,
    
    // Unix socket path (alternative to port)
    unix: "/tmp/my-app.sock",
    
    // Reuse port (SO_REUSEPORT)
    reusePort: true,
    
    // Low priority requests handling
    lowMemoryMode: false,
  },
  plugins: [],
};

unixstring

Unix domain socket path. If specified, the server will listen on this socket instead of a TCP port.

reusePortboolean

Enable SO_REUSEPORT for multiple processes to bind to the same port.

Default: false

lowMemoryModeboolean

Optimize for lower memory usage at the cost of some performance.

Default: false

Plugins Configuration

Plugins extend Frame-Master's functionality. Configure plugins by adding them to the plugins array.

frame-master.config.ts

import type { FrameMasterConfig } from "frame-master/server/types";
import ReactSSRPlugin from "frame-master-plugin-react-ssr/plugin";
import TailwindPlugin from "frame-master-plugin-tailwind";
import SessionPlugin from "frame-master-plugin-session/plugin";

const config: FrameMasterConfig = {
  HTTPServer: {
    port: 3000,
  },
  plugins: [
    // React SSR plugin with options
    ReactSSRPlugin({
      pathToShellFile: ".frame-master/shell.tsx",
      pathToClientWrapper: ".frame-master/client-wrapper.tsx",
      pathToBuildDir: ".frame-master/build",
    }),
    
    // Tailwind CSS plugin
    TailwindPlugin({
      inputFile: "static/index.css",
      outputFile: "static/tailwind.css",
    }),
    
    // Session management plugin
    SessionPlugin({
      framework: "react",
      strategy: "cookie",
    }),
  ],
};

export default config;

💡

Plugin Order Matters

Plugins are initialized in the order they appear in the array. Some plugins may depend on others being loaded first. Check plugin documentation for dependency requirements.

Plugin Configuration Patterns

📦

Plugin Import

Import plugins from their package's /plugin export path

⚙️

Plugin Options

Each plugin accepts a configuration object specific to its functionality

🔗

Plugin Composition

Combine multiple plugins to build your perfect framework

🔌

Plugin System

Learn more about how plugins work and their lifecycle

Learn more→

📚

Official Plugins

Explore official plugins and their configuration options

Learn more→

Plugin Options

Configure global plugin behavior with pluginsOptions.

frame-master.config.ts

const config: FrameMasterConfig = {
  HTTPServer: {
    port: 3000,
  },
  plugins: [
    // Your plugins here
  ],
  pluginsOptions: {
    // Disable warnings when plugins have conflicting server options
    disableHttpServerOptionsConflictWarning: false,
  },
};

disableHttpServerOptionsConflictWarningboolean

When multiple plugins try to set the same HTTPServer option with different values, Frame-Master throws an error by default. Set this to true to suppress the error and allow the last plugin's value to win.

Default: false

⚠️

Configuration Conflicts

Plugins can modify HTTPServer configuration through their serverConfig hook. If multiple plugins set conflicting values (like different ports), Frame-Master will throw an error unless you disable the warning. Be careful when disabling this as it may lead to unexpected behavior.

Configuration Merge Strategy

merge-example.ts

// Frame-Master merges configurations in this order:
// 1. Plugin 1 serverConfig
// 2. Plugin 2 serverConfig
// 3. Your HTTPServer config (highest priority)

// Example:
// Plugin A sets: { port: 3000 }
// Plugin B sets: { hostname: "0.0.0.0" }
// Your config:   { port: 8080 }
// Result:        { port: 8080, hostname: "0.0.0.0" }

// Conflict example (throws error by default):
// Plugin A sets: { port: 3000 }
// Plugin B sets: { port: 4000 }
// Error: Conflict in serverConfig plugins

Environment-Specific Configuration

Use environment variables and conditional logic to create environment-specific configurations.

frame-master.config.ts

import type { FrameMasterConfig } from "frame-master/server/types";

const isDevelopment = process.env.NODE_ENV === "development";
const isProduction = process.env.NODE_ENV === "production";

const config: FrameMasterConfig = {
  HTTPServer: {
    port: parseInt(process.env.PORT || "3000"),
    hostname: process.env.HOST || "localhost",
    
    // Enable development features
    development: isDevelopment,
    
    // Production-only TLS
    ...(isProduction && {
      tls: {
        key: Bun.file(process.env.TLS_KEY_PATH!),
        cert: Bun.file(process.env.TLS_CERT_PATH!),
      },
    }),
  },
  plugins: [
    // Conditionally include plugins
    ...(isDevelopment ? [DevToolsPlugin()] : []),
  ],
};

export default config;

💡

Environment Best Practices

Create separate .env.development and .env.production files
Use sensible defaults with fallback values (||)
Validate required environment variables on startup
Document all environment variables in .env.example

Configuration Validation

frame-master.config.ts

import type { FrameMasterConfig } from "frame-master/server/types";

// Validate required environment variables
const requiredEnvVars = ["DATABASE_URL", "API_KEY"];
for (const envVar of requiredEnvVars) {
  if (!process.env[envVar]) {
    throw new Error(`Missing required environment variable: ${envVar}`);
  }
}

// Validate configuration values
const port = parseInt(process.env.PORT || "3000");
if (isNaN(port) || port < 1 || port > 65535) {
  throw new Error(`Invalid port number: ${process.env.PORT}`);
}

const config: FrameMasterConfig = {
  HTTPServer: { port },
  plugins: [],
};

export default config;

Complete Example

A comprehensive configuration example showing all major features.

frame-master.config.ts

import type { FrameMasterConfig } from "frame-master/server/types";
import ReactSSRPlugin from "frame-master-plugin-react-ssr/plugin";
import TailwindPlugin from "frame-master-plugin-tailwind";
import SessionPlugin from "frame-master-plugin-session/plugin";
import { readFileSync } from "fs";

const isDevelopment = process.env.NODE_ENV === "development";
const isProduction = process.env.NODE_ENV === "production";

const config: FrameMasterConfig = {
  HTTPServer: {
    // Basic server config
    port: parseInt(process.env.PORT || "3000"),
    hostname: process.env.HOST || "localhost",
    
    // Development features
    development: isDevelopment,
    
    // Request limits
    maxRequestBodySize: 1024 * 1024 * 50, // 50MB
    
    // TLS/SSL for production
    ...(isProduction && {
      tls: {
        key: readFileSync(process.env.TLS_KEY_PATH!),
        cert: readFileSync(process.env.TLS_CERT_PATH!),
      },
    }),
    
    // WebSocket configuration
    websocket: {
      maxPayloadLength: 16 * 1024 * 1024,
      idleTimeout: 120,
      perMessageDeflate: true,
    },
    
    // Custom error handler
    error(error: Error) {
      console.error("[Server Error]", error);
      
      if (isDevelopment) {
        return new Response(
          JSON.stringify({
            error: error.message,
            stack: error.stack,
          }),
          {
            status: 500,
            headers: { "Content-Type": "application/json" },
          }
        );
      }
      
      return new Response("Internal Server Error", {
        status: 500,
        headers: { "Content-Type": "text/plain" },
      });
    },
  },
  
  plugins: [
    // React SSR for UI
    ReactSSRPlugin({
      pathToShellFile: ".frame-master/shell.tsx",
      pathToClientWrapper: ".frame-master/client-wrapper.tsx",
      pathToBuildDir: ".frame-master/build",
      pathToPagesDir: "src/pages",
    }),
    
    // Tailwind for styling
    TailwindPlugin({
      inputFile: "static/index.css",
      outputFile: "static/tailwind.css",
    }),
    
    // Session management
    SessionPlugin({
      framework: "react",
      strategy: "cookie",
    }),
  ],
  
  pluginsOptions: {
    disableHttpServerOptionsConflictWarning: false,
  },
};

export default config;