Getting Started

This page gets you from zero to a running racletteJS app. For a deeper explanation of the runtime model (VFS, Docker, containers), see How racletteJS Works.

Installation

Prerequisites

Before you begin, install:

• Node.js and yarn (npm is optional)
• Docker Desktop — racletteJS runs your app in containers during development
• A terminal and code editor (VS Code / OSS Code is recommended)

create-raclette-app

The fastest way to start is create-raclette-app. It scaffolds a complete project with plugins folder, config, scripts, and (by default) the Workbench admin package.

npm

npx create-raclette-app

yarn

yarn create raclette-app

The wizard creates everything you need. Follow its “next steps”, then continue below with Start and use your application.

---

You can also assemble a project manually. You need @raclettejs/core; @raclettejs/workbench is strongly recommended so you can configure users, compositions, and system data without raw database work.

yarn

yarn add @raclettejs/core @raclettejs/workbench

The Config File

Your app is configured in raclette.config.js or raclette.config.yaml:

raclette.config.js

import { defineRacletteConfig } from "@raclettejs/core"

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

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

See Reference: raclette Config for all options.

package.json Scripts

Add racletteJS CLI scripts to your package.json:

"scripts": {
  "dev": "raclette dev",
  "down": "raclette down",
  "update": "raclette update",
  "restart": "raclette restart",
  "add-package": "raclette add-package"
},

These map to the raclette CLI — you usually run them as yarn dev, yarn down, and so on. Full command reference: racletteJS CLI.

Start and Use Your Application

From your project root:

yarn dev

This is your main development command. racletteJS reads your config, generates the .raclette folder, builds the virtual runtime file tree, starts Docker containers (backend, frontend, database, cache, and Workbench when enabled), and streams logs in the same terminal.

The first run often takes a few minutes while dependencies install inside the containers. When startup finishes, open:

Service	URL
Main app (frontend)	http://localhost:8081
racletteJS Workbench (when enabled)	http://localhost:8083

Stop the app with Ctrl+C in the dev terminal, or run yarn down from the project root.

Want the full picture?

For step-by-step detail (what appears in logs, optional docker ps inspection, container naming, and stopping services), read How racletteJS Works — Start your local application.

Plugin Development

Most of your application code belongs in plugins — not in framework entry files. racletteJS discovers plugins from your plugins/ folder and loads them into the running backend and frontend.

New to plugins? Start with Fundamentals — Getting started with plugins.

Important: services/ Means Override Mode

Optional folders services/frontend/ and services/backend/ overlay the racletteJS core at matching file paths. A file there replaces the core file with the same path — it does not merge or patch.

• Use this only when you need behavior the plugin system does not expose yet.
• Prefer adding features through plugins whenever possible.
• If you only want to add app code (not replace core files), use the reserved app namespace under services/*/src/app/.

See File layering and VFS and Plugins vs service overrides before relying on overrides.

What to Read Next

Topic	Page
Runtime model (VFS, Docker, containers)	How racletteJS Works
Where to put code	Where to put your code
Day-to-day defaults	Best practices
Architecture overview	Architecture Overview