Local Development with dx

This page is for contributors working on the Lombok codebase.

It reflects the current Lombok repository structure and local workflow:

• Bun workspace monorepo
• main runtime packages such as packages/api, packages/ui, and packages/core-worker
• Docker-based local development
• the ./dx developer CLI as the primary entrypoint

If you only want to run Lombok instead of developing it, see the Quickstart.

What this page helps you do

Use this page to get a contributor environment running and to understand the main local development loop.

At a high level, the workflow is:

1. clone the repository
2. install dependencies with Bun
3. start the local environment with ./dx up
4. use ./dx for reloads, resets, migrations, tests, checks, and logs

Repository shape

The Lombok repository is not a single src/ application with Prisma and a local SQLite file.

It is a monorepo organized around runtime-oriented packages, including:

• packages/api — NestJS backend
• packages/ui — React + Vite frontend
• packages/core-worker — core worker runtime
• packages/types — shared platform types
• packages/sdk — typed client SDK
• packages/app-worker-sdk — app worker SDK
• packages/app-browser-sdk — embedded app UI SDK
• packages/ui-toolkit — shared UI system

For a broader structural view, see Repository Conventions.

Prerequisites

Before you start, install:

• Git
• Bun
• Docker
• Docker Compose

Clone the repository

git clone https://github.com/lombokapp/lombok-web.git
cd lombok

Install dependencies

bun install

Start the development environment

The main source of truth for local development is the repository’s DEVELOPMENT.md.

The normal workflow is:

./dx up

The inspected docs describe this as starting the Docker-based local environment, including:

• backend
• frontend
• PostgreSQL
• MinIO

After startup:

1. add lombok.localhost to your /etc/hosts file pointing to 127.0.0.1
2. open http://localhost:5173

What ./dx does

./dx is the main developer command surface for Lombok.

Examples referenced in the current docs include:

./dx reload api
./dx restart api
./dx restart ui
./dx db seed
./dx db reset
./dx db migrate
./dx unit <package>
./dx e2e api
./dx e2e ui
./dx e2e core-worker
./dx generate openapi
./dx generate metadata
./dx shell
./dx logs

Run help any time:

./dx help

Environment model

For the standard contributor workflow, environment variables are primarily driven through Lombok’s Docker-based development setup.

You do not need a generic .env.local + SQLite + Prisma workflow.

The inspected docs indicate that:

• the default development environment is driven by docker-compose.yml
• PostgreSQL and MinIO are part of the local environment
• DEV_SEED_FILE controls initial seed behavior

Database and migrations

The inspected docs describe Lombok as using Drizzle, not Prisma.

Examples of the documented database workflow include:

./dx db migrate
./dx db migrate:new
./dx db reset
./dx db reset:seed

A dedicated migrations page is planned for deeper workflow guidance.

Testing and checks

Use ./dx for common contributor checks.

Examples currently referenced in the docs include:

./dx check all
./dx check eslint
./dx check prettier
./dx check tsc
./dx e2e api
./dx e2e ui
./dx e2e core-worker

Dedicated pages for tests and linting/type-checking are planned for this docs wave.

Contributor mental model

A useful way to think about local development is:

• API in packages/api
• UI in packages/ui
• Workers in packages/core-worker
• shared contracts and tooling across the monorepo

That split matters because the codebase is intentionally organized by runtime responsibility rather than by a single app folder.

Next steps

Once your environment is running:

• read Repository Conventions
• review Core Concepts
• review the Storage
• review the App Platform
• use the later Development pages for tests, linting, migrations, OpenAPI generation, and per-surface workflows

Important correction

Older draft docs described Lombok local development as a generic app with:

• src/
• prisma/
• .env.local
• SQLite-first development

That is not an accurate representation of the current Lombok codebase and should not be used as contributor guidance.