or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

client-api.mdcontent-scripts.mdfile-writer-system.mdindex.mdmanifest-definition.mdplugin-configuration.md
tile.json

content-scripts.mddocs/

Content Script Management

Automatic handling of content script injection, CSS processing, and web-accessible resource generation with support for different script formats and execution environments. Provides seamless integration between Vite's development features and Chrome's content script requirements.

Capabilities

Content Script Configuration

Interface for managing content script metadata and processing options.

interface ContentScript {
  /** Script format type - affects how the script is processed and injected */
  type: 'module' | 'iife' | 'loader';
  /** Unique identifier for the script */
  id: string;
  /** Reference ID linking to the original source */
  refId: string;
  /** Resolved file path after Vite processing */
  resolvedId?: string;
  /** Generated script identifier for runtime */
  scriptId?: string;
  /** Name of the loader file (for loader type scripts) */
  loaderName?: string;
  /** Output filename after build processing */
  fileName?: string;
  /** Whether this is a dynamically injected script */
  isDynamicScript?: boolean;
  /** Match patterns where this script should be injected */
  matches: string[];
  /** Associated CSS files for this content script */
  css?: string[];
}

Content Script Types:

  • module: ES module format with full HMR support and dynamic imports
  • iife: Immediately Invoked Function Expression for isolated execution
  • loader: Dynamic loader script that can inject other scripts at runtime

Content Script Processing Pipeline

The plugin automatically processes content scripts through several stages.

Development Processing:

  1. Source Analysis: Identifies content script files from manifest
  2. HMR Injection: Adds hot module replacement support
  3. CSS Processing: Extracts and processes associated CSS files
  4. Loader Generation: Creates dynamic loader scripts when needed
  5. Web Resource Registration: Registers files as web-accessible resources

Production Processing:

  1. Bundle Generation: Creates optimized script bundles
  2. Asset Optimization: Minifies and optimizes all assets
  3. Resource Mapping: Maps files to web-accessible resources
  4. Manifest Update: Updates manifest with final file references

Dynamic Content Script Injection

Support for runtime content script injection using Chrome's scripting API.

// Usage in background script
import scriptLoader from "./content-script.ts?script";

// Inject content script dynamically
chrome.scripting.executeScript({
  target: { tabId: tab.id },
  files: [scriptLoader], // Uses the generated loader file
});

Script Loading Formats:

// Different import formats for different use cases

// Default: ES module with loader and HMR
import contentScript from "./content.ts?script";

// Explicit loader format
import contentScriptLoader from "./content.ts?script&loader";

// IIFE format for isolated execution
import contentScriptIIFE from "./content.ts?script&iife";

// Pure ES module without loader
import contentScriptModule from "./content.ts?script&module";

CSS Processing for Content Scripts

Automatic handling of CSS files associated with content scripts.

CSS Injection Options:

// In vite.config.ts
export default defineConfig({
  plugins: [
    crx({
      manifest,
      contentScripts: {
        injectCss: true, // Default: automatically inject CSS
      },
    }),
  ],
});

CSS Processing Features:

  • Automatic Extraction: CSS files are automatically extracted from content scripts
  • Scoped Injection: CSS is injected only where the content script runs
  • HMR Support: CSS changes trigger hot updates in development
  • Web Resource Registration: CSS files are registered as web-accessible resources

Web-Accessible Resources Management

Automatic management of web-accessible resources for content scripts.

interface WebAccessibleResourceByMatch {
  matches: string[];
  resources: string[];
  use_dynamic_url?: boolean;
}

interface WebAccessibleResourceById {
  extension_ids: string[];
  resources: string[];
  use_dynamic_url?: boolean;
}

Automatic Resource Registration:

  • Content script files are automatically registered as web-accessible resources
  • CSS files used by content scripts are included
  • Dynamic imports and assets are tracked and registered
  • Match patterns are inherited from content script configuration

Content Script HMR (Hot Module Replacement)

Advanced HMR support specifically designed for Chrome extension content scripts.

HMR Features:

  • Live Updates: Content scripts update without page reload
  • State Preservation: Maintains script state during updates
  • Error Recovery: Graceful error handling and recovery
  • Connection Management: Manages HMR connections across extension contexts

HMR Configuration:

export default defineConfig({
  plugins: [
    crx({
      manifest,
      contentScripts: {
        hmrTimeout: 5000, // HMR connection timeout
        preambleCode: `
          console.log('Content script with HMR loaded');
          // Custom initialization code
        `,
      },
    }),
  ],
});

Advanced Content Script Patterns

Multi-World Content Scripts:

// Main world injection (interacts with page JavaScript)
import mainWorldScript from "./main-world.ts?script&module";

// Isolated world content script (default Chrome extension context)
import isolatedScript from "./isolated.ts?script";

// Background script coordination
chrome.scripting.executeScript({
  target: { tabId },
  files: [mainWorldScript],
  world: "MAIN", // Inject into main world
});

Conditional Content Script Loading:

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

const manifest = defineManifest(({ mode }) => ({
  manifest_version: 3,
  name: "Dynamic Extension",
  version: "1.0.0",
  content_scripts: [
    {
      matches: ["https://example.com/*"],
      js: ["src/content.ts"],
    },
    // Development-only content script
    ...(mode === "development" ? [{
      matches: ["<all_urls>"],
      js: ["src/debug-content.ts"],
    }] : []),
  ],
}));

Content Script Communication:

// In content script (content.ts)
/// <reference types="@crxjs/vite-plugin/client" />

// Optional execution callback with performance metrics
export const onExecute: ContentScriptAPI.ExecuteFn = (options) => {
  console.log(`Script injected in ${options.perf.injectTime}ms`);
  console.log(`Script loaded in ${options.perf.loadTime}ms`);
  
  // Initialize content script functionality
  initializeContentScript();
};

function initializeContentScript() {
  // Content script logic here
}

Content Script Best Practices

Performance Optimization:

  • Use lazy loading for heavy dependencies
  • Minimize initial script size
  • Leverage dynamic imports for code splitting
  • Use IIFE format for simple, isolated scripts

Security Considerations:

  • Always validate data from web pages
  • Use isolated execution contexts when possible
  • Be careful with main world injections
  • Sanitize any content inserted into the DOM

Development Workflow:

  • Use HMR for rapid development iteration
  • Monitor content script performance metrics
  • Test across different websites and scenarios
  • Validate web-accessible resource permissions