Installation

There are two ways to install DEJA.js:

• Quick Install — A single command that downloads the server, installs dependencies, and configures your environment. Best for most users.
• Developer Setup — Clone the full monorepo and configure everything yourself. Best for developers who want to contribute or customize.

Both paths assume you have already signed up for DEJA Cloud and completed the onboarding wizard (see Quick Start, Steps 1–3).

Prerequisites

Quick Install

That's it — the install script handles everything else.

Developer Setup

If you do not have pnpm installed, you can enable it through Node.js corepack:

corepack enable
corepack prepare pnpm@9.0.0 --activate

A DCC-EX CommandStation connected via USB is optional during development. The server and frontend apps will run without hardware attached — you just will not be able to send commands to the track.

Quick Install

Open a terminal on the machine connected to your DCC-EX CommandStation and run one command:

macOS / Linux / Raspberry Pi

curl -fsSL https://install.dejajs.com | bash

Windows

Windows users should install via WSL, then run the curl command above from a WSL terminal.

The script will:

1. Check for Node.js 20+ (provides install instructions if missing)
2. Prompt for your account credentials (UID and Layout ID from the onboarding wizard)
3. Create your environment configuration at ~/.deja/.env
4. Detect serial ports for your DCC-EX CommandStation
5. Download the DEJA Server tarball and install dependencies
6. Install the deja CLI
7. Start the server

deja CLI Commands

After installation, manage the server with the deja CLI:

~/.deja/ Directory Structure

The Quick Install places all files under ~/.deja/:

~/.deja/
├── bin/
│   └── deja          # CLI executable (added to PATH)
├── server/           # Server files (downloaded tarball)
├── config.json       # Account config (uid, layoutId)
└── .env              # Environment variables (Firebase, ports, etc.)

After the script finishes, you're ready to register your CommandStation.

Developer Setup

Clone the Repository

git clone https://github.com/jmcdannel/DEJA.js.git
cd DEJA.js

Install Dependencies

DEJA.js uses pnpm workspaces with Turborepo. A single install command fetches dependencies for every app and package in the monorepo:

pnpm install

This may take a minute on the first run. Do not use npm install or yarn — the project is configured exclusively for pnpm.

Configure Environment Variables

Copy the example environment file to create your local configuration:

cp .env.example .env.local

Open .env.local in your editor and paste the credentials from the onboarding wizard. If you need to find them again, log in to DEJA Cloud, select your layout, and click Settings > View Local Environment Configuration.

Required Variables

Communication Settings

Optional Variables

Individual apps can also have their own .env.local files in apps/<app-name>/ for app-specific overrides.

Verify the Installation

Quick Install

deja status

If the server is running and connected, you're good to go.

Developer Setup

Build all packages to confirm everything is wired up correctly:

pnpm build

If the build succeeds with no errors, your installation is complete. You can also run the type checker and linter to catch any configuration issues:

pnpm check-types
pnpm lint

Troubleshooting

deja: command not found

The install script adds ~/.deja/bin to your PATH. If the command is not found after installation, either open a new terminal or run:

source ~/.zshrc   # or source ~/.bashrc

pnpm: command not found

Only needed for the Developer Setup. Make sure corepack is enabled (corepack enable) or install pnpm globally (npm install -g pnpm@9).

Firebase errors on startup

Quick Install: Double-check that all Firebase variables are set in ~/.deja/.env. You can re-run the install script or edit the file manually.

Developer Setup: Double-check that all VITE_FIREBASE_* variables are set in .env.local. Missing values will cause build-time or runtime errors in apps that depend on Firebase.

Serial port access denied

On Linux, your user may need to be in the dialout group to access USB serial ports:

sudo usermod -a -G dialout $USER

Log out and back in for the change to take effect.

Port conflicts

If a dev server fails to start because a port is already in use, you can change the port in the app's vite.config.ts or stop the conflicting process.

Next Steps

Your environment is ready. Head to the Quick Start guide to register your CommandStation and start controlling trains.