Frame-master logo

Documentation

Installing Plugins

Learn how to install, configure, and manage plugins in your Frame-Master project.

⚡ Quick Install

Install plugins from npm and add them to your configuration.

Step 1: Install the Package

terminal
# Using bun (recommended)
bun add frame-master-plugin-react-ssr


# Using npm
npm install frame-master-plugin-react-ssr


# Using yarn
yarn add frame-master-plugin-react-ssr

Step 2: Add to Configuration

frame-master.config.ts
import { defineConfig } from "frame-master";
import reactSSR from "frame-master-plugin-react-ssr";


export default defineConfig({
  plugins: [
    reactSSR({
      // Plugin options
    }),
  ],
});
✅

That's it!

The plugin is now active. Restart your dev server to apply changes.

🔍 Finding Plugins

Discover plugins from various sources.

📦 NPM Registry

Search for 'frame-master-plugin' on npm

npm search frame-master-plugin

🌐 Official Website

Browse curated plugins on frame-master.dev

Browse Plugins →

🔎 CLI Search ( future release )

Search plugins from the command line

frame-master search [query]

📂 GitHub

Find community plugins on GitHub

GitHub Topics →

⚙️ Configuring Plugins

Learn how to configure plugins with options.

Basic Configuration

frame-master.config.ts
import { defineConfig } from "frame-master";
import reactSSR from "frame-master-plugin-react-ssr";
import session from "frame-master-plugin-session";
import database from "frame-master-plugin-database";


export default defineConfig({
  plugins: [
    // Plugin with default options
    reactSSR(),
    
    // Plugin with custom options
    session({
      secret: process.env.SESSION_SECRET,
      maxAge: 86400, // 1 day
      secure: process.env.NODE_ENV === "production",
    }),
    
    // Plugin with environment-specific config
    database({
      url: process.env.DATABASE_URL,
      pool: {
        min: 2,
        max: 10,
      },
    }),
  ],
});

Environment-Based Configuration

frame-master.config.ts
import { defineConfig } from "frame-master";
import analytics from "frame-master-plugin-analytics";


const isDev = process.env.NODE_ENV !== "production";


export default defineConfig({
  plugins: [
    analytics({
      // Disable in development
      enabled: !isDev,
      trackingId: process.env.ANALYTICS_ID,
      
      // Different settings per environment
      debug: isDev,
      anonymizeIp: !isDev,
    }),
  ],
});

Conditional Plugins

frame-master.config.ts
import { defineConfig } from "frame-master";
import devTools from "frame-master-plugin-devtools";
import sentry from "frame-master-plugin-sentry";


const isDev = process.env.NODE_ENV !== "production";


export default defineConfig({
  plugins: [
    // Only load in development
    ...(isDev ? [devTools()] : []),
    
    // Only load in production
    ...(isDev ? [] : [
      sentry({
        dsn: process.env.SENTRY_DSN,
      }),
    ]),
  ],
});

📋 Plugin Order & Priority

Understanding how plugin execution order works.

💡

How Priority Works

- Plugins are sorted by their priority property. Lower numbers execute first. Array order doesn't matter—priority does!
- If two plugins have the same priority, they execute in the order they are listed in the configuration.
- Default priority is undefined, which runs after any numbered priorities.

frame-master.config.ts
import { defineConfig } from "frame-master";
import auth from "frame-master-plugin-auth";       // priority: 0
import session from "frame-master-plugin-session"; // priority: 10
import logging from "frame-master-plugin-logging"; // priority: undefined ( run last )


export default defineConfig({
  plugins: [logging(), session(), auth()],
  // Execution order: auth → session → logging
});

See the Plugin Lifecycle for detailed execution flow.

🔗 Plugin Dependencies

Handle plugins that depend on other plugins.

⚠️

Dependency Validation

Frame-Master validates plugin dependencies at startup. If a required plugin is missing or has an incompatible version, the server won't start.

frame-master.config.ts
import { defineConfig } from "frame-master";
import session from "frame-master-plugin-session";
import auth from "frame-master-plugin-auth"; // Requires session plugin


export default defineConfig({
  plugins: [
    // Session must be loaded for auth to work
    session({
      secret: process.env.SESSION_SECRET,
    }),
    
    // Auth plugin declares session as a requirement
    auth({
      providers: ["github", "google"],
    }),
  ],
});

Checking Requirements

View a plugin's requirements in its documentation or by using the CLI:frame-master plugin info <plugin-name>

📦 Managing Plugin Versions

Best practices for plugin version management.

Check for Updates

terminal
# Check outdated packages
bun outdated


# Update a specific plugin
bun update frame-master-plugin-react-ssr


# Update all plugins
bun update

Version Pinning

package.json
{
  "dependencies": {
    // Exact version (most stable)
    "frame-master-plugin-auth": "1.2.3",
    
    // Patch updates only (recommended)
    "frame-master-plugin-session": "~1.2.0",
    
    // Minor updates (default with ^)
    "frame-master-plugin-database": "^1.2.0"
  }
}
💡

Version Strategy

  • Use exact versions for critical plugins (auth, database)
  • Use ~ (patch) for stable plugins you trust
  • Use ^ (minor) for actively developed plugins
  • Always test after updating plugins

🔧 Troubleshooting

Common issues and solutions.

Plugin Not Loading

terminal
# Verify installation
bun pm ls | grep frame-master-plugin


# Reinstall if needed
bun remove frame-master-plugin-xyz && bun add frame-master-plugin-xyz

Version Conflicts

terminal
# Check peer dependencies
bun pm ls --all


# Force resolution (use with caution)
bun install --force

Debug Mode

terminal
# Run with verbose output
frame-master start --verbose

🗑️ Uninstalling Plugins

Safely remove plugins from your project.

terminal
# 1. Remove from frame-master.config.ts first
# 2. Uninstall the package
bun remove frame-master-plugin-name
⚠️

Check Dependencies

Before removing a plugin, ensure no other plugins depend on it.

🎯Next Steps

🔧

Creating Plugins

Build your own custom plugins

Learn more→
🪝

Plugin Hooks

Complete hook reference

Learn more→
📦

Browse Plugins

Discover community plugins

Learn more→