Plasmo Layout

Automate HTML layout generation for Plasmo browser extension components.

> 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

``bash
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.

$3

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

`bash


For JSX layouts (default)

npm install react react-dom

For Edge.js layouts

npm install edge.js
`

Quick Start

1. Initialize configuration (optional):

`bash
npx plasmo-layout init
`
2. Create a layout file in layouts/ directory:

`jsx
// layouts/default.tsx
export default function DefaultLayout() {
return (










);
}
`
3. Add @layout decorator to your Plasmo component:

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

export default function Popup() {
return

;
}
`
4. Run the build:

`bash
npx plasmo-layout build
`

This generates src/popup/popup.html based on your layout.

CLI Commands

$3

Scan components and generate HTML files.

`bash
npx plasmo-layout build [options]

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

$3

Watch for file changes and rebuild incrementally.

`bash
npx plasmo-layout watch [options]

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

$3

Remove all generated HTML files.

`bash
npx plasmo-layout clean [options]

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

$3

Create a default configuration file.

`bash
npx plasmo-layout init [options]

Options:
-r, --root 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:

`javascript
/* @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,
};
`

$3

To use a custom templating engine:

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

Your custom engine must implement the CustomEngine interface:

`typescript
// my-custom-engine.js
export default {
name: 'my-engine',
extensions: ['.myext'],

async render(templatePath, context) {
// Read template, process it, return HTML string
return '...';
},

// 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:

`html

`

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

Programmatic API

You can also use plasmo-layout programmatically:

`typescript
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

$3

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

1. Using local installation incorrectly: When installed as a dev dependency (npm install --save-dev plasmo-layout), you must use npx:
`bash
npx plasmo-layout build
`

2. Package not built: Ensure the package is properly built and the dist folder exists:
`bash
npm run build
`

3. Missing in node_modules: The package wasn't installed correctly:
`bash
rm -rf node_modules package-lock.json
npm install
`

4. Global installation: If you prefer using plasmo-layout directly without npx, install globally:
`bash
npm install -g plasmo-layout
`

$3

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

`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