or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

cli-commands.mdframework-integration.mdindex.mdplugin-system.md
tile.json

plugin-system.mddocs/

Plugin System

Builtin plugin system that automatically configures development and build processes based on user configuration and project requirements. The system provides a comprehensive set of plugins for React applications, SSR, state management, authentication, and more.

Capabilities

getBuiltInPlugins Function

Core function that returns the appropriate plugin configuration based on user settings and project requirements.

/**
 * Get builtin plugins based on user configuration (CommonJS export = syntax)
 * @param {Object} userConfig - User configuration object
 * @returns {Array<string|Array>} Array of plugin configurations
 */
export = function getBuiltInPlugins(userConfig);

Usage Examples:

const getBuiltInPlugins = require("ice.js/lib/getBuiltInPlugins");

// Get plugins for basic React app
const plugins = getBuiltInPlugins({});

// Get plugins with SSR enabled
const ssrPlugins = getBuiltInPlugins({ ssr: true });

// Get plugins with store disabled
const noStorePlugins = getBuiltInPlugins({ store: false });

// Get minimal plugin set for runtime-disabled apps
const minimalPlugins = getBuiltInPlugins({ disableRuntime: true });

Builtin Plugin Categories

Core Plugins (always included)

Essential plugins that are included in every configuration:

// Core application plugin with framework configuration
"build-plugin-app-core"

// React application base plugin
"build-plugin-react-app"

// Mini-app support plugin  
"build-plugin-miniapp"

// Router functionality plugin
"build-plugin-ice-router"

// Helper utilities plugin
"build-plugin-ice-helpers"

// Logging plugin
"build-plugin-ice-logger"

// Configuration management plugin
"build-plugin-ice-config"

// Multi-page application plugin
"build-plugin-ice-mpa"

// HTTP request utilities plugin
"build-plugin-ice-request"

// React Helmet plugin for head management
"build-plugin-helmet"

Conditional Plugins

Plugins that are included based on user configuration:

Server-Side Rendering Plugin

// Included when userConfig.ssr === true
"build-plugin-ice-ssr"

Configuration:

// Enable SSR plugin
const plugins = getBuiltInPlugins({ ssr: true });

State Management Plugin

// Included by default unless userConfig.store === false
"build-plugin-ice-store"

Configuration:

// Default behavior (store plugin included)
const plugins = getBuiltInPlugins({});

// Disable store plugin
const plugins = getBuiltInPlugins({ store: false });

// Explicitly enable store plugin
const plugins = getBuiltInPlugins({ store: true });

Authentication Plugin

// Included by default unless userConfig.auth === false
"build-plugin-ice-auth"

Configuration:

// Default behavior (auth plugin included)
const plugins = getBuiltInPlugins({});

// Disable auth plugin
const plugins = getBuiltInPlugins({ auth: false });

// Explicitly enable auth plugin
const plugins = getBuiltInPlugins({ auth: true });

Special Configurations

Runtime Disabled Mode

When 

disableRuntime
is true, only essential plugins are included:

/**
 * Minimal plugin set for runtime-disabled applications
 * @param {Object} userConfig - Must have disableRuntime: true
 * @returns {Array} Minimal plugin array
 */
// Returns: ["build-plugin-react-app", "build-plugin-ice-mpa"]
getBuiltInPlugins({ disableRuntime: true });

Usage:

// For applications that don't need the full ice.js runtime
const minimalPlugins = getBuiltInPlugins({ 
  disableRuntime: true 
});

Core Plugin Configuration

The app-core plugin receives special configuration:

/**
 * Core plugin configuration object
 * @typedef {Object} CoreOptions
 * @property {string} framework - Framework type (always "react")
 * @property {string} alias - Framework alias name
 */

// Configuration passed to build-plugin-app-core
{
  framework: "react",
  alias: process.env.__FRAMEWORK_NAME__ || "ice"
}

Plugin Validation and Warnings

Duplicate Plugin Detection

The system detects and warns about duplicate auth plugin configurations:

/**
 * Checks if build-plugin-ice-auth is already configured in user plugins
 * Displays warning message if duplicate found
 * @param {Object} userConfig - User configuration with plugins array
 */

Behavior:

// If user manually adds auth plugin, warning is displayed:
const userConfig = {
  plugins: ["build-plugin-ice-auth"]
};

const plugins = getBuiltInPlugins(userConfig);
// Console output: "The build-plugin-ice-auth has been built in. Please remove it from build.json."

Environment Variables

Framework Configuration

Plugin system respects environment variables for framework configuration:

// Framework name (defaults to "ice")
process.env.__FRAMEWORK_NAME__

// Framework version (set from package.json)
process.env.__FRAMEWORK_VERSION__

Usage:

# Set custom framework name
__FRAMEWORK_NAME__=my-framework icejs start

# Framework version is automatically set
# process.env.__FRAMEWORK_VERSION__ = "1.18.6"

Plugin Configuration Format

Plugin Array Structure

Plugins can be specified as strings or arrays:

/**
 * Plugin configuration formats
 * @typedef {string|Array} PluginConfig
 */

// String format (plugin name only)
"build-plugin-react-app"

// Array format (plugin name with options)
["build-plugin-app-core", { framework: "react", alias: "ice" }]

Complete Plugin List Example

// Example of complete plugin list returned by getBuiltInPlugins
[
  ["build-plugin-app-core", { framework: "react", alias: "ice" }],
  "build-plugin-react-app",
  "build-plugin-miniapp", 
  "build-plugin-ice-router",
  "build-plugin-ice-helpers",
  "build-plugin-ice-logger",
  "build-plugin-ice-config",
  "build-plugin-ice-mpa",
  "build-plugin-ice-request",
  "build-plugin-helmet",
  "build-plugin-ice-ssr",      // if ssr: true
  "build-plugin-ice-store",    // if store !== false
  "build-plugin-ice-auth"      // if auth !== false
]