wled-controller/BUILD.md

Building WLED Controller for Windows

This guide explains how to build a standalone Windows executable for WLED Controller.

Prerequisites

• Node.js 20 or higher
• npm

Build Steps

1. Install Dependencies

First, install dependencies for both frontend and backend:

# Install backend dependencies
cd backend
npm install

# Install frontend dependencies
cd ../frontend
npm install

2. Run Database Migrations

Ensure your database is set up:

cd backend
npm run prisma:migrate
npm run prisma:generate

3. Build the Executable

From the backend directory, run:

cd backend
npm run package

This command will:

1. Build the frontend and copy it to backend/public
2. Build the backend TypeScript code to JavaScript
3. Package everything into a single Windows executable

The executable will be created at: release/wled-controller.exe

Running the Executable

First Time Setup

1. Copy the wled-controller.exe file to your desired location
2. In the same directory, create a prisma folder
3. Copy the backend/prisma/dev.db file (your database) to the same directory as the exe

Your directory structure should look like:

your-install-folder/
├── wled-controller.exe
└── prisma/
    └── dev.db

Running

Simply double-click wled-controller.exe or run from command line:

.\wled-controller.exe

The application will start on port 3000 (configurable via PORT environment variable).

Access the web interface at: http://localhost:3000

Configuration

You can set environment variables before running:

# Set custom port
$env:PORT=8080
.\wled-controller.exe

# Set custom database path
$env:DATABASE_URL="file:./custom-path/wled.db"
.\wled-controller.exe

Troubleshooting

Database Not Found

If you see database errors, ensure:

• The prisma folder exists in the same directory as the exe
• The dev.db file is in the prisma folder
• File permissions allow reading/writing

Port Already in Use

If port 3000 is already in use, set a different port:

$env:PORT=3001
.\wled-controller.exe

Missing Dependencies

The executable includes all Node.js dependencies, but requires:

• Windows 10 or higher (64-bit)
• No additional runtime needed

Development vs Production

• Development: Use npm run dev in both frontend and backend directories
• Production Build: Use npm run package to create the executable

File Sizes

The packaged executable will be approximately 80-100 MB due to:

• Node.js runtime
• All npm dependencies
• Frontend static files
• Prisma binaries

Notes

• The executable is self-contained and includes the Node.js runtime
• All frontend files are served from the built-in web server
• Database file can be backed up by copying the dev.db file
• Scheduler tasks will run automatically when the executable starts