Redirected from /gitlab_raclettejs/docs
racletteJS

https://gitlab.com/raclettejs/core-dev
Admin
Documentation for racletteJS, an open-source fullstack web framework for building modular SaaS...
Tokens:112,243
Snippets:1,141
Trust Score:7.5
Update:1 month ago
Show doc for...
Tokens:
Raw
### Install and start the core development environment

Source: https://gitlab.com/raclettejs/core-dev/-/blob/main/README.md

This command sequence installs the core development environment. It clones the repository, sets up Yarn, configures local files, installs workspace and other dependencies, builds, and starts the dev stack. The `yarn :dev` command may need to be run twice due to timing issues, and `yarn :down` stops the dev server and removes containers.

```sh
$ git clone git@gitlab.com:raclettejs/core-dev.git
$ cd core-dev
$ npm install --global yarn # if you don't have it yet globally
$ git update-index --assume-unchanged package.json .yarnrc.yml    # avoid hassle with yarn magick 
$ yarn set version stable   # set yarn version for project, does some installations and .yarnrc.yml editing
$ yarn install              # @raclettejs/* workspaces (root lockfile)
$ yarn :install             # other deps: core services, create-raclette-app, @docs
$ yarn :build               # optional before release; not required for :dev
$ yarn :dev                 # start playground dev stack; may need to be done twice
$ yarn :down                # stop dev server, delete containers, recommended to do before each yarn :dev
```

--------------------------------

### Real Usage Example with $data, $socket, and $eventbus

Source: https://gitlab.com/raclettejs/core-dev/-/blob/main/@docs/compiled-docs/docs/guides/howto/FAQ/dataApi.md

Complete example combining data fetching, mutation, and real-time sync with snackbar notification.

```ts
const { $data, $socket, $eventbus } = usePluginApi()

const { data, execute } = $data.todo.getAll({
  params: { isDeleted: false },
  options: { immediate: true },
})

const { execute: createTodo } = $data.todo.create({
  options: { cb: () => execute() },
})

$socket.on("todoDeleted", () => {
  $eventbus.global.emit("ui/addToSnackbar", {
    message: "Todo deleted",
    color: "yellow",
  })

  execute()
})
```

--------------------------------

### Create example service

Source: https://gitlab.com/raclettejs/core-dev/-/blob/main/@docs/compiled-docs/docs/examples/cooking-steps/backend/snippets/wrappers/backendIndexDatatypeWrapper.md

Creates the example service using the models created earlier. The service depends on the example model.

```typescript
const exampleService = createExampleService(models.example)
```

--------------------------------

### Install dependencies from repository root

Source: https://gitlab.com/raclettejs/core-dev/-/blob/main/@docs/compiled-docs/docs/introduction/core-monorepo-for-maintainers.md

Run these commands in order from the repository root to install dependencies. `yarn install` installs `@raclettejs/*` workspaces from the root lockfile. `yarn :install` installs everything else (backend, frontend, create-raclette-app, docs). `yarn :build` is optional for day-to-day dev but required before releases.

```bash
yarn install
yarn :install
yarn :build # optional for day-to-day dev; required before releases / :release:prepare
```

--------------------------------

### Complete raclette.plugin.js example

Source: https://gitlab.com/raclettejs/core-dev/-/blob/main/@docs/compiled-docs/docs/plugin-development/metadata.md

A comprehensive example of a raclette.plugin.js file, showing the plugin's metadata, dependencies, options, and lifecycle hooks (beforeMount, mounted, beforeUnmount).

```javascript
export default {
  name: "advanced-canvas",
  author: "Canvas Team",
  version: "1.2.0",
  description:
    "Advanced canvas plugin with collaborative features and real-time synchronization",
  repository: "https://github.com/canvas-team/advanced-canvas",
  license: "MIT",

  // Plugin dependencies
  dependencies: ["websocket-manager", "user-authentication"],

  // Plugin configuration
  options: {
    maxCanvasSize: { width: 5000, height: 5000 },
    enableRealTimeSync: true,
    defaultZoomLevel: 1.0,
    supportedFormats: ["png", "jpg", "svg"],
    collaboration: {
      maxUsers: 50,
      cursorsVisible: true,
      enableChat: true,
    },
  },

  // Lifecycle hooks
  hooks: {
    beforeMount: async (app) => {
      console.log("Setting up canvas environment...")

      // Initialize canvas utilities
      await initializeCanvasUtils()

      // Setup global styles
      injectCanvasStyles()
    },

    mounted: async (app) => {
      console.log("Canvas plugin mounted successfully")

      // Register global canvas components
      app.component("GlobalCanvas", CanvasComponent)

      // Start background services
      startCanvasServices()
    },

    beforeUnmount: async (app) => {
      console.log("Cleaning up canvas resources...")

      // Stop background services
      stopCanvasServices()

      // Clear canvas cache
      clearCanvasCache()
    },
  },
}
```

--------------------------------

### Register example schemas

Source: https://gitlab.com/raclettejs/core-dev/-/blob/main/@docs/compiled-docs/docs/examples/cooking-steps/backend/snippets/wrappers/backendIndexDatatypeWrapper.md

Registers the example schemas with the Fastify instance.

```typescript
registerExampleSchemas(fastify)
```

--------------------------------

### Basic usePluginApi() destructuring in setup()

Source: https://gitlab.com/raclettejs/core-dev/-/blob/main/@docs/compiled-docs/docs/plugin-development/frontend/how-to/use-plugin-api.md

Call usePluginApi() inside a plugin Vue setup() to get runtime API references. The component must belong to a registered plugin.

```typescript
const { $data, $store, $i18n, $socket, $log, $user } = usePluginApi()
```

--------------------------------

### Start local development with yarn dev

Source: https://gitlab.com/raclettejs/core-dev/-/blob/main/@docs/compiled-docs/docs/introduction/how-raclette-works.md

Starts the racletteJS development environment. Generates the .raclette folder, starts Docker containers, and attaches to service logs in the same terminal. First run takes longer due to dependency installation.

```bash
yarn dev
```

--------------------------------

### Query action ID example

Source: https://gitlab.com/raclettejs/core-dev/-/blob/main/@docs/compiled-docs/docs/guides/howto/FAQ/storeApi.md

Example of a generated query action ID.

```text
plugin-pacifico__example-todo-116-todo-getAll-sD9o
```

--------------------------------

### Real usage example with $log and $eventbus

Source: https://gitlab.com/raclettejs/core-dev/-/blob/main/@docs/compiled-docs/docs/guides/howto/FAQ/socketApi.md

Shows a real usage example that logs the payload, emits a custom snackbar notification via $eventbus, and refreshes data on both 'todoCreated' and 'todoDeleted' events.

