From 35b84936969aa73e65113b62de6e809a37b9cd07 Mon Sep 17 00:00:00 2001
From: simoleo89 <simoleo89@users.noreply.github.com>
Date: Tue, 12 May 2026 08:48:11 +0000
Subject: [PATCH] vite: fail fast with a setup hint when the renderer SDK is
 missing

Today if you clone Nitro-V3 without cloning Nitro_Render_V3 next to it,
yarn start / yarn build fail deep inside Rolldown with:

    Failed to resolve import "@nitrots/nitro-renderer"
    from "/path/to/Nitro-V3/src/App.tsx"

which doesn't tell you what to do. Move the check up to
vite.config.mjs: when neither ../Nitro_Render_V3 nor ../renderer
exists, throw with the explicit clone-and-install steps and a pointer
to CLAUDE.md.

Also update CLAUDE.md "Commands" section:
- Add `yarn preview` (production build server, http://localhost:4173).
- Add a 4-step "Setup walkthrough" covering: clone the renderer
  sibling, yarn install on both, copy public/configuration/*.example
  to *.json, then run.

Net effect: a fresh checkout of this branch shows you exactly which
prerequisite is missing instead of a Rolldown stack trace.
---
 CLAUDE.md       | 31 +++++++++++++++++++++++++++++++
 vite.config.mjs | 17 +++++++++++++++++
 2 files changed, 48 insertions(+)

diff --git a/CLAUDE.md b/CLAUDE.md
index 9e3f830..d8a0451 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -21,11 +21,42 @@ read that before starting anything non-trivial.
 |---|---|
 | Dev server | `yarn start` |
 | Production build | `yarn build` |
+| Serve production build | `yarn preview` (defaults to http://localhost:4173) |
 | Lint | `yarn eslint` |
 | Type-check (TS 7 native, fast) | `yarn typecheck` |
 | Test (Vitest, once) | `yarn test` |
 | Test (watch) | `yarn test:watch` |
 
+## Setup walkthrough
+
+1. **Clone the renderer SDK as a sibling of this repo.**
+   `vite.config.mjs` resolves the `@nitrots/*` aliases against
+   `../Nitro_Render_V3` (preferred) or `../renderer` (legacy). If neither
+   exists, the dev server and build now fail fast with a message
+   pointing here.
+
+   ```sh
+   cd ..                            # parent of Nitro-V3
+   git clone <renderer-repo> Nitro_Render_V3
+   cd Nitro_Render_V3 && yarn install
+   ```
+
+2. **Install client deps.**
+   ```sh
+   cd ../Nitro-V3
+   yarn install
+   ```
+
+3. **Materialize the runtime configuration.** `public/configuration/`
+   ships `.example` files. Copy the ones you need without the `.example`
+   suffix and point them at your game server (websocket URL, asset
+   base URL, UI texts, etc.). The dev server doesn't fail if these are
+   missing but the client renders a blank/error screen at runtime.
+
+4. **Run.**
+   - Dev: `yarn start` (Vite, HMR, includes the renderer source).
+   - Production preview: `yarn build && yarn preview`.
+
 The renderer SDK (`@nitrots/nitro-renderer`) is consumed via a filesystem
 link to a sibling working tree — `../Nitro_Render_V3` (preferred) or
 `../renderer` (legacy). Without it, `yarn typecheck` reports TS2307 across
diff --git a/vite.config.mjs b/vite.config.mjs
index 5947ff6..0a8536e 100644
--- a/vite.config.mjs
+++ b/vite.config.mjs
@@ -7,6 +7,23 @@ const legacyRendererRoot = resolve(__dirname, '..', 'renderer');
 const currentRendererRoot = resolve(__dirname, '..', 'Nitro_Render_V3');
 const rendererRoot = existsSync(currentRendererRoot) ? currentRendererRoot : legacyRendererRoot;
 
+if(!existsSync(rendererRoot))
+{
+    // Fail fast with a useful message instead of waiting for Rolldown to
+    // report "Failed to resolve import @nitrots/nitro-renderer" deep
+    // inside the bundle pass.
+    throw new Error(
+        '\n  Nitro renderer SDK not found.\n\n' +
+        '  vite.config.mjs expects one of these directories to exist as a sibling of this repo:\n' +
+        `    - ${ currentRendererRoot } (preferred)\n` +
+        `    - ${ legacyRendererRoot } (legacy)\n\n` +
+        '  Clone the Nitro_Render_V3 repo next to Nitro-V3 and rerun:\n' +
+        '    git clone <renderer-repo> ../Nitro_Render_V3\n' +
+        '    cd ../Nitro_Render_V3 && yarn install\n\n' +
+        '  (See CLAUDE.md "Commands" section for the full setup walkthrough.)\n'
+    );
+}
+
 const ReactCompilerConfig = {
     target: '19'
 };