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: {
    // see Bun documentation for available options
  },
  plugins: [],
};

Bun.serveobjectrequired

All options available in Bun.serve() can be used here to configure the HTTP server.

→bun.serve API Docs

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, unless they are specified with a priority param. Some plugins may depend on others being loaded first. Check plugin documentation for dependency requirements.

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;