```typescript
$socket.on("todoCreated", (payload) => {
  $log("todoCreated", payload)

  execute() // refetch data
})

$socket.on("todoDeleted", (payload) => {
  $log("todoDeleted", payload)

  $eventbus.global.emit("ui/addToSnackbar", {
    message: "My custom notification next to the default core 'delete' notification",
    color: "yellow",
  })

  execute()
})
```

--------------------------------

### Start development environment with yarn dev

Source: https://gitlab.com/raclettejs/core-dev/-/blob/main/@docs/compiled-docs/docs/introduction/cli-commands.md

Starts the local development environment using Docker Compose. Use --filter to limit log output to specific services.

```bash
yarn dev --filter frontend
```

--------------------------------

### Example index.ts for backend plugin

Source: https://gitlab.com/raclettejs/core-dev/-/blob/main/@docs/compiled-docs/docs/plugin-development/golden-path/backend/overview.md

Example TypeScript code for the backend plugin's index.ts, importing types and registration functions, and defining the plugin function that registers routes, payload helpers, and example schemas.

```typescript
import type {
  PluginFastifyInstance,
  PluginOptions,
} from "@raclettejs/core/backend"
import { registerRoutes } from "./routes"
import { registerPayload } from "./helpers/payload"
import { registerExampleSchemas } from "./example.schema"

const examplePlugin = async (
  fastify: PluginFastifyInstance,
  _opts: PluginOptions,
) => {
  await fastify.register((instance) => registerRoutes(instance))

  registerPayload(fastify)

  registerExampleSchemas(fastify)
}

export default examplePlugin
```

--------------------------------

### Reactivity example

Source: https://gitlab.com/raclettejs/core-dev/-/blob/main/@docs/compiled-docs/docs/guides/howto/FAQ/storeApi.md

Shows how mutations trigger reactive updates.

```typescript
const uiState = $store.getUiState()

$store.setUiState({ navigationOpen: true })

// uiState.value.navigationOpen updates automatically
```

--------------------------------

### Start mongosh and set FCV

Source: https://gitlab.com/raclettejs/core-dev/-/blob/main/@docs/compiled-docs/docs/guides/migrations/mongodb/migrating-mongodb-5-to-8-2.md

Starts mongosh and then checks and sets the feature compatibility version. The set command may require omitting 'confirm: true' on MongoDB 5.0 servers.

```bash
mongosh raclette
```

```javascript
> db.adminCommand({ getParameter: 1, featureCompatibilityVersion: 1 })
// expected: featureCompatibilityVersion: { version: 'x.y' }

> db.adminCommand({
  setFeatureCompatibilityVersion: "<VER>",
  confirm: true,
})
```

--------------------------------

### Register routes, payload, and example schemas

Source: https://gitlab.com/raclettejs/core-dev/-/blob/main/@docs/compiled-docs/docs/examples/cooking-steps/backend/snippets/wrappers/backendIndexMinimalWrapper.md

Minimal backend index flow using shared micro-calls. Registers routes, payload, and example schemas on the Fastify instance.

```typescript
await fastify.register((instance) => registerRoutes(instance))
```

```typescript
registerPayload(fastify)
```

```typescript
registerExampleSchemas(fastify)
```

--------------------------------

### getUiState example

Source: https://gitlab.com/raclettejs/core-dev/-/blob/main/@docs/compiled-docs/docs/guides/howto/FAQ/storeApi.md

Resolves to the path for the UI state.

```typescript
const uiState = $store.getUiState()
```

--------------------------------

### Define raclette.config.js

Source: https://gitlab.com/raclettejs/core-dev/-/blob/main/@docs/compiled-docs/docs/introduction/getting-started.md

Example configuration file that sets the app name and configures the Vue frontend with the vue-router plugin. Use this as a starting point for your own raclette.config.js.

```js
import { defineRacletteConfig } from "@raclettejs/core"

export default defineRacletteConfig({
  name: "raclette-dev",

  // Frontend framework configuration
  frontend: {
    framework: "vue",
    vue: {
      plugins: ["vue-router"],
    },
  },
})
```

--------------------------------

### Example: Logging a string with output

Source: https://gitlab.com/raclettejs/core-dev/-/blob/main/@docs/compiled-docs/docs/guides/howto/FAQ/logApi.md

Logs a string message and shows the console output, which includes the plugin prefix, title, and a JSON object with the message and timestamp.

```typescript
$log("hallo", "dings", 1)
```

```text
plugin/<plugin-name> - hallo

{
  message: "dings",
  dateTime: "21.04.2026 - 17:30:40:615"
}
```

--------------------------------

### Default seed file paths for compositions and interaction links

Source: https://gitlab.com/raclettejs/core-dev/-/blob/main/@docs/compiled-docs/docs/guides/migrations/upgrading-0.1-to-0.2.md

Default seed files to ship under the app root. These are installable from the workbench via Project → install default config.

```text
<app>/config/compositions.js
<app>/config/interactionLinks.js
```

--------------------------------

### Install ESLint dependencies with yarn

Source: https://gitlab.com/raclettejs/core-dev/-/blob/main/@docs/compiled-docs/docs/directory-structure/eslint-config.md

Install the required dependencies before using the ESLint configuration. These ensure support for modern linting patterns, Prettier integration, and framework-specific rules (Vue/React).

```bash
yarn add -D @eslint/js eslint eslint-config-prettier eslint-plugin-import eslint-plugin-prefer-arrow-functions eslint-plugin-prettier eslint-plugin-vue globals prettier typescript-eslint vue-eslint-parser
```

--------------------------------

### beforeMount lifecycle hook

Source: https://gitlab.com/raclettejs/core-dev/-/blob/main/@docs/compiled-docs/docs/plugin-development/metadata.md

Called before the plugin is mounted to the application. Use for pre-mount setup.

```javascript
hooks: {
  beforeMount: async (app) => {
    console.log("Plugin is about to be mounted")
    // Perform pre-mount setup
  }
}
```

--------------------------------

### getQueryState example

Source: https://gitlab.com/raclettejs/core-dev/-/blob/main/@docs/compiled-docs/docs/guides/howto/FAQ/storeApi.md

Resolves to the path for a query's state.

```typescript
const queryState = $store.getQueryState(actionId)
```

--------------------------------

### Default cache configuration (all stacks on DB 0)

Source: https://gitlab.com/raclettejs/core-dev/-/blob/main/@docs/compiled-docs/reference/raclette-config.md

Typical setup requiring no explicit DB configuration; all stacks use the default database index 0.

```javascript
services: {
  cache: {
    enabled: true,
    port: 6379,
  },
}
```

--------------------------------

### updateConfig example

Source: https://gitlab.com/raclettejs/core-dev/-/blob/main/@docs/compiled-docs/docs/guides/howto/FAQ/storeApi.md

