> ## Documentation Index
> Fetch the complete documentation index at: https://docs.vulpy.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Build features for the Vulpy WebUI

> Extend the Fox WebUI with new features, side-panel iframes, and custom pages under /extensions/, using the vulpy-commerce namespace rules.

The Fox WebUI in Vulpy Commerce can be extended with custom features, side-panel iframes, and standalone pages. This page explains the feature structure, namespace rules, and how to register new functionality so it loads correctly alongside the built-in features.

<Tip>
  **Ask Fox to build the feature.** Fox is a WebUI feature itself; it can scaffold new ones, wire manifests, and add iframe targets.

  Try prompts like:

  * "Scaffold a WebUI feature called `vulpy-commerce-order-monitor`."
  * "Add an iframe target for Grafana."
  * "Show me the current feature registry."
</Tip>

## Feature structure

WebUI features live under `extensions/hermes-webui/features/` and are bundled as a single manifest entry named `vulpy-commerce`. The built-in features are:

* `core`
* `welcome`
* `side-panel`
* `env-context`
* `env-actions`
* `profile-switcher`

Each feature folder exports its own init function and assets. The bundled manifest loads them together under the `vulpy-commerce` entry point.

## Namespace rules

To avoid collisions with other Vulpy products, follow these naming conventions:

* **Registry keys**: `vulpy-commerce.*`
* **CSS classes**: `vc-*`
* **Data attributes**: `data-vc-*`

These rules are mandatory. Using unscoped names may conflict with future Vulpy extensions.

## Add a new feature

<Steps>
  <Step title="Create the feature folder">
    Add a folder under `extensions/hermes-webui/features/<your-feature>/`.
  </Step>

  <Step title="Export a manifest entry">
    Export a manifest entry with your init function and any assets (scripts, styles, or templates) the feature needs.
  </Step>

  <Step title="Register in the bundled manifest">
    Add the feature to the bundled `vulpy-commerce` manifest so it loads after `vulpy-commerce-core`. The core feature initializes the shared registry and event bus.
  </Step>
</Steps>

## Add side-panel iframes

You can load external tools or custom pages in the WebUI side panel by setting the `VULPY_WEBUI_IFRAMES` environment variable. The value configures which URLs appear in the panel. See [Environment variables](/reference/env-vars) for the format.

## Add custom pages

Place HTML and JavaScript files under `pages/` in the extension directory. They are served through the `/extensions/` route in the WebUI. Use these pages for dashboards, tools, or reports that do not fit the side-panel model.

## Share state between features

Use the `window.VulpyCommerce` registry and the event bus provided by `vulpy-commerce-core`. Features can publish and subscribe to events, read shared configuration, and expose APIs for other features to call.

<Note>
  Fox writes to `/app/workspace`, which is bind-mounted from the host. Your feature edits are live on the host filesystem without requiring a container rebuild.
</Note>

<Warning>
  Do not ship secrets in extension pages. The WebUI is basic-auth-protected, but it is not a hardened public admin console. Treat it as an internal tool.
</Warning>

<CardGroup cols={2}>
  <Card title="Fox extensions" icon="puzzle" href="/fox/extensions">
    Learn how Fox loads and manages extensions in the Vulpy stack.
  </Card>

  <Card title="Fox WebUI" icon="browser" href="/fox/webui">
    Explore the WebUI layout, panels, and navigation model.
  </Card>
</CardGroup>