Troubleshooting

Apps

API calls fail with CORS errors in dev. The dev server proxies /api/* to the backend so requests are same-origin. If you see CORS errors, you're probably calling an absolute backend URL directly instead of a relative /api/... path.

Dev server rejects a backend response / header too large. One endpoint returns oversized headers; npm run dev tracking raises --max-http-header-size. Pass the same NODE_OPTIONS if you start Next another way.

Production build errors about SSR / Server Actions / Route Handlers. The prod build is output: "export". Remove the server-only code — see Architecture.

BLE code can't see the device / navigator.bluetooth is undefined. Go through the @enode/core BleService adapter, not navigator.bluetooth. Web Bluetooth needs a secure context (HTTPS/localhost) and a user gesture.

A change to @enode/core / @enode/ui isn't picked up. The packages ship TS source compiled by each app via transpilePackages. Restart the dev server after changing a shared package's public surface.

Documentation builds

The docs site is blank / loads wrong when I open it. The Docusaurus build is a single-page app and must be served over HTTP — opening docs-site/build/index.html as a file:// URL fails. Run npm run docs:serve (or npm run docs:start for live reload), both on :4000.

The TypeDoc / Storybook navbar links 404. They are served from docs-site/static/typedoc and docs-site/static/storybook, which npm run docs:build writes before building Docusaurus. Running docs:docusaurus alone won't (re)generate them — run the full docs:build.

Storybook story has no design-system styles. Tokens come from docs-site/.storybook/preview.css (Tailwind + @enode/ui/styles/design-system.css), processed by the @tailwindcss/vite plugin wired in docs-site/.storybook/main.ts. Confirm the class is a real token (see the tracking app's styleguide route).

TypeDoc warns "X is referenced but not included". Expected for internal helper types that aren't exported. Warnings don't fail the build.