Use Node.js 24 or newer. The application uses the runtime’s built-in SQLite support and checks the Node version before normal development, build, test, and worker commands. Install the locked dependencies from the repository root. Use a separate environment and data directory for synthetic tests so test records cannot mix with working data.

bash
npm ci
cp .env.example .env.local
# In .env.local, deliberately select ATLAS_AUTH_PROVIDER=local
# for isolated local development, or configure both Clerk keys.
npm run dev

The default development server listens on http://127.0.0.1:3000. Leave DATABASE_URL unset for the local SQLite fallback. Local authentication is an explicit development option; configure Clerk before exposing a hosted application. Adding OPENAI_API_KEY enables real provider calls, including semantic indexing. Without it, the interface reports AI unavailability and allows an explicit built-in-helper choice.

Verify a change#

bash
npm run verify
# Equivalent checks: typecheck, unit tests, and production build.
npx playwright install chromium

Browser tests require a separately running, isolated server. The empty provider key makes AI behavior deterministic; the tests explicitly choose the built-in helper or use synthetic provider responses. ATLAS_BUILD_DIR and ATLAS_DATA_DIR separate test artifacts from your normal server.

bash
ATLAS_AUTH_PROVIDER=local OPENAI_API_KEY='' ATLAS_BUILD_DIR=.next-e2e ATLAS_DATA_DIR=../ralti-test-data ATLAS_DISABLE_WORKER=true npm run dev -- --port 3001
# In another terminal:
PLAYWRIGHT_BASE_URL=http://127.0.0.1:3001 npm run test:e2e

Before changing Next.js integration code, read the relevant installed guide under node_modules/next/dist/docs/. This repository’s Next.js version may differ from older tutorials and uses proxy.ts for request interception.