Appearance

Backend plugin overview ​

This page opens the Backend chapter in Plugin Development: what the raclette backend side of a plugin is, how it sits on Fastify, and which raclette-specific features you touch — without prescribing folder layouts (that is the Golden Path — Backend).

What lives in backend/ ​

The backend folder is optional for a plugin (you can ship frontend-only plugins). When it exists, it is loaded as a Fastify plugin scoped to your app: raclette gives you a plugin-scoped Fastify instance with extra APIs (models, payload, schemas, route prefixes, generation hooks, contracts, …).

Typical responsibilities:

  • HTTP routes — REST-style handlers your app and workbench call.
  • Services — business logic and integration (databases, external APIs).
  • Persistence — when you store data (today Mongoose/MongoDB; see Model for current and planned direction).
  • Payload + schemas — how data is shaped for the UI and for validation; see Helpers and Schema.

How this relates to Fastify ​

If you know Fastify: a raclette backend plugin is still a Fastify plugin function (instance, opts) => Promise<void>. You register routes with instance.register, instance.get / instance.post, etc., subject to raclette’s routing and prefix rules.

What raclette adds on top:

  • Consistent plugin and route namespacing so npm-installed plugins do not collide.
  • Payload and schema registration tied into the same pipeline the frontend uses.
  • Route metadata (config.type, config.broadcastChannels, …) consumed when generating frontend/generated-config.ts.
  • Plugin contracts and other extension points — see Plugin contracts and extension points (sidebar: Plugin Development → Backend → Advanced).

Registration flow (high level) ​

  1. raclette discovers your plugin and loads backend/index.ts (the only file the loader requires for the backend to exist).
  2. Your default export runs and registers routes, services, payload handlers, schemas, and related hooks.
  3. The framework records what you registered and can emit frontend generation metadata.

By default, each backend plugin is registered for frontend config generation after index.ts runs (empty options). Override or opt out only for special cases — see Frontend entity mapping.

You do not edit generated-config.ts by hand; it is produced from your backend registrations.

generated-config.ts lifecycle ​

  • Development — the file is regenerated whenever the backend server starts, which also means it is refreshed on hot reload when the dev server restarts. Treat it as volatile local output, not something you commit workflow state to by hand.
  • Production build — generation runs as part of the build; a built application does not rewrite this file at runtime. What shipped in the artifact stays fixed until the next deploy/build.

Where to go next ​