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 auto-detects MIME types for 20+ formats:

Type	Extensions	Use Case
Images	.png, .jpg, .svg, .webp, .gif	Icons, thumbnails, overlays
Data	.json, .csv	Configuration, presets
Fonts	.woff2, .woff, .ttf	Custom typography
Documents	.pdf, .md	Help docs, guides
Audio	.mp3, .wav	Sound effects (rare)

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