Golden Path — Widgets

Widgets are how your plugin appears in the workbench composition editor and in the running app. Raclette enforces a folder contract; everything inside the Vue component is up to you (see Vue structure).

For usePluginApi, i18n, and generated-config, see How to use — not repeated here.

Folder contract (required)

Piece	Rule
Path	frontend/widgets/<WidgetFolder>/
Component	<WidgetFolder>Widget.vue (name must end with Widget.vue)
Catalog	setup.ts with details + config

Full plugin tree (atoms diagram):

exampleCreator__examplePlugin/
├── raclette.plugin.ts            # Main plugin configuration 
├── frontend/                     # Frontend-side code (if frontendDir specified)
│   ├── [...]                     # See plugin metadata for more
│   └── widgets/                  # Plugin widgets
│       ├── Example/           # Your custom Widget folder name 
│       │   ├── ExampleWidget.vue    # The widget File. Needs to follow this structure "[CustomName]Widget.vue"
│       │   ├── setup.ts          # Contains details and config for the widget
│       │   └── [...] 
│       └── [...] 
└── backend/                      # Server-side code (if backendDir specified)
    ├── index.ts                  # Server entry point
    ├── example.model.ts     # The model for your dataType. Currently mongoose
    ├── example.schema.ts    # The schema for your dataType. Fastify schema, validations etc
    ├── example.service.ts   # The services for your dataType ie the actuall backend business logic         
    ├── routes/                   # API routes
    └── helpers/                  # Business logic helpers and utils

Details of raclette.plugin.ts

setup.ts (required shape)

import type { WidgetDeclaration } from "@raclettejs/core"

export const details = {
  title: "My Example Widget",
  color: "#6CB5D1",
  icon: new URL("./icon.svg", import.meta.url).href,
  images: [new URL("./screenshot.png", import.meta.url).href],
  description: "An example widget",
} satisfies WidgetDeclaration

const config = {}

export default {
  config,
  details,
}

Add config entries with Vue PropType and an editor block so workbench admins can tune props without redeploying.

*Widget.vue — entry file only

The widget file should wire the feature: usePluginApi(), props, i18n, and child components. Move presentation to components/ and logic to composables/ when the widget grows.

Fuller template: Widget Vue entry — cooking step.

Props from the orchestrator

Source	Role
Workbench config / public	From setup.ts editors
slotParams	From URL for this slot — declare matching prop names
Context	compositionName, slotType, uuid

You do not parse the URL manually for standard params; see Reading URL state.

Test in workbench

1. yarn dev with workbench (local URLs).
2. Compositions — add your widget to a layout.
3. Interaction links — deep links with query params.
4. Open the portal frontend on the resulting URL.

If the widget is missing from the picker: check folder name, *Widget.vue suffix, and plugin load (npm or local plugins/).

Loading (framework-internal)

Raclette detects when widget slots have rendered (including async chunk loads) before revealing content. You do not need to call readiness hooks, set data attributes, or branch on slotType.

Surface	What you see
Page navigation	Top progress bar; page content stays hidden until slots are ready
Modal	Local loading overlay on the modal until modal slots are ready
Inline (app bar, user menu)	No global loading — widgets load in place

Widget-owned loading UI inside the slot (skeletons, spinners) is fine and does not replace the framework overlay or progress bar.

Failed widgets do not block the page

If a widget fails to load or throws during setup, raclette renders ErrorWidgetState in that slot. The slot is treated as ready so navigation loading and modals are not stuck waiting on a broken widget. Other widgets on the same page still load normally.

Fix the plugin error and refresh; you do not need to change orchestrator code for this behavior.

See also

• Vue structure
• How to use — usePluginApi