plasmo-layout

v1.0.5

Published

11 days ago

Automate HTML layout generation for Plasmo browser extension components

0High
0Medium
0Low

plasmo plasmo-framework browser-extension layout html-generation cli

We're open to technical consulting and engineering partnerships and contract opportunities. Initiated with Love ❤️ from Biafra.

Overview

plasmo-layout is a CLI tool that automatically generates HTML files for Plasmo browser extension components. It scans your component files for @layout decorators and generates the corresponding HTML files that Plasmo uses to override default component HTML.

Features

🔍 Auto-discovery - Scans components for @layout('path') decorators
🎨 Multiple engines - Supports JSX, Edge.js, and custom templating engines
📁 Plasmo conventions - Follows Plasmo's HTML file naming conventions
👀 Watch mode - Incremental rebuilds on file changes
🧹 Clean command - Remove all generated files with one command
⚙️ Configurable - Flexible include/exclude patterns

Installation

npm install --save-dev plasmo-layout

Note: When installed as a dev dependency, use npx plasmo-layout to run commands. For global installation (npm install -g plasmo-layout), you can use plasmo-layout directly.

Peer Dependencies

Depending on which templating engine you use, install the corresponding peer dependency:

# For JSX layouts (default)
npm install react react-dom

# For Edge.js layouts
npm install edge.js

Quick Start

Initialize configuration (optional):
```
npx plasmo-layout init
```

Create a layout file in layouts/ directory:

// layouts/default.tsx
export default function DefaultLayout() {
  return (
    <html>
      <head>
        <title>My Extension</title>
      </head>
      <body>
        <div id="root"></div>
      </body>
    </html>
  );
}

Add @layout decorator to your Plasmo component:

// src/popup/index.tsx
// @layout('default')

export default function Popup() {
  return <div>Hello from Popup!</div>;
}

Run the build:
```
npx plasmo-layout build
```
This generates src/popup/popup.html based on your layout.

CLI Commands

`build`

Scan components and generate HTML files.

npx plasmo-layout build [options]

Options:
  -c, --config <path>   Path to config file
  -r, --root <path>     Project root directory (default: cwd)
  -v, --verbose         Enable verbose logging

`watch`

Watch for file changes and rebuild incrementally.

npx plasmo-layout watch [options]

Options:
  -c, --config <path>   Path to config file
  -r, --root <path>     Project root directory (default: cwd)
  -v, --verbose         Enable verbose logging

`clean`

Remove all generated HTML files.

npx plasmo-layout clean [options]

Options:
  -c, --config <path>   Path to config file
  -r, --root <path>     Project root directory (default: cwd)
  -d, --dry-run         Show what would be deleted
  -v, --verbose         Enable verbose logging

`init`

Create a default configuration file.

npx plasmo-layout init [options]

Options:
  -r, --root <path>     Project root directory (default: cwd)
  -t, --typescript      Create TypeScript config file

Configuration

Create a plasmo-layout.config.js (or .ts, .mjs, .cjs) file in your project root:

/** @type {import('plasmo-layout').PlasmoLayoutConfig} */
export default {
  // Glob patterns for files to scan
  include: ['src/**/*.{tsx,jsx}'],
  
  // Glob patterns to exclude
  exclude: [
    '**/node_modules/**',
    '**/.git/**',
    '**/dist/**',
    '**/build/**',
  ],
  
  // Directory containing layout templates
  layoutsDir: 'layouts',
  
  // Templating engine: 'jsx' | 'edge' | 'custom'
  engine: 'jsx',
  
  // Enable verbose logging
  verbose: false,
};

Custom Engine

To use a custom templating engine:

// plasmo-layout.config.js
export default {
  engine: 'custom',
  customEngine: {
    path: './my-custom-engine.js',
  },
};

Your custom engine must implement the CustomEngine interface:

// my-custom-engine.js
export default {
  name: 'my-engine',
  extensions: ['.myext'],
  
  async render(templatePath, context) {
    // Read template, process it, return HTML string
    return '<html>...</html>';
  },
  
  // Optional hooks
  async initialize() {},
  async cleanup() {},
};

Layout Path Resolution

The @layout decorator uses dot notation to specify layout paths:

| Decorator | Resolved Path | | ----------------------------------- | ------------------------------------------ | | @layout('default') | layouts/default.{tsx,jsx} | | @layout('tabs.onboarding') | layouts/tabs/onboarding.{tsx,jsx} | | @layout('admin.dashboard.main') | layouts/admin/dashboard/main.{tsx,jsx} |

Output Naming Convention

Following Plasmo conventions:

| Component Path | Generated HTML | | ------------------------- | ---------------------------- | | src/popup/index.tsx | src/popup/popup.html | | src/popup.tsx | src/popup.html | | src/options/index.tsx | src/options/options.html | | src/tabs/settings.tsx | src/tabs/settings.html |

Generated File Tracking

Generated HTML files include a special comment header:

<!-- GENERATED BY PLASMO-LAYOUT - DO NOT EDIT MANUALLY -->

This allows the clean command to identify and remove only generated files.

Programmatic API

You can also use plasmo-layout programmatically:

import { loadConfig, executeBuild, executeClean, executeWatch } from 'plasmo-layout';

// Load configuration
const config = await loadConfig('./my-project');

// Run build
const summary = await executeBuild(config);
console.log(`Generated ${summary.successCount} files`);

// Run clean
const cleanResult = await executeClean(config);

// Start watch mode
const watcher = await executeWatch(config, {
  onProcessComplete: (file, success) => {
    console.log(`Processed: ${file}, Success: ${success}`);
  },
});

// Later: stop watching
await watcher.stop();

Troubleshooting

Command not found: plasmo-layout

If you get sh: plasmo-layout: command not found, this usually means:

Using local installation incorrectly: When installed as a dev dependency (npm install --save-dev plasmo-layout), you must use npx:
```
npx plasmo-layout build
```
Package not built: Ensure the package is properly built and the dist folder exists:
```
npm run build
```
Missing in node_modules: The package wasn't installed correctly:
```
rm -rf node_modules package-lock.json
npm install
```
Global installation: If you prefer using plasmo-layout directly without npx, install globally:
```
npm install -g plasmo-layout
```

Package scripts alternative

You can also add npm scripts to your package.json:

{
  "scripts": {
    "layout:build": "plasmo-layout build",
    "layout:watch": "plasmo-layout watch",
    "layout:clean": "plasmo-layout clean"
  }
}

Then run: npm run layout:build

License

This Project is MIT Licensed