Updates the widget configuration.

```typescript
$store.updateConfig({ theme: "dark" })
```

--------------------------------

### Define TypeBox schemas and types for example resource

Source: https://gitlab.com/raclettejs/core-dev/-/blob/main/@docs/compiled-docs/docs/examples/cooking-steps/backend/plugin/schema.md

This snippet defines the TypeBox schemas for the example resource, including base, full, create, and update schemas, along with TypeScript types and a registration function. It uses @sinclair/typebox and mongoose, and registers schemas with the Fastify instance.

```typescript
import type { Static } from "@sinclair/typebox"
import type { Document } from "mongoose"
import { Type } from "@sinclair/typebox"
import { PluginFastifyInstance } from "@raclettejs/core"

/**
 * Base Example Schema - Fields common to all operations
 */
const baseExampleSchema = {
  name: Type.String(),
  content: Type.Optional(Type.String()),
  tags: Type.Optional(Type.Array(Type.String(), { default: [] })),
  owner: Type.String(),
  lastEditor: Type.Optional(Type.String()),
  isDeleted: Type.Optional(Type.Boolean({ default: false })),
}

/**
 * Full Example Schema - Used for response serialization and database model
 */
export const exampleSchema = Type.Object(
  {
    _id: Type.String(),
    ...baseExampleSchema,
    createdAt: Type.String({ format: "date-time" }),
    updatedAt: Type.String({ format: "date-time" }),
  },
  {
    $id: "#example/base",
    title: "core/example",
  },
)

/**
 * Example Create Schema - For POST operations
 */
export const exampleCreateSchema = Type.Object(
  {
    _id: Type.Optional(Type.String()),
    ...baseExampleSchema,
  },
  {
    $id: "#example/create",
    title: "core/example-create",
  },
)

/**
 * Example Update Schema - For PATCH operations
 */
export const exampleUpdateSchema = Type.Object(
  {
    name: Type.Optional(Type.String()),
    tags: Type.Optional(Type.Array(Type.String())),
    lastEditor: Type.Optional(Type.String()),
    isDeleted: Type.Optional(Type.Boolean()),
  },
  {
    $id: "#example/update",
    title: "core/example-update",
  },
)

/**
 * Type Utilities
 */

type DateTimeFields = {
  createdAt: Date
  updatedAt: Date
}

type RawExample = Static<typeof exampleSchema>
export type Example = Omit<RawExample, keyof DateTimeFields> & DateTimeFields

type RawExampleCreate = Static<typeof exampleCreateSchema>
export type ExampleCreate = RawExampleCreate

type RawExampleUpdate = Static<typeof exampleUpdateSchema>
export type ExampleUpdate = RawExampleUpdate

export interface ExampleDoc
  extends Document<string, unknown, Example>, Example {
  _id: string
}
export type AnyExample = Example | ExampleDoc

/**
 * Register Schema/Type Generation for Shared Folder
 */
export const registerExampleSchemas = (fastify: PluginFastifyInstance) => {
  fastify.registerSchema({
    schema: exampleSchema,
    name: "Example",
  })

  fastify.registerSchema({
    schema: exampleCreateSchema,
    name: "ExampleCreate",
  })

  fastify.registerSchema({
    schema: exampleUpdateSchema,
    name: "ExampleUpdate",
  })
}
```

--------------------------------

### Start ephemeral Valkey with no persistence

Source: https://gitlab.com/raclettejs/core-dev/-/blob/main/@docs/compiled-docs/docs/guides/cache/migrate-ephemeral-auth-persistent-data.md

Command to run a Valkey server with persistence disabled, used for the new ephemeral cache service.

```text
valkey-server --save ""
```

--------------------------------

### Database Backup API Call (JSON)

Source: https://gitlab.com/raclettejs/core-dev/-/blob/main/@docs/compiled-docs/docs/official-plugins/cli-connector.md

Example API request to invoke the db-backup script.

```json
POST /run/db-backup
{
  "args": ["users"]
}
```

--------------------------------

### Single Valkey with rdb+aof persistence

Source: https://gitlab.com/raclettejs/core-dev/-/blob/main/@docs/compiled-docs/docs/examples/boilerplates/raclette.config.persistent-valkey.md

Typical customer setup: one Valkey, persistence on, plugin uses `fastify.cache`. Configures the cache service with port 6379, a volume, and backend persistence set to `rdb+aof` with RDB_OPTIONS.

```javascript
import { defineRacletteConfig } from "@raclettejs/core"

export default defineRacletteConfig({
  name: "my-app",
  services: {
    cache: {
      enabled: true,
      port: 6379,
      volume: "raclette-cache-data",
    },
  },
  backend: {
    cache: {
      persistence: "rdb+aof",
      RDB_OPTIONS: "3600 1 300 100 60 10000",
    },
  },
})
```

--------------------------------

### GET /jobs

Source: https://gitlab.com/raclettejs/core-dev/-/blob/main/@docs/compiled-docs/docs/official-plugins/cli-connector.md

Lists all known processes. Restricted to admin users.

```APIDOC
## GET /jobs

### Description
Lists all known processes. This endpoint is restricted to admin users.

### Method
GET

### Endpoint
/jobs

### Response
#### Success Response (200)
- **id** (string) - Job ID.
- **cmd** (string) - Command name.
- **argv** (array of strings) - Command arguments.
- **done** (number or string) - Completion status.

#### Response Example
[
  {
    "id": "123",
    "cmd": "backup-database",
    "argv": ["full"],
    "done": 0
  }
]
```

--------------------------------

### Map auth roles to instance ids - single persistent Valkey

Source: https://gitlab.com/raclettejs/core-dev/-/blob/main/@docs/compiled-docs/docs/guides/cache/valkey-instances.md

Example showing all auth roles (sessions, oauthState, providerTokens) mapped to the default 'cache' instance, requiring only services.cache and CACHE_URL.

```javascript
auth: {
  valkeyInstances: {
    sessions: "cache",
    oauthState: "cache",
    providerTokens: "cache",
  },
},
// Only services.cache + CACHE_URL; no second instance required.
```

--------------------------------

### Fully Controlled Example: actionId + id

Source: https://gitlab.com/raclettejs/core-dev/-/blob/main/@docs/compiled-docs/docs/guides/howto/FAQ/usePluginApi.md

Shows the combination of actionId and id to produce a fully controlled query ID. The result is 'plugin-pacifico__example-todo-todoList-archive'.

```typescript
const { $data } = usePluginApi({
  actionId: "todoList",
})

$data.todo.getAll({
  params: { isDeleted: true },
  id: "archive",
})
```

--------------------------------

### Channel mapping example

