or run

npx @tessl/cli init

Version

Tile

Overview

Evals

Files

docs

client-api.md content-scripts.md file-writer-system.md index.md manifest-definition.md plugin-configuration.md

tile.json

Plugin Configuration

Core plugin functions that create Chrome extension configuration for Vite, providing a complete set of specialized plugins for different extension features including manifest processing, content scripts, HMR, and file management.

Capabilities

Main Plugin Function

Creates the complete CRXJS Vite plugin configuration for Chrome extension development.

/**
 * Creates Chrome extension configuration for Vite
 * @param options - Configuration object containing manifest and options
 * @returns Array of Vite plugins for Chrome extension development
 */
function crx(options: {
  manifest: ManifestV3Export;
} & CrxOptions): PluginOption[];

// Alias for crx function - identical functionality
const chromeExtension = crx;

Usage Examples:

import { defineConfig } from "vite";
import { crx, defineManifest } from "@crxjs/vite-plugin";

const manifest = defineManifest({
  manifest_version: 3,
  name: "My Extension",
  version: "1.0.0",
  background: {
    service_worker: "src/background.ts",
  },
});

// Basic usage
export default defineConfig({
  plugins: [crx({ manifest })],
});

// With content script options
export default defineConfig({
  plugins: [
    crx({
      manifest,
      contentScripts: {
        preambleCode: "console.log('Content script loaded');",
        hmrTimeout: 5000,
        injectCss: true,
      },
      browser: 'chrome',
    }),
  ],
});

Plugin Options

Configuration options for customizing plugin behavior.

interface CrxOptions {
  /** Content script configuration options */
  contentScripts?: {
    /** Code to inject at the beginning of content scripts, or false to disable */
    preambleCode?: string | false;
    /** Timeout for HMR connections in milliseconds */
    hmrTimeout?: number;
    /** Whether to inject CSS files into content scripts */
    injectCss?: boolean;
  };
  /** Options passed to fast-glob for file matching */
  fastGlobOptions?: FastGlobOptions;
  /** Target browser - affects manifest processing and features */
  browser?: 'firefox' | 'chrome'; // default: 'chrome'
}

Content Script Options:

preambleCode: Custom code injected at the start of content scripts. Useful for polyfills or initialization. Set to false to disable.
hmrTimeout: Maximum time to wait for HMR connection establishment (default: reasonable timeout).
injectCss: Whether to automatically inject CSS files into content scripts (default: true).

Browser Support:

chrome: Default. Enables Chrome-specific features and optimizations.
firefox: Enables Firefox-specific manifest processing and features.

Plugin Architecture

The crx function returns an array of specialized Vite plugins that work together:

// Internal plugin structure (returned by crx function)
type CrxPluginArray = [
  pluginOptionsProvider,
  pluginBackground,
  pluginContentScripts,
  pluginDeclaredContentScripts,
  pluginDynamicContentScripts,
  pluginFileWriter,
  pluginFileWriterPublic,
  pluginFileWriterPolyfill,
  pluginHtmlInlineScripts,
  pluginWebAccessibleResources,
  pluginContentScriptsCss,
  pluginHMR,
  pluginManifest,
  pluginPrint
];

Plugin Responsibilities:

Options Provider: Manages plugin configuration and options
Background: Handles background script processing and service workers
Content Scripts: Manages content script injection and processing
File Writer: Handles file output and development server integration
HMR: Provides hot module replacement for extension development
Manifest: Processes and validates the extension manifest
Web Accessible Resources: Manages web-accessible resource declarations

Custom Plugin Extensions

Advanced users can extend the plugin system with custom CrxPlugin implementations.

interface CrxPlugin extends VitePlugin {
  /** 
   * Transform manifest during the transform hook
   * Filenames use input filenames
   */
  transformCrxManifest?(
    this: PluginContext,
    manifest: ManifestV3
  ): Promise<ManifestV3 | null | undefined> | ManifestV3 | null | undefined;
  
  /** 
   * Render manifest during generateBundle, before output
   * Filenames use output filenames
   */
  renderCrxManifest?(
    this: PluginContext,
    manifest: ManifestV3,
    bundle: OutputBundle
  ): Promise<ManifestV3 | null | undefined> | ManifestV3 | null | undefined;
  
  /** 
   * Transform content scripts during development
   * script.id is in Vite URL format
   */
  renderCrxDevScript?(
    code: string,
    script: CrxDevScriptId
  ): Promise<string | null | undefined> | string | null | undefined;
}

interface CrxDevScriptId {
  id: string;
  type: 'module' | 'iife';
}

Usage Example:

import { defineConfig } from "vite";
import { crx, defineManifest } from "@crxjs/vite-plugin";

const customPlugin: CrxPlugin = {
  name: 'custom-crx-plugin',
  transformCrxManifest(manifest) {
    // Modify manifest during transform
    return {
      ...manifest,
      description: `${manifest.description} (Custom Build)`,
    };
  },
  renderCrxDevScript(code, script) {
    // Add custom development code
    if (script.type === 'module') {
      return `// Custom dev code\n${code}`;
    }
    return code;
  },
};

export default defineConfig({
  plugins: [...crx({ manifest }), customPlugin],
});

Version

Tile

Files