Asset Management
How plugins load and serve static assets (images, icons, data files) both in development and production.
usePluginResource Hook
Load a static asset bundled with your plugin:
import { usePluginResource } from '@opengpex/editor/core/context';
function MyPanel() {
const logoUrl = usePluginResource('visuals/logo.svg');
const docUrl = usePluginResource('docs/readme.pdf');
return <img src={logoUrl} alt="Logo" />;
}
How It Works
The hook resolves the path to: /api/plugins/serve/${pluginFolderName}/${relativePath}
The serve API then searches in order:
- Dynamic data directory:
data/plugins/user/${folderName}/${path} - Static source directory:
src/lib/opengpex/plugins/user/${folderName}/${path}
This dual-fallback means the same code works in development (Track 1) and production (Track 2) without any configuration changes.
Supported Asset Types
The serve API sets Content-Type from a built-in MIME map covering 20 formats (.js, .mjs, .css, .json, .png, .jpg, .jpeg, .gif, .webp, .avif, .svg, .ico, .woff, .woff2, .ttf, .otf, .pdf, .mp3, .mp4, .wasm); anything else falls back to application/octet-stream:
| Type | Extensions | Use Case |
|---|---|---|
| Images | .png, .jpg, .jpeg, .svg, .webp, .avif, .gif, .ico | Icons, thumbnails, overlays |
| Data | .json | Configuration, presets |
| Fonts | .woff2, .woff, .ttf, .otf | Custom typography |
| Documents | Help docs, guides | |
| Media | .mp3 (audio), .mp4 (video) | Sound clips, demo videos |
| Code | .js, .mjs, .css, .wasm | Plugin bundle, styles, WASM modules |
Note: .js and .mjs files also get on-the-fly import rewriting — bare-specifier imports (react, @opengpex/editor/*, ...) are rewritten to window.__GPEX__ lookups before serving.
Asset Directory Naming
Asset directories can use any name — the system does not restrict naming:
MyPlugin/
├── index.tsx
├── components.tsx
├── visuals/ # ✅ Any name works
│ └── logo.svg
├── icons/ # ✅ Multiple directories allowed
│ └── tool.png
└── data/
└── presets.json
All subdirectories are automatically included when packaging (pnpm pack-plugin).
Security
- Path traversal attempts (
../) are blocked by the serve API - Only files within the plugin's own directory are accessible
- No access to host system files or other plugins' directories
Next Steps
- Packaging & Distribution — ZIP structure details
- Plugin API Reference — All available hooks
- Your First Plugin — End-to-end tutorial
Last updated: 2026-07-30