Source: https://gitlab.com/raclettejs/core-dev/-/blob/main/@docs/compiled-docs/docs/guides/howto/FAQ/socketApi.md

Shows the mapping between backend channels and frontend event names. The frontend uses only the logical event name (e.g., 'todoCreated') without the full channel string.

```text
| Backend Channel | Frontend Event |
| ------------------ | -------------- |
| `...--todoCreated` | `todoCreated`  |
| `...--todoUpdated` | `todoUpdated`  |
| `...--todoDeleted` | `todoDeleted`  |
```

--------------------------------

### File Listing API Call (JSON)

Source: https://gitlab.com/raclettejs/core-dev/-/blob/main/@docs/compiled-docs/docs/official-plugins/cli-connector.md

Example API request to invoke the safe-ls script.

```json
POST /script/safe-ls
{
  "args": ["documents"]
}
```

--------------------------------

### getWidgetState example

Source: https://gitlab.com/raclettejs/core-dev/-/blob/main/@docs/compiled-docs/docs/guides/howto/FAQ/storeApi.md

Resolves to the path for the current widget's state.

```typescript
const widgetState = $store.getWidgetState()
```

--------------------------------

### Example: Logging an object

Source: https://gitlab.com/raclettejs/core-dev/-/blob/main/@docs/compiled-docs/docs/guides/howto/FAQ/logApi.md

Logs an object message with title 'hallo' and level 1 (info).

```typescript
$log("hallo", { title: "test" }, 1)
```

--------------------------------

### Clone the RacletteJS core-dev repository

Source: https://gitlab.com/raclettejs/core-dev/-/blob/main/@docs/compiled-docs/docs/examples/cookbook.md

Use this command to download the monorepo and access the living code examples.

```bash
git clone https://gitlab.com/raclettejs/core-dev.git
```

--------------------------------

### POST /run/:cmd

Source: https://gitlab.com/raclettejs/core-dev/-/blob/main/@docs/compiled-docs/docs/official-plugins/cli-connector.md

Starts a long-running process and returns a job ID for interaction. Use for commands that take longer than a few seconds.

```APIDOC
## POST /run/:cmd

### Description
Starts a process and returns a job ID for interaction. Use this for commands that take longer than a few seconds.

### Method
POST

### Endpoint
/run/:cmd

### Parameters
#### Path Parameters
- **cmd** (string) - Required - The name of the script to run.

#### Request Body
- **args** (array of strings) - Optional - Command-line arguments.

### Request Example
{
  "args": ["full", "production"]
}

### Response
#### Success Response (201)
- **id** (number) - The job ID.

#### Response Example
123456

### Error Responses
- **404** - Script not found.
- **409** - Too many jobs running.
- **500** - Server error.
```

--------------------------------

### Map auth roles to instance ids - split ephemeral vs persistent

Source: https://gitlab.com/raclettejs/core-dev/-/blob/main/@docs/compiled-docs/docs/guides/cache/valkey-instances.md

Example mapping sessions and OAuth state to 'cache' and provider tokens to 'cachePersistent' for durable storage.

```javascript
auth: {
  valkeyInstances: {
    sessions: "cache",
    oauthState: "cache",
    providerTokens: "cachePersistent",
  },
},
```

--------------------------------

### Create and register example payload handler with @raclettejs/core

Source: https://gitlab.com/raclettejs/core-dev/-/blob/main/@docs/compiled-docs/docs/examples/cooking-steps/backend/plugin/helpers/pluginHelper.md

Defines two exported functions for a RacletteJS plugin: createexamplePayload calls fastify.createPayload to create a payload of type "example", and registerPayload registers a payload handler for the same type with displayName, completion, and fields callbacks. The fields callback sets owner to "NONE", uses requestData.project (non-null asserted), and an empty tags array.

```typescript
import {
  FrontendPayloadRequestData,
  PluginFastifyInstance,
} from "@raclettejs/core"
import { example } from "../example.schema"

export const createexamplePayload = async (
  fastify: PluginFastifyInstance,
  items: example[],
  requestData: FrontendPayloadRequestData,
) => {
  const res = await fastify.createPayload("example", items, requestData)
  return res
}

export const registerPayload = (fastify: PluginFastifyInstance) => {
  fastify.registerPayloadHandler<example>("example", {
    type: "example",
    displayName: (item) => item.name || "",
    completion: (item) => item.name || "",

    fields: (item, requestData: FrontendPayloadRequestData) => ({
      owner: "NONE",
      project: requestData.project!,
      tags: [],
    }),
  })
}
```

--------------------------------

### get Read Operation

Source: https://gitlab.com/raclettejs/core-dev/-/blob/main/@docs/compiled-docs/docs/guides/howto/FAQ/generatedConfig.md

Example of a `get` read operation that fetches a single entity by ID. The target is a dynamic route based on the payload.

```typescript
target: (payload) => `/todo/${payload._id}`
method: "get"
storeActionType: "dataRead"
```

--------------------------------

### create Write Operation

Source: https://gitlab.com/raclettejs/core-dev/-/blob/main/@docs/compiled-docs/docs/guides/howto/FAQ/generatedConfig.md

Example of a `create` write operation that creates a new entity. It emits real-time channels.

```typescript
method: "post"
storeActionType: "dataCreate"
```

--------------------------------

### Folder Structure: example-todo/

Source: https://gitlab.com/raclettejs/core-dev/-/blob/main/@docs/compiled-docs/docs/examples/recipes/settingUpATodoPlugin.md

The intended directory layout for the plugin, showing frontend and backend folders with their key files.

```plaintext
example-todo/
├── raclette.plugin.ts
├── frontend/
│    ├── index.ts
│    ├── components/
│    │    └── TodoComponent
│    └── widgets/
│        ├── TodoList/
│        ├── TodoListWidget.vue
│        ├── icon.svg
│        ├── screenshot.png
│        └── setup.ts
└── backend/
    ├── index.ts
    ├── todo.model.ts
    ├── todo.schema.ts
    ├── todo.service.ts
    ├── helpers/
    │    ├── index.ts
    │    └── todoHelper.ts
    └── routes/
        ├── index.ts
        └── route.todo.[action].ts
```

--------------------------------

### Install core packages with yarn

Source: https://gitlab.com/raclettejs/core-dev/-/blob/main/@docs/compiled-docs/docs/introduction/getting-started.md

Adds the required @raclettejs/core and recommended @raclettejs/workbench packages to your project. The workbench is strongly recommended for configuring users, compositions, and system data without raw database work.

```sh
yarn add @raclettejs/core @raclettejs/workbench
```

--------------------------------

### Assign service to Fastify instance

Source: https://gitlab.com/raclettejs/core-dev/-/blob/main/@docs/compiled-docs/docs/examples/cooking-steps/backend/snippets/wrappers/backendIndexDatatypeWrapper.md

