Appearance

Golden Path — Model (*.model.ts) ​

Current stack ​

Today, raclette’s first-class persistence story in plugins is MongoDB via Mongoose. Model modules define documents and export a factory such as createModels(fastify) so collection naming stays consistent with the plugin and framework conventions.

Direction: we plan a more dynamic database layer over time. SurrealDB is one technology we are evaluating for teams who want a different operational model than classic NoSQL — there is no release date yet. Until then, treat Mongoose as the supported path; the same Golden Path ideas (factory + plugin-scoped registration) should carry over with new APIs.

Annotated “small” model (explained) ​

Below is a shortened model file with comments. For a full copy-paste template, use the cooking-step model.

typescript
/**
 * Model module (Mongoose today)
 *
 * Role:
 * - Define how documents are stored (fields, indexes, hooks).
 * - Export a factory (here: createModels) so the plugin index can create
 * prefixed models via fastify.createModel / your plugin conventions.
 *
 * This snippet is intentionally smaller than the full cookbook file: it
 * highlights structure. For a complete copy-paste template, use the
 * cooking-step "model" page linked from the Golden Path model doc.
 */
import type { PluginFastifyInstance } from "@raclettejs/core"
import { Schema } from "mongoose"

export const createModels = (fastify: PluginFastifyInstance) => {
  const exampleSchema = new Schema(
    {
      _id: { type: String, required: true },
      name: { type: String, required: true },
      // …other fields
    },
    { timestamps: true },
  )

  return {
    example: fastify.createModel("example", exampleSchema),
  }
}

Responsibilities ​

  • Define the stored shape for one persistence-backed concept.
  • Export a small factory used from the plugin index.ts (see Plugin index.ts).
  • Keep indexes, migrations, or collection-specific notes next to the model when needed.

Timestamps, tags, and payload alignment ​

For every model that flows to the UI through payload, plan for:

  • createdAt and updatedAt — add them to the schema now. We intend to auto-fill missing timestamp fields for common cases when the new database layer lands, but until that ships you should always define and maintain them on the model so list/detail views and other plugins see consistent rows.
  • tags: string[] — treat an array field as the default so rows can participate in cross-plugin or user-centric workflows (filtering, collections, automation) without schema forks.

These fields are called out again from the payload perspective in Helpers — payload field conventions.

Cookbook example (full file) ​

The cooking-step guide keeps the variableized model in one place (with its own frontmatter). Open it directly so we do not embed a second YAML block into this page:

See also ​