Common Netlify pitfalls and fixes — widget timing, redirect loops, script loading order, JWT refresh, deploy branch mismatch
Error: Registering widget.on('init', callback) inside DOMContentLoaded. The widget fires init before DOMContentLoaded, so the callback never runs → page stays blank.
Correct: Register immediately after the widget script tag. Add widget.currentUser() as synchronous fallback + setTimeout safety net.
Error: Using /* catch-all with force=true without a passthrough for public pages. This catches the login page itself → 404 or redirect loop.
Correct: Always add explicit passthrough rules for public pages BEFORE catch-all role-gated rules.
Error: Using DOMContentLoaded to initialize code that depends on external CDN scripts. Those scripts may not be ready yet.
Correct: Either use window.addEventListener('load', ...) or put inline script AFTER external script tags (synchronous scripts block parsing, so they'll be ready).
Error: Assigning a role to a user and expecting it to work immediately.
Correct: User must log out and log back in. JWT is only refreshed on login or refreshSession().
GoTrue JS logs loud warnings about HTTP in development — safe to ignore locally. Only HTTPS matters in production (Netlify handles this).
Error: Pushing to main when Netlify production branch is set to a different branch.
Correct: Always check which branch Netlify deploys from before pushing. Push to the correct branch or both.