How racletteJS Works

racletteJS uses a managed runtime architecture so application teams can focus on business logic first.

Core Idea

• racletteJS ships opinionated backend and frontend runtime layers in @raclettejs/core.
• Your app extends that runtime primarily through plugins.
• During yarn dev, racletteJS builds a virtualized runtime file tree (.raclette) and starts containers from it.

Mental Model

• Think in layers: core files + app overlays + mounted plugin folders.
• The runtime inside containers is the result of VFS plus extra mounts.
• Plugins are additive by design; service overrides are an escape hatch.

Typical App Structure

Below is a typical create-raclette-app style project structure:

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

Start Your Local Application

From your project root, start development with:

yarn dev

This is the main command you use day to day. The racletteJS CLI will:

• Print a lot of log output while it prepares the runtime
• Generate the .raclette folder (config, virtual file tree, Docker files)
• Start the required Docker containers (app services, database, cache, and Workbench when enabled)
• Attach to service logs in the same terminal, so you keep seeing backend and frontend output

The first run can take noticeably longer, because dependencies are installed inside the containers.

Once startup completes, open the app in your browser:

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

Inspect running containers (optional)

After yarn dev has finished starting, you can open a separate terminal window and list running containers:

docker ps

The table below mirrors a typical docker ps result for a create-raclette-app project named my-test-app (Workbench enabled). Column NAMES matches what you see in the terminal.

NAMES	IMAGE	STATUS	Host port(s)
my-test-app-frontend	my-test-app-frontend	Up (healthy)	8081 → container 8081
my-test-app-backend	my-test-app-backend	Up (healthy)	8082 → container 3000
my-test-app-workbench-backend	my-test-app-workbench-backend	Up (healthy)	8084 → container 3000
raclette-mongodb	mongo:8.2	Up (healthy)	27017 (localhost only)
raclette-cache	valkey/valkey:9.0-alpine	Up (healthy)	6379 (localhost only)

App containers are prefixed with your project name from raclette.config (here: my-test-app). MongoDB and cache often keep shared names (raclette-mongodb, raclette-cache) so multiple racletteJS projects can reuse them.

Stop the app

To stop your local racletteJS app:

• Press Ctrl+C in the terminal where yarn dev is running, or
• Run yarn down from the project root

Both stop the racletteJS Docker services started for your app.

Where to Start

1. Read Architecture Overview.
2. Read File layering and VFS.
3. Read Where to put your code.
4. Continue with Getting Started.