DocsPlugins

Plugins Guide

Extend Lunx with official and community plugins. Plugins hook into the build lifecycle via five Rust-orchestrated lifecycle hooks to modify, transform, and enhance your build.

Plugin basics

Install a plugin package and add it to the plugins array in lunx.config.ts. Plugins run in declaration order. Most official plugins accept an options object for fine-grained configuration.

bash

npm install --save-dev @lunx/plugin-compress @lunx/plugin-pwa @lunx/plugin-env

typescriptlunx.config.ts

import { defineConfig }  from 'lunx'
import env               from '@lunx/plugin-env'
import compress          from '@lunx/plugin-compress'
import pwa               from '@lunx/plugin-pwa'

export default defineConfig({
  framework: 'react',
  plugins: [
    env({ schema: './src/env.schema.ts' }),
    compress({ algorithm: 'brotli', threshold: 1024 }),
    pwa({ name: 'My Lunx App', themeColor: '#2563eb' }),
  ],
})

Official plugins

@lunx/plugin-env

Schema-validated environment variables. Limits browser exposure to LUNX_PUBLIC_ prefix to prevent backend secret leaks.

@lunx/plugin-pwa

Automates service worker generation, offline caching, and PWA manifest injection. Zero-config compliance.

@lunx/plugin-compress

Native Brotli and Gzip compression via parallelized Rust threads. Reduces transfer size by up to 85%.

@lunx/plugin-svg

Import SVG files as React/Vue components with full TypeScript types and SVGO optimization.

@lunx/plugin-icons

On-demand icon bundling from Iconify (100,000+ icons). Only the icons you use are bundled.

@lunx/plugin-image

Automatic image optimization: WebP conversion, responsive srcsets, and lazy loading attributes.

@lunx/plugin-mock

Intercept API calls in development with type-safe mock handlers. Zero production overhead.

@lunx/plugin-inspect

Interactive build inspector at /__lunx_inspect__. Visualize module graph and transformation pipeline.

@lunx/plugin-checker

TypeScript type checking and ESLint diagnostics streamed into the dev server overlay in real time.

@lunx/plugin-legacy

Generate a legacy bundle targeting IE11 and older browsers using @babel/preset-env as a parallel output.

@lunx/plugin-auto-import

Auto-import React, Vue composition APIs, utilities, and component libraries without explicit import statements.

Plugin lifecycle hooks

Hook	When it runs	Use case
resolveId()	Module resolution phase	Redirect imports to virtual modules or alternative paths
load()	Module loading phase	Load module content from a custom source (virtual modules)
transform()	Compilation phase	Modify source code — strip logs, inject metadata, transpile DSLs
generateBundle()	After bundling, pre-write	Modify or add output chunks and assets
closeBundle()	After files are written	Post-build tasks — upload assets, send notifications

Plugin sandboxing

Lunx enforces a strict permission sandbox for all plugins. Third-party plugins must declare required permissions in their package.json. Undeclared access is blocked and logged.

jsonplugin/package.json

{
  "name": "my-lunx-plugin",
  "lunx": {
    "permissions": [
      "fs:read",          // read files from the project directory
      "fs:write:dist",    // write files to the output directory only
      "network:fetch"     // make outbound HTTP requests
    ]
  }
}

bash

# Audit permissions of all installed plugins
lunx security plugins

🛡 Plugin audit...
  @lunx/plugin-compress  — permissions: none (safe)
  @lunx/plugin-pwa       — permissions: fs:write:dist (expected)
  some-third-party-plugin — permissions: fs:write:/ (!) BLOCKED
  → Remove or review: some-third-party-plugin

Third-party plugin supply chain

Always run lunx security plugins after installing any third-party plugin. A plugin with fs:write:/ access could overwrite arbitrary files outside your project directory.

PreviousSBOM Guide Nextplugin-env