# Local Compiler

Run the Quickback compiler locally using Docker. The local compiler uses the exact same Docker image as the cloud compiler, ensuring identical behavior — including SPA builds with correct environment variables.

## Prerequisites

- Docker Desktop installed and running
- Quickback monorepo cloned locally
- Authenticated via `quickback login`

## Quick Start

From the monorepo root:

```bash
cd apps/compiler-local && bash dev.sh
```

This will:
1. Ensure Docker Desktop is running
2. Stop any existing compiler container
3. Build the Docker image from `apps/compiler/Dockerfile`
4. Run it on port 3000

### Custom Port

```bash
bash dev.sh 3001
```

## Compiling a Project

Point the CLI to your local compiler:

```bash
QUICKBACK_API_URL=http://localhost:3000 quickback compile
```

Or export it for the session:

```bash
export QUICKBACK_API_URL=http://localhost:3000
quickback compile
```

Authentication is always required. Run `quickback login` first if you haven't already.

## Manual Build & Run

You can also build and run the Docker image directly from the monorepo root:

```bash
# Build
docker build -t quickback-compiler -f apps/compiler/Dockerfile .

# Run
docker run --rm -p 3000:3000 quickback-compiler
```

## Verify

Check the compiler is running:

```bash
curl http://localhost:3000/health
```

## How It Works

The Docker image includes:
- Pre-installed dependencies for compiled projects (`/deps/node_modules`)
- CMS and Account SPA source code (`/spa/cms/`, `/spa/account/`)
- Pre-installed SPA dependencies (`/spa-deps/cms/`, `/spa-deps/account/`)

When compiling a project with `cms: true` or `account: true`, the compiler builds the SPAs from source inside the container with the correct Vite environment variables (e.g., `VITE_QUICKBACK_API_URL`, `VITE_QUICKBACK_ACCOUNT_URL`). This ensures each project gets properly configured SPA assets without manual intervention.

## Deploying to Cloud

After making changes to the compiler, deploy to `compiler.quickback.dev`:

```bash
cd apps/compiler-cloud && bash deploy.sh
```

## Troubleshooting

### Container not starting

```bash
docker logs quickback-compiler-local
```

### Port already in use

```bash
# Find what's using the port
lsof -i :3000

# Use a different port
bash dev.sh 3001
```

### Docker out of disk space

```bash
docker system prune -af
```

### SPA build warnings

If you see SPA build warnings during compilation, ensure the SPA dependency files are up to date:
- `apps/compiler/deps-spa-cms-package.json`
- `apps/compiler/deps-spa-account-package.json`

These must include all dependencies from `packages/cms/package.json` and `packages/account/package.json` respectively.
