Skip to content

Getting Started

Jump to bottom
ArdaDDemir edited this page Jul 16, 2026 · 1 revision

Getting Started

Requirements

  • Node.js 20+
  • A browser with WebGL2 — any current Chrome, Edge, Firefox or Safari

No database, no API keys, no .env file. It's a client-side game.

Run it

git clone https://github.com/ArdaDDemir/luminareef.git
cd luminareef
npm install
npm run dev

Open the printed URL — usually http://localhost:3000.

Use a visible browser tab. The scene is driven by requestAnimationFrame, which browsers pause for hidden or backgrounded tabs. A minimised window or a headless preview pane shows a blank canvas. That's the browser, not a bug.

Build it

npm run build     # production build
npm start         # serve the build

Every script

Command What it does
npm run dev Dev server with hot reload
npm run build Production build
npm start Serve the production build
npm run lint ESLint
npm run typecheck tsc --noEmit
npm run perf Measure fps against a running dev server — see Performance
npm run shots Regenerate the README screenshots

perf and shots drive a real browser via Playwright and expect a dev server to already be running. Next refuses to start a second dev server in the same directory, so start one yourself first:

npm run dev      # terminal 1
npm run perf     # terminal 2

Deploy it

It's a static-friendly Next app with no backend, so anywhere that runs Next works. Vercel needs no configuration:

npx vercel

Netlify, Render, Railway, Cloudflare Pages and a plain npm run build && npm start on any Node host all work the same way. There is nothing to configure because there is nothing to connect to.

Troubleshooting

Blank canvas. The tab is hidden or backgrounded — see the note above. If the tab is visible, check chrome://gpu for a blocklisted GPU.

"Another next dev server is already running." Exactly what it says. Next 16 allows one per directory; the error prints the PID to kill.

It runs, but it drags. The scene should promote itself to full quality only if your device can hold it. If it feels heavy anyway, see Performance — and please open an issue with your GPU, it's useful data.

More in the FAQ.

🪸 LuminaReef

Playing

Building

Repository

Clone this wiki locally