diff --git a/README.md b/README.md
index a9ac4858..0e7808a9 100644
--- a/README.md
+++ b/README.md
@@ -59,6 +59,42 @@ If you encounter any issues with nightly builds, please report them in our [issu
 ## Development & Building
 You'll need to download the package manager used with this repo. You can install it by visiting [Bun.sh](https://bun.sh/) and following the installation instructions. 
 
+### Debugging 
+
+#### Debugging with React Scan
+Meshtastic Web Client has included the library [React Scan](https://github.com/aidenybai/react-scan) to help you identify and resolve render performance issues during development.
+
+React's comparison-by-reference approach to props makes it easy to inadvertently cause unnecessary re-renders, especially with:
+
+- Inline function callbacks (`onClick={() => handleClick()}`)
+- Object literals (`style={{ color: "purple" }}`)
+- Array literals (`items={[1, 2, 3]}`)
+
+These are recreated on every render, causing child components to re-render even when nothing has actually changed.
+
+Unlike React DevTools, React Scan specifically focuses on performance optimization by:
+
+- Clearly distinguishing between necessary and unnecessary renders
+- Providing render counts for components
+- Highlighting slow-rendering components
+- Offering a dedicated performance debugging experience
+
+#### Usage
+When experiencing slow renders, run:
+
+```bash
+bun run dev:scan
+```
+
+This will allow you to discover the following about your components and pages:
+
+- Components with excessive re-renders
+- Performance bottlenecks in the render tree
+- Expensive hook operations
+- Props that change reference on every render
+
+Use these insights to apply targeted optimizations like `React.memo()`, `useCallback()`, or `useMemo()` where they'll have the most impact.
+
 ### Building and Packaging
 
 Build the project:
diff --git a/package.json b/package.json
index a9961b0d..2f1aa3d3 100644
--- a/package.json
+++ b/package.json
@@ -11,7 +11,7 @@
     "check:fix": "pnpm check --write src/",
     "format": "biome format --write src/",
     "dev": "vite dev --open",
-    "dev:debug": "VITE_DEBUG=true vite dev",
+    "dev:scan": "VITE_DEBUG_SCAN=true vite dev",
     "test": "vitest",
     "test:ui": "vitest --ui",
     "test:run": "vitest run",
diff --git a/src/index.tsx b/src/index.tsx
index e1cb4764..7b56e632 100644
--- a/src/index.tsx
+++ b/src/index.tsx
@@ -8,7 +8,8 @@ import { createRoot } from "react-dom/client";
 import { App } from "@app/App.tsx";
 
 // run react scan tool in development mode only
-import.meta.env.VITE_DEBUG &&
+// react scan must be the first import and the first line in this file in order to work properly
+import.meta.env.VITE_DEBUG_SCAN &&
   scan({
     enabled: true,
   });