refactor: address review feedback for Spotlight + fallow

- Extract Sentry env opts (cloud/spotlight/silent) for readability
- Hoist SPOTLIGHT_PLACEHOLDER_DSN constant
- Move enableLogs into spotlight branch
- Add PowerShell variant for SPOTLIGHT=true in CONTRIBUTING.md
- Tune .fallowrc.json: cover storybook + package configs,
  exclude generated registry/manager types, tools/, .github/

Amp-Thread-ID: https://ampcode.com/threads/T-019de261-3205-769d-a3c0-e7a363ea5896
Co-authored-by: Amp <amp@ampcode.com>

.env_example

@@ -47,6 +47,10 @@ ALGOLIA_API_KEY=684d998c36b67a9a9fce8fc2d8860579
 # SENTRY_PROJECT=cloud-frontend-staging
 # SENTRY_PROJECT_PROD= # prod project slug for sourcemap uploads
 
+# Enable Sentry Spotlight local dev overlay (https://spotlightjs.com).
+# Run `pnpx @spotlightjs/spotlight` in another terminal, then set this to true.
+# SPOTLIGHT=true
+
 # Ashby (apps/website careers page build).
 # Server-only; read inside the Astro build context. Do NOT prefix with PUBLIC_.
 # When unset, the committed snapshot at apps/website/src/data/ashby-roles.snapshot.json is used.

.fallowrc.json

@@ -0,0 +1,59 @@
+{
+  "$schema": "https://raw.githubusercontent.com/fallow-rs/fallow/main/schema.json",
+  "entry": [
+    "src/main.ts",
+    "scripts/**/*.{ts,mts,js}",
+    "build/**/*.{ts,mts,js}",
+    "vite.config.mts",
+    "vite.electron.config.mts",
+    "vite.types.config.mts",
+    "vitest.setup.ts",
+    "playwright.config.ts",
+    "playwright.i18n.config.ts",
+    "eslint.config.ts",
+    "knip.config.ts",
+    "lint-staged.config.ts",
+    "apps/*/src/main.ts",
+    "packages/*/src/index.ts",
+    "**/.storybook/{main,preview}.{ts,tsx}",
+    "packages/*/*.config.{ts,mts}",
+    "browser_tests/**/*.spec.ts",
+    "src/**/*.test.ts",
+    "src/**/*.stories.ts"
+  ],
+  "ignorePatterns": [
+    "**/*.generated.ts",
+    "**/*.gen.ts",
+    "**/*.d.ts",
+    "**/dist/**",
+    "**/.nx/**",
+    "**/node_modules/**",
+    "**/coverage/**",
+    "src/lib/litegraph/**",
+    "src/locales/**",
+    "packages/registry-types/src/comfyRegistryTypes.ts",
+    "**/generatedManagerTypes.ts",
+    "tools/**",
+    "public/**",
+    "temp/**",
+    ".github/**"
+  ],
+  "rules": {
+    "unused-files": "warn",
+    "unused-exports": "warn",
+    "unused-types": "warn",
+    "unused-dependencies": "warn",
+    "unused-enum-members": "warn",
+    "unused-class-members": "warn",
+    "circular-dependencies": "warn",
+    "boundary-violations": "warn",
+    "unresolved-imports": "warn",
+    "unlisted-dependencies": "warn",
+    "duplicate-exports": "warn",
+    "stale-suppressions": "warn"
+  },
+  "health": {
+    "maxCyclomatic": 20,
+    "maxCognitive": 15
+  }
+}

CONTRIBUTING.md

@@ -118,6 +118,36 @@ navigate to `http://<server_ip>:5173` (e.g. `http://192.168.2.20:5173` here), to
 > ⚠️ IMPORTANT:
 > The dev server will NOT load JavaScript extensions from custom nodes. Only core extensions (built into the frontend) will be loaded. This is because the shim system that allows custom node JavaScript to import frontend modules only works in production builds. Python custom nodes still function normally. See [Extension Development Guide](docs/extensions/development.md) for details and workarounds. And See [Extension Overview](docs/extensions/README.md) for extensions overview.
 