Assigns the created example service to the Fastify instance under the custom property.

```typescript
fastify.custom.exampleService = exampleService
```

--------------------------------

### Fastify plugin entry point (async)

Source: https://gitlab.com/raclettejs/core-dev/-/blob/main/@docs/compiled-docs/docs/examples/cooking-steps/backend/snippets/micro/pluginEntryOpenDatatype.md

Defines an asynchronous Fastify plugin function `examplePlugin` with `fastify` typed as `PluginFastifyInstance` and `_opts` as `PluginOptions`. This is the standard entry signature for a plugin; `_opts` is unused (prefixed with underscore).

```typescript
const examplePlugin = async (
  fastify: PluginFastifyInstance,
  _opts: PluginOptions,
) => {
```

--------------------------------

### DataExporter Quick Start Template

Source: https://gitlab.com/raclettejs/core-dev/-/blob/main/@docs/compiled-docs/docs/guides/howto/FAQ/exporterUsage.md

Starter template for using DataExporter in a Vue component. The template is incomplete in the source; the full usage is not shown.

```vue
<template>
  
</template>
```

--------------------------------

### Initialize and register CLI commands

Source: https://gitlab.com/raclettejs/core-dev/-/blob/main/@docs/compiled-docs/docs/official-plugins/cli-connector.md

Sets up the plugin with a Fastify instance and registers a CLI command using registerScriptByConfig. This must be added to the backend part of the application.

```typescript
import type { PluginFastifyInstance } from "@raclettejs/core"
import {
  registerScriptByConfig,
  setupFastify,
} from "@raclettejs/plugin-cli-connector"

export const initializeCliCommands = (fastify: PluginFastifyInstance) => {
  // Initialize the plugin with the Fastify instance
  setupFastify(fastify)

  // Register your CLI commands here
  try {
    registerScriptByConfig("system-info", {
      exe: "/usr/bin/uname",
      args: ["-a"],
    })

    fastify.log.info("CLI commands registered successfully")
  } catch (error) {
    fastify.log.error("Failed to register CLI commands:", error)
    throw error
  }
}
```

--------------------------------

### With $socket (real-time sync)

Source: https://gitlab.com/raclettejs/core-dev/-/blob/main/@docs/compiled-docs/docs/guides/howto/FAQ/dataApi.md

Shows how to trigger a refetch when a socket event occurs.

```ts
$socket.on("todoCreated", () => {
  execute()
})
```

--------------------------------

### Move plugin snapshot code to persistent Valkey connection

Source: https://gitlab.com/raclettejs/core-dev/-/blob/main/@docs/compiled-docs/docs/guides/cache/migrate-ephemeral-auth-persistent-data.md

TypeScript example showing how to create a persistent cache service using the cachePersistent Valkey connection, replacing direct use of fastify.cache for upstream API payloads.

```ts
import { createCacheService } from "@m/cache/cacheManager"

const persistentStore = createCacheService(
  fastify.fastify.valkeys.cachePersistent,
  { prefix: pluginKey, defaultTtl: -1 },
)

// was: fastify.cache.get("feed")
await persistentStore.get("feed")
```

--------------------------------

### Service Injection Pattern

Source: https://gitlab.com/raclettejs/core-dev/-/blob/main/@docs/compiled-docs/docs/plugin-development/backend.md

Create a service instance and attach it to the fastify instance for use in route handlers. The example shows creating a todoService and using it in a route handler.

```typescript
// In plugin index.ts
const todoService = createTodoService(models.todo)
fastify.todoService = todoService

// In route handlers
const payload = await fastify.todoService.createTodo(/*...*/)
```

--------------------------------

### Minimal custom format example (CSV)

Source: https://gitlab.com/raclettejs/core-dev/-/blob/main/@docs/compiled-docs/docs/guides/howto/FAQ/customExporter.md

Shows the minimal structure for a custom export format, importing the ExportFormat type and defining a csvFormat export. The serialize function is not shown in the source.

```TypeScript
import type { ExportFormat } from "@raclettejs/core/orchestrator/composables"

type CsvItem = { id: string; name: string }

export const csvFormat: ExportFormat
```

--------------------------------

### config/compositions.js landing page seed

Source: https://gitlab.com/raclettejs/core-dev/-/blob/main/@docs/compiled-docs/docs/guides/migrations/upgrading-0.1-to-0.2.md

Example composition seed that defines a home page with a single widget. This is part of the landing page seeds to avoid a 404 after login.

```js
// config/compositions.js
export default [
  {
    _id: "home",
    pathname: { default: "home" },
    widgetsLayout: [
      [
        {
          column: 12,
          widget: {
            uuid: "main",
            name: "Main",
            pluginKey: "your__plugin-key",
          },
        },
      ],
    ],
  },
]
```

--------------------------------

### config/interactionLinks.js landing page seed

Source: https://gitlab.com/raclettejs/core-dev/-/blob/main/@docs/compiled-docs/docs/guides/migrations/upgrading-0.1-to-0.2.md

Example interaction link seed that marks a landing page. It imports the compositions file and references the first composition, setting isLandingPage to true.

```js
// config/interactionLinks.js
import compositions from "./compositions.js"

export default [
  {
    _id: "homeLink",
    composition: compositions[0]._id,
    slotType: "page",
    triggers: [
      {
        type: "page-navigation",
        settings: {
          icon: "mdi-home",
          title: { default: "Home" },
          sortOrder: 0,
          navigationBarType: "navItem",
        },
      },
    ],
    isLandingPage: true,
  },
]
```

--------------------------------

### ExampleService class and createExampleService factory

Source: https://gitlab.com/raclettejs/core-dev/-/blob/main/@docs/compiled-docs/docs/examples/cooking-steps/backend/plugin/service.md

Defines the ExampleService class with a constructor that takes a Mongoose model for the Example type. The class includes placeholder comments for business logic. The exported factory function createExampleService creates and returns a new instance of ExampleService.

```typescript
import type { Example, Example as ExampleType } from "./example.schema"
import type { QueryOptions } from "@_/types/service"
import { v4 as uuidv4, validate } from "uuid"
import { createTodoPayload } from "./helpers/exampleHelper"
import type {
  PluginFastifyInstance,
  FrontendPayload,
  FrontendPayloadRequestData,
} from "@raclettejs/core/types"
import { Model } from "mongoose"

export class ExampleService {
  private exampleModel: Model<Todo>

  constructor(model: Model<Example>) {
    this.exampleModel = model
  }
  // [...]
  /* YOUR BUSINESS LOGIC */
  // [...]
}

export const createExampleService = (model: Model<Example>) => {
  return new ExampleService(model)
}
```

--------------------------------

