Appearance

Where can I see if my routes are properly compiled for the frontend? ​

The racletteJS backend will, during startup, create a config file based on your plugins route configs. You can easily find that file in your plugin folder at ./plugins/YOURPLUGIN/frontend/generated-config.ts.

When the file changes: in development, generated-config.ts is rewritten on each backend server start (including restarts triggered by hot reload). In a production build, it is generated once at build time; a deployed app does not mutate this file at runtime.

How to define routes
typescript
import type { Static } from "@sinclair/typebox"
import type { FastifyReply, FastifyRequest } from "fastify"
import { Type } from "@sinclair/typebox"
import type { PluginFastifyInstance } from "@raclettejs/types"

const ParamsSchema = Type.Object({
  _id: Type.String(),
})
type Params = Static<typeof ParamsSchema>

export default (fastify: PluginFastifyInstance) => {
  const handler = async (
    req: FastifyRequest<{
      Params: Params
    }>,
    reply: FastifyReply,
  ) => {
    try {
      /* YOUR BUSINESS LOGIC */
    } catch (err: any) {
      fastify.log.error(err.message)
      return reply.internalServerError(err.message)
    }
  }

  return {
    handler,
    onRequest: [fastify.authenticate],
    config: {
      type: dataUpdate,
      broadcastChannels: ["exampleUpdated"],
    },
    schema: {
      summary: "Example example get Route",
      description: "Example example get Route",
      tags: ["myApp/example"],
      body: exampleBaseSchema,
    },
  }
}

What does that tell me? ​

This is an auto-generated plugin configuration produced by the backend.
It describes how a plugin communicates with the API, how data operations behave, and which real-time channels are emitted per operation.

🧠 Core Concept ​

Each plugin exposes:

  • metadata (plugin identity + routing)
  • entities (e.g. todo)
  • operations (CRUD + custom actions)
  • channels (real-time events emitted per operation)

📦 Top-Level Plugin Metadata ​

ts
pluginName: string
author: string
pluginKey: string
routePrefix: string
pluginPath: string

Meaning ​

  • pluginName → human-readable name of the plugin
  • author → plugin namespace owner
  • pluginKey → unique identifier used across frontend systems
  • routePrefix → base API route for all operations
  • pluginPath → internal filesystem path reference

🧩 Data Section ​

ts
data: {
  [entity]: {
    type: string
    operations: Record<string, Operation>
  }
}

Example:

ts
data.todo

Represents a domain entity (e.g. todos, users, posts).

⚙️ Operation Structure ​

Each operation defines how the frontend interacts with the backend.

ts
operation: {
  target: string | (payload) => string
  method: "get" | "post" | "patch" | "delete"
  storeActionType: string
  channels?: Channel[]
}

📡 Operation Types ​

1. Read Operations ​

getAll ​

ts
target: "/todo/all"
method: "get"
storeActionType: "dataRead"
  • Fetches full collection
  • No channels emitted

get ​

ts
target: (payload) => `/todo/${payload._id}`
method: "get"
storeActionType: "dataRead"
  • Fetches single entity by ID
  • Dynamic route based on payload

2. Write Operations ​

create ​

ts
method: "post"
storeActionType: "dataCreate"
  • Creates new entity
  • Emits real-time channels

update ​

ts
method: "patch"
storeActionType: "dataUpdate"
  • Updates existing entity
  • Emits update channels

delete ​

ts
method: "delete"
storeActionType: "dataDelete"
  • Deletes entity
  • Emits delete channels

🧩 Custom Operations ​

Example:

ts
updateCheckTask
deleteHard
  • Functionally identical to standard operations
  • Just custom backend endpoints
  • Fully integrated into $data

📡 Channels (Real-time Events) ​

Operations may define channels:

ts
channels: [
  {
    channel: "pacifico__example-todo--todoCreated",
    channelKey: "todoCreated",
    prefix: "pacifico__example-todo"
  }
]

Channel Fields ​

channel ​

  • Full backend-emitted event name
  • Scoped to plugin + entity + operation

channelKey ​

  • Normalized frontend event name
  • Used in $socket.on(...)

prefix ​

  • Namespace grouping

  • Helps distinguish:

    • plugin-specific events
    • global broadcast events

🔄 Channel Behavior Model ​

After a successful operation:

  1. Backend executes API call
  2. Backend emits channel event(s)
  3. Frontend receives via $socket
  4. UI reacts (refresh, update store, notify)

🧠 Key Takeaways ​

  • This config is fully backend-generated

  • It defines:

    • API endpoints (target)
    • HTTP behavior (method)
    • store integration (storeActionType)
    • real-time sync (channels)

  • Operations are automatically exposed to $data

  • Channels are automatically consumable via $socket

⚠️ Important Rule ​

  • Do not modify manually

  • It is the single source of truth for:

    • API structure
    • frontend data operations
    • real-time events