+### Local Sentry events with Spotlight (optional)
+
+[Spotlight](https://spotlightjs.com) is the local Sentry dev overlay. It shows errors, traces, and logs from your running dev server in a browser UI, without needing a Sentry account.
+
+To enable it:
+
+1. In one terminal, run the Spotlight sidecar:
+
+   ```bash
+   pnpx @spotlightjs/spotlight
+   ```
+
+   This starts Spotlight on `http://localhost:8969`.
+
+2. In another terminal, start the dev server with Spotlight enabled:
+
+   ```bash
+   # macOS / Linux
+   SPOTLIGHT=true pnpm dev
+   ```
+
+   ```powershell
+   # Windows (PowerShell)
+   $env:SPOTLIGHT='true'; pnpm dev
+   ```
+
+3. Open `http://localhost:8969` to inspect events captured from your dev session.
+
+Spotlight is opt-in — Sentry stays silent in dev by default. Production behavior is unchanged.
+
 ## Troubleshooting
 
 If you run into issues during development (e.g. `pnpm dev` hanging, TypeScript errors after pulling, lock file conflicts), see [TROUBLESHOOTING.md](TROUBLESHOOTING.md) for common fixes.

global.d.ts

@@ -2,6 +2,7 @@ declare const __COMFYUI_FRONTEND_VERSION__: string
 declare const __COMFYUI_FRONTEND_COMMIT__: string
 declare const __SENTRY_ENABLED__: boolean
 declare const __SENTRY_DSN__: string
+declare const __SPOTLIGHT_ENABLED__: boolean
 declare const __ALGOLIA_APP_ID__: string
 declare const __ALGOLIA_API_KEY__: string
 declare const __USE_PROD_CONFIG__: boolean

scripts/vite-define-shim.ts

@@ -8,6 +8,7 @@ declare global {
   const __COMFYUI_FRONTEND_VERSION__: string
   const __SENTRY_ENABLED__: boolean
   const __SENTRY_DSN__: string
+  const __SPOTLIGHT_ENABLED__: boolean
   const __ALGOLIA_APP_ID__: string
   const __ALGOLIA_API_KEY__: string
   const __USE_PROD_CONFIG__: boolean
@@ -19,6 +20,7 @@ type GlobalWithDefines = typeof globalThis & {
   __COMFYUI_FRONTEND_VERSION__: string
   __SENTRY_ENABLED__: boolean
   __SENTRY_DSN__: string
+  __SPOTLIGHT_ENABLED__: boolean
   __ALGOLIA_APP_ID__: string
   __ALGOLIA_API_KEY__: string
   __USE_PROD_CONFIG__: boolean
@@ -34,6 +36,7 @@ globalWithDefines.__COMFYUI_FRONTEND_VERSION__ =
   process.env.npm_package_version || '1.0.0'
 globalWithDefines.__SENTRY_ENABLED__ = false
 globalWithDefines.__SENTRY_DSN__ = ''
+globalWithDefines.__SPOTLIGHT_ENABLED__ = false
 globalWithDefines.__ALGOLIA_APP_ID__ = ''
 globalWithDefines.__ALGOLIA_API_KEY__ = ''
 globalWithDefines.__USE_PROD_CONFIG__ = false

src/main.ts

@@ -56,30 +56,57 @@ const sentryDsn = isCloud
   ? configValueOrDefault(remoteConfig.value, 'sentry_dsn', __SENTRY_DSN__)
   : __SENTRY_DSN__
 
+// Spotlight (https://spotlightjs.com) is the local Sentry dev overlay. When
+// opted-in via SPOTLIGHT=true in dev, initialize Sentry so events forward to
+// the local sidecar; production wiring is unchanged.
+//
+// Spotlight requires a DSN to initialize; this local placeholder is fine
+// because events are redirected to the sidecar and never leave the machine.
+const SPOTLIGHT_PLACEHOLDER_DSN = 'https://spotlight@local/0'
+
+const cloudSentryOpts = {
+  integrations: [
+    // Disable event target wrapping to reduce overhead on high-frequency
+    // DOM events (pointermove, mousemove, wheel). Sentry still captures
+    // errors via window.onerror and unhandledrejection.
+    Sentry.browserApiErrorsIntegration({ eventTarget: false })
+  ]
+}
+
+const spotlightSentryOpts = {
+  integrations: [
+    Sentry.spotlightBrowserIntegration(),
+    Sentry.browserTracingIntegration(),
+    Sentry.consoleLoggingIntegration({
+      levels: ['log', 'info', 'warn', 'error', 'debug']
+    })
+  ],
+  enableLogs: true
+}
+
+const silentSentryOpts = {
+  integrations: [],
+  autoSessionTracking: false,
+  defaultIntegrations: false
+}
+
+const sentryEnvironmentOpts = isCloud
+  ? cloudSentryOpts
+  : __SPOTLIGHT_ENABLED__
+    ? spotlightSentryOpts
+    : silentSentryOpts
+
 Sentry.init({
   app,
-  dsn: sentryDsn,
-  enabled: __SENTRY_ENABLED__,
+  dsn:
+    __SPOTLIGHT_ENABLED__ && !sentryDsn ? SPOTLIGHT_PLACEHOLDER_DSN : sentryDsn,
+  enabled: __SENTRY_ENABLED__ || __SPOTLIGHT_ENABLED__,
   release: __COMFYUI_FRONTEND_VERSION__,
   normalizeDepth: 8,
-  tracesSampleRate: isCloud ? 1.0 : 0,
+  tracesSampleRate: isCloud || __SPOTLIGHT_ENABLED__ ? 1.0 : 0,
   replaysSessionSampleRate: 0,
   replaysOnErrorSampleRate: 0,
-  // Only set these for non-cloud builds
-  ...(isCloud
-    ? {
-        integrations: [
-          // Disable event target wrapping to reduce overhead on high-frequency
-          // DOM events (pointermove, mousemove, wheel). Sentry still captures
-          // errors via window.onerror and unhandledrejection.
-          Sentry.browserApiErrorsIntegration({ eventTarget: false })
-        ]
-      }
-    : {
-        integrations: [],
-        autoSessionTracking: false,
-        defaultIntegrations: false
-      })
+  ...sentryEnvironmentOpts
 })
 app.directive('tooltip', Tooltip)
 app

vite.config.mts

@@ -622,6 +622,12 @@ export default defineConfig({
       !(process.env.NODE_ENV === 'development' || !process.env.SENTRY_DSN)
     ),
     __SENTRY_DSN__: JSON.stringify(process.env.SENTRY_DSN || ''),
+    // Spotlight is the local Sentry dev overlay (https://spotlightjs.com).
+    // Enabled only for dev, non-cloud builds, and only when the developer
+    // opts in via SPOTLIGHT=true so Sentry stays silent by default.
+    __SPOTLIGHT_ENABLED__: JSON.stringify(
+      IS_DEV && DISTRIBUTION !== 'cloud' && process.env.SPOTLIGHT === 'true'
+    ),
     __ALGOLIA_APP_ID__: JSON.stringify(process.env.ALGOLIA_APP_ID || ''),
     __ALGOLIA_API_KEY__: JSON.stringify(process.env.ALGOLIA_API_KEY || ''),
     __USE_PROD_CONFIG__: process.env.USE_PROD_CONFIG === 'true',

vitest.setup.ts

@@ -43,6 +43,7 @@ declare global {
 globalThis.__COMFYUI_FRONTEND_VERSION__ = '1.24.0'
 globalThis.__SENTRY_ENABLED__ = false
 globalThis.__SENTRY_DSN__ = ''
+globalThis.__SPOTLIGHT_ENABLED__ = false
 globalThis.__ALGOLIA_APP_ID__ = ''
 globalThis.__ALGOLIA_API_KEY__ = ''
 globalThis.__USE_PROD_CONFIG__ = false