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/).

See also

• Vue structure
• How to use — usePluginApi