### Frontend fetch and axios with credentials

Source: https://gitlab.com/raclettejs/core-dev/-/blob/main/@docs/compiled-docs/docs/guides/migrations/upgrading-0.1-to-0.2.md

Custom fetch and axios clients that talk to the raclette backend must include cookies. The fetch example uses credentials: 'include', and the axios example uses withCredentials: true.

```ts
// fetch
fetch("/auth/session", { credentials: "include" })

// axios
axios.create({ withCredentials: true })
```

--------------------------------

### updateDataItem example

Source: https://gitlab.com/raclettejs/core-dev/-/blob/main/@docs/compiled-docs/docs/guides/howto/FAQ/storeApi.md

Updates a data item by UUID.

```typescript
$store.updateDataItem("uuid-123", { name: "Updated" })
```

--------------------------------

### Example AI Prompt for Building a racletteJS Plugin

Source: https://gitlab.com/raclettejs/core-dev/-/blob/main/@docs/compiled-docs/docs/coding-with-ai/introduction.md

Use this prompt to instruct an AI assistant to generate a racletteJS plugin based on the boilerplate. It specifies the required backend file structure, i18n key location, and that $store and $data pluginApi calls must remain in the *Widget.vue file.

```text
You are an expert vue3 and racletteJS developer with modern es6 approaches and vue3 best practices in mind:
I want to build a racletteJS plugin that [describes your feature].

I'm using the plugin boilerplate from
https://gitlab.com/raclettejs/core-dev/-/tree/main/@raclettejs/playground/plugins/raclette__boilerplate?ref_type=heads

Please reference the racletteJS documentation at
https://context7.com/gitlab_raclettejs/docs

Plese rewrite the backend files to fit the naming, model and schema structure discussed earlier. Locate all i18n keys in the index.ts of the frontend directory. Make sure that all $store and $data pluginApi calls stay in the *Widget.vue file. Provide all necessary contents to the respective child components.
```

--------------------------------

### updateWidgetState example

Source: https://gitlab.com/raclettejs/core-dev/-/blob/main/@docs/compiled-docs/docs/guides/howto/FAQ/storeApi.md

Merges the payload into the widget state.

```typescript
$store.updateWidgetState({ count: 1 })
```

--------------------------------

### Plugin Entry Point (index.ts)

Source: https://gitlab.com/raclettejs/core-dev/-/blob/main/@docs/compiled-docs/docs/plugin-development/backend.md

The main plugin file that orchestrates all components, registering models, services, routes, schemas, and helpers with the Fastify instance. It includes error handling for route registration and injects the todo service into the Fastify instance.

```typescript
import type { PluginOptions, PluginFastifyInstance } from "@_/types/plugins"
import { createModels } from "./todo.model"
import { registerRoutes } from "./routes"
import { registerPayload } from "./helpers/todoHelper"
import { registerTodoSchemas } from "./todo.schema"
import { registerTodoCrud } from "./helpers/crud"
import { createTodoService } from "./todo.service"

const todoPlugin = async (
  fastify: PluginFastifyInstance,
  opts: PluginOptions,
) => {
  // Create and register database models
  const models = createModels(fastify)

  // Initialize service layer
  const todoService = createTodoService(models.todo)
  fastify.todoService = todoService

  // Register routes with error handling
  try {
    await fastify.register((instance) => registerRoutes(instance, models, opts))
  } catch (error) {
    fastify.log.error(`Failed to register routes.`, error)
    throw error
  }

  // Register additional components
  registerPayload(fastify)
  registerTodoSchemas(fastify)
  registerTodoCrud(fastify)
}

export default todoPlugin
```

--------------------------------

### setUiState example

Source: https://gitlab.com/raclettejs/core-dev/-/blob/main/@docs/compiled-docs/docs/guides/howto/FAQ/storeApi.md

Sets the UI state with a payload.

```typescript
$store.setUiState({ navigationOpen: true })
```

--------------------------------

### Query endpoint with usePluginApi and $data.todo.getAll

Source: https://gitlab.com/raclettejs/core-dev/-/blob/main/@docs/compiled-docs/docs/examples/recipes/readingDataFromTheBackend.md

Defines the action and its outputs for reading data. The options object controls immediate execution, caching, store usage, notifications, and response type. Set immediate: false and use await execute() to await the retrieval.

```typescript
const { $data, [...] } = usePluginApi()
const {data, dataArr, response, query, execute, isLoading, error } = $data.todo.getAll({
  params: {},
  id: false,
  options: {
    immediate: false,
    cb: (result) => {},
    notify: true | false,
    responseType: "json",
    mode: "none" | "cors",
    useCache: true | false,
    useStore: true | false,
  },
  config: {}
})
```

--------------------------------

### GET /scripts

Source: https://gitlab.com/raclettejs/core-dev/-/blob/main/@docs/compiled-docs/docs/official-plugins/cli-connector.md

Lists all registered script names.

```APIDOC
## GET /scripts

### Description
Lists all registered script names that can be executed via the endpoints.

### Method
GET

### Endpoint
/scripts

### Response
#### Success Response (200)
- **scripts** (array of strings) - List of script names.

#### Response Example
["script1", "script2"]
```

--------------------------------

### Register a GET route with authentication and broadcasting

Source: https://gitlab.com/raclettejs/core-dev/-/blob/main/@docs/compiled-docs/docs/examples/cooking-steps/backend/plugin/singleRoute.md

Use this snippet to define a GET route in a RacletteJS plugin. It requires a payloadHelper and exampleBaseSchema, and uses fastify.authenticate for onRequest. The route broadcasts to 'exampleUpdated' channel and includes a schema with summary, description, tags, and body.

```typescript
import type { PluginFastifyInstance } from "@raclettejs/core"
import type { FastifyRequest, FastifyReply } from "fastify"
import payloadHelper from "./payloadHelper"

export const registerRoutes = async (fastify: PluginFastifyInstance) => {
  fastify.get("/example/get", {
    handler: async (req: FastifyRequest, reply: FastifyReply) => {
      /* YOUR BUSINESS LOGIC */
    },
    onRequest: [fastify.authenticate],
    config: {
      type: dataUpdate,
      broadcastChannels: ["exampleUpdated"],
    },
    schema: {
      summary: "Example example get Route",
      description: "Example example get Route",
      tags: ["myApp/example"],
      body: exampleBaseSchema,
    },
  })
}
```

--------------------------------

### Hooks example - output hooks converting Buffer to string

Source: https://gitlab.com/raclettejs/core-dev/-/blob/main/@docs/compiled-docs/docs/official-plugins/cli-connector.md

For long-running processes (jobs), include output hooks to convert Buffer objects to strings unless explicitly unwanted. This example shows stdout and stderr hooks that convert Buffers to UTF-8 strings.

```typescript
{
  exe: "/usr/bin/command",
  hooks: {
    stdout: (chunk: Buffer | string): string => {
      return Buffer.isBuffer(chunk) ? chunk.toString('utf8') : chunk
    },
    stderr: (chunk: Buffer | string): string => {
      return Buffer.isBuffer(chunk) ? chunk.toString('utf8') : chunk
    }
  }
}
```

--------------------------------

### Minimal frontend file tree

Source: https://gitlab.com/raclettejs/core-dev/-/blob/main/@docs/compiled-docs/docs/plugin-development/frontend/overview.md

Shows the minimal required frontend file layout for a plugin: an index.ts entry point and a widget Vue file. The frontend is optional, and a frontend-only plugin is valid without a backend.

```text
frontend/
├── index.ts
└── widgets/MyThing/MyThingWidget.vue
```

--------------------------------

### setWidgetState example

Source: https://gitlab.com/raclettejs/core-dev/-/blob/main/@docs/compiled-docs/docs/guides/howto/FAQ/storeApi.md

Sets the widget state with a full override.

```typescript
$store.setWidgetState({ foo: "bar" })
```

--------------------------------

### Multiple Instances: Accessing current and global plugin

Source: https://gitlab.com/raclettejs/core-dev/-/blob/main/@docs/compiled-docs/docs/guides/howto/FAQ/usePluginApi.md

Shows how to create multiple instances of usePluginApi, one for the current plugin and one for a specific plugin key 'raclette__core'.

```typescript
const { $data } = usePluginApi()
const { $data: $globalData } = usePluginApi("raclette__core")
```

--------------------------------

### GET /raclette__cache/cacheInstances

Source: https://gitlab.com/raclettejs/core-dev/-/blob/main/@docs/compiled-docs/docs/workbench/cacheList.md

Returns the configured Valkey instance ids and labels.

```APIDOC
## GET /raclette__cache/cacheInstances

### Description
Returns the configured Valkey instance ids and labels.

### Method
GET

### Endpoint
/raclette__cache/cacheInstances

### Response
#### Success Response (200)
- **instance ids** (array) - Configured Valkey instance ids
- **labels** (array) - Labels for the configured instances

#### Response Example
{
  "instances": [
    {
      "id": "string",
      "label": "string"
    }
  ]
}
```

--------------------------------

### Golden Path frontend folder structure

Source: https://gitlab.com/raclettejs/core-dev/-/blob/main/@docs/compiled-docs/docs/plugin-development/golden-path/frontend/overview.md

Recommended folder structure for a frontend plugin that has grown beyond a single widget file. The `*Widget.vue` file is the entry point and should stay thin, while shared logic goes into `components/` and `composables/`.

```text
frontend/
├── index.ts
├── generated-config.ts      # from backend
├── widgets/
│   └── TodoList/
│       ├── TodoListWidget.vue   # entry only — keep thin
│       └── setup.ts
├── components/                # shared across widgets (recommended)
└── composables/

```

--------------------------------

### Register Fastify routes for todo endpoints (routes/index.ts)

Source: https://gitlab.com/raclettejs/core-dev/-/blob/main/@docs/compiled-docs/docs/plugin-development/backend.md

Centralized route registration that imports individual route handlers and registers them on the Fastify instance. Maps GET /all, GET /todo/:_id, POST /todo, PATCH /todo/:_id, DELETE /todo/:_id, and DELETE /todo/:_id/hard.

```typescript
import type { PluginFastifyInstance, PluginOptions } from "@raclettejs/core"
import type { Model } from "mongoose"
import getAllRoute from "./route.todo.get-all"
import getByIdRoute from "./route.todo.get"
import postRoute from "./route.todo.post"
import patchRoute from "./route.todo.patch"
import deleteRoute from "./route.todo.delete"
import hardDeleteRoute from "./route.todo.hard-delete"

export const registerRoutes = async (
  fastify: PluginFastifyInstance,
  models: Record<string, Model<any>>,
  options: PluginOptions,
) => {
  const { key: pluginKey } = options

  // Register individual routes
  fastify.get("/all", getAllRoute(fastify))
  fastify.get("/todo/:_id", getByIdRoute(fastify))
  fastify.post("/todo", postRoute(fastify))
  fastify.patch("/todo/:_id", patchRoute(fastify))
  fastify.delete("/todo/:_id", deleteRoute(fastify))
  fastify.delete("/todo/:_id/hard", hardDeleteRoute(fastify))
}
```

--------------------------------

### dependencies field

Source: https://gitlab.com/raclettejs/core-dev/-/blob/main/@docs/compiled-docs/docs/plugin-development/metadata.md

Defines an array of plugin dependencies that must be installed before this plugin.

```javascript
dependencies: ["core-ui", "data-manager"]
```

--------------------------------

### Create a changeset with yarn :changeset

Source: https://gitlab.com/raclettejs/core-dev/-/blob/main/README.md

Run this command to interactively create a changeset file. Select affected publishable packages, choose a bump type (patch, minor, or major), and write a concise summary. The generated .changeset/*.md file should be committed with the feature or fix.

```shell
yarn :changeset
```

--------------------------------

### Install CLI Connector plugin with yarn

Source: https://gitlab.com/raclettejs/core-dev/-/blob/main/@docs/compiled-docs/docs/official-plugins/cli-connector.md

Adds the @raclettejs/plugin-cli-connector package to the project.

```bash
yarn add @raclettejs/plugin-cli-connector
```

--------------------------------

### POST Route Handler Example (route.todo.post.ts)

Source: https://gitlab.com/raclettejs/core-dev/-/blob/main/@docs/compiled-docs/docs/plugin-development/backend.md

Defines a Fastify route handler for creating a todo. It uses a factory function that returns a route configuration object with authentication middleware, schema validation, and error handling. The handler extracts user ID from the request, calls the todo service, and returns a 201 response or an internal server error.

```typescript
import type { TodoCreate } from "../todo.schema"
import type { FastifyReply, FastifyRequest } from "fastify"
import { todoCreateSchema } from "../todo.schema"
import type { PluginFastifyInstance } from "@raclettejs/types"

export default (fastify: PluginFastifyInstance) => {
  const handler = async (
    req: FastifyRequest<{ Body: TodoCreate }>,
    reply: FastifyReply,
  ) => {
    try {
      const todoData = {
        ...req.body,
        owner: req.user._id,
        lastEditor: req.user._id,
      }

      const payload = await fastify.todoService.createTodo(
        fastify,
        req.requestParams,
        todoData,
      )

      return reply.status(201).send(payload)
    } catch (err: any) {
      fastify.log.error(`Error creating todo: ${err.message}`)
      return reply.internalServerError(err.message)
    }
  }

  return {
    handler,
    onRequest: [fastify.authenticate],
    config: {
      type: "dataCreate",
    },
    schema: {
      summary: "Create a new todo",
      description: "Create a new todo",
      tags: ["core/todo"],
      body: todoCreateSchema,
    },
  }
}
```

--------------------------------

### hasChanges example

Source: https://gitlab.com/raclettejs/core-dev/-/blob/main/@docs/compiled-docs/docs/guides/howto/FAQ/storeApi.md

Compares two states and returns true if differences are detected.

```typescript
const changed = $store.hasChanges(originalState, currentState)
```

--------------------------------

### Listen to todoCreated event

Source: https://gitlab.com/raclettejs/core-dev/-/blob/main/@docs/compiled-docs/docs/guides/howto/FAQ/socketApi.md

Example of listening to the 'todoCreated' channel and logging the payload.

```typescript
$socket.on("todoCreated", (payload) => {
  console.log("Todo created:", payload)
})
```

--------------------------------

### Core getter example

Source: https://gitlab.com/raclettejs/core-dev/-/blob/main/@docs/compiled-docs/docs/guides/howto/FAQ/storeApi.md

Fully dynamic access to nested state, reactive.

```typescript
const state = $store.get(["queries", actionId])
```

--------------------------------

### Typical create-raclette-app project structure

Source: https://gitlab.com/raclettejs/core-dev/-/blob/main/@docs/compiled-docs/docs/introduction/how-raclette-works.md

Shows the file and folder layout of a standard racletteJS project, including plugins, services, shared code, i18n, and the generated .raclette directory.

```text
my-raclettejs-app/
├── package.json
├── packages.json
├── raclette.config.yaml
├── plugins/
│   └── my-plugin/
│       ├── raclette.plugin.ts
│       ├── backend/
│       └── frontend/
├── services/                  # optional overrides
│   ├── backend/
│   └── frontend/
├── shared/                    # optional shared app code
├── i18n/                      # optional app i18n
└── .raclette/                 # generated runtime output
```

--------------------------------

### Basic Usage: Logging a string

Source: https://gitlab.com/raclettejs/core-dev/-/blob/main/@docs/compiled-docs/docs/guides/howto/FAQ/logApi.md

Logs a string message with title 'init' and level 1 (info).

```typescript
$log("init", "Component mounted", 1)
```

--------------------------------

### Service Control API Call (JSON)

Source: https://gitlab.com/raclettejs/core-dev/-/blob/main/@docs/compiled-docs/docs/official-plugins/cli-connector.md

Example API request to invoke the service-control script.

```json
POST /script/service-control
{
  "args": ["restart", "nginx"]
}
```

--------------------------------

### Cross-component sync pattern

Source: https://gitlab.com/raclettejs/core-dev/-/blob/main/@docs/compiled-docs/docs/guides/howto/FAQ/eventApi.md

Shows how to set up a listener for a domain event like `todoUpdated` and execute logic when it fires.

```TypeScript
$eventbus.on("todoUpdated", () => {
  execute()
})
```

--------------------------------

### Available Methods - $data.<model>.<action>()

Source: https://gitlab.com/raclettejs/core-dev/-/blob/main/@docs/compiled-docs/docs/guides/howto/FAQ/dataApi.md

Generic call pattern for any model and action.

```ts
$data.<model>.<action>()
```

--------------------------------

### GET /raclette__cache/cacheEntry

Source: https://gitlab.com/raclettejs/core-dev/-/blob/main/@docs/compiled-docs/docs/workbench/cacheList.md

Returns a single key lookup based on the provided key, database, and instance.

```APIDOC
## GET /raclette__cache/cacheEntry

### Description
Returns a single key lookup.

### Method
GET

### Endpoint
/raclette__cache/cacheEntry

### Parameters
#### Query Parameters
- **key** (string) - Required - The key to look up
- **db** (integer) - Required - The database index
- **instance** (string) - Required - The instance identifier

### Response
#### Success Response (200)
- **key** (string) - The key
- **value** (string) - The value associated with the key

#### Response Example
{
  "key": "string",
  "value": "string"
}
```

--------------------------------

### Excerpt of generated-config.ts showing operations, storeActionType, and channels

Source: https://gitlab.com/raclettejs/core-dev/-/blob/main/@docs/compiled-docs/docs/plugin-development/golden-path/backend/frontend-entity-mapping.md

Short excerpt from the playground todo plugin illustrating how an entity exposes operations with HTTP metadata, storeActionType, and channels. The file is not hand-edited.

```typescript
export default {
  pluginName: "example-todo",
  author: "pacifico",
  pluginKey: "pacifico__example-todo",
  routePrefix: "/pacifico__example-todo",
  pluginPath: "/app/src/appPlugins/pacifico__todo",
  data: {
    todo: {
      type: "todo",
      operations: {
        getAll: {
          target: "/pacifico__example-todo/todo/all",
          method: "get",
          storeActionType: "dataRead",
        },
        create: {
          target: "/pacifico__example-todo/todo",
          method: "post",
          storeActionType: "dataCreate",
          channels: [
            {
              channel: "pacifico__example-todo--todoCreated",
              channelKey: "todoCreated",
              prefix: "pacifico__example-todo",
            },
            {
              channel: "dataCreated",
              channelKey: "broadcastDataCreated",
              prefix: "",
            },
          ],
        },
        updateCheckTask: {
          target: (payload) =>
            `/pacifico__example-todo/todo/checkTask/${payload._id}`,
          method: "patch",
          storeActionType: "dataUpdate",
          channels: [
            /* … */
          ],
        },
      },
    },
  },
}
```

--------------------------------

### Typical Pattern: Default usage

Source: https://gitlab.com/raclettejs/core-dev/-/blob/main/@docs/compiled-docs/docs/guides/howto/FAQ/usePluginApi.md

Shows the default usage of usePluginApi to get the $data API.

```typescript
const { $data } = usePluginApi()
```

--------------------------------

### Get reactive state with $store.get

Source: https://gitlab.com/raclettejs/core-dev/-/blob/main/@docs/compiled-docs/docs/guides/howto/FAQ/storeApi.md

Access any part of the store reactively using a path array.

```typescript
const ui = $store.get(["ui"])
const widgets = $store.get(["widgets"])
const widget = $store.get(["widgets", widgetId])
```

--------------------------------

### File Operations with Concatenation API Call (JSON)

Source: https://gitlab.com/raclettejs/core-dev/-/blob/main/@docs/compiled-docs/docs/official-plugins/cli-connector.md

Example API request to invoke the chmod-files script.

```json
POST /script/chmod-files
{
  "args": ["rw", "document.txt"]
}
```
Tokens:
Raw