docs(cookbook): add SSG and CSP considerations to theme management#8231
Conversation
|
There was a problem hiding this comment.
Pull request overview
This PR significantly expands the Theme Management cookbook with comprehensive guidance for production scenarios. It addresses common challenges with dark mode implementation in Qwik applications, particularly for Static Site Generation (SSG) deployments and Content Security Policy (CSP) compliance.
Key changes include:
- Complete rewrite with improved clarity and modern JavaScript practices
- Detailed explanations of SSG considerations and why inline scripts prevent theme flicker
- Documentation of three CSP approaches (unsafe-inline, nonces, and script hashes)
- Multiple code examples showing different implementation patterns
- New troubleshooting section for common issues
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
- Change var to const in inline scripts - Use classList.add/remove instead of className for consistency - Add aria-hidden to decorative SVG icons - Add note about ThemeToggle component reuse in complete example - Add security note about unsafe-inline trade-offs - Add comment explaining ThemeToggle placement
commit: |
built with Refined Cloudflare Pages Action⚡ Cloudflare Pages Deployment
|
maiieul
left a comment
maiieul
left a comment
There was a problem hiding this comment.
Thanks @chindris-mihai-alexandru good additions and improvements overall. Can you address my comments before I click the merge button? 🤓
- Remove useVisibleTask$ example (simpler onClick$ approach is sufficient) - Strengthen CSP security note wording per maintainer suggestion - Remove redundant Complete Example for SSG section - Update troubleshooting to reflect CSS-based icon visibility approach
done ✅ |
maiieul
left a comment
maiieul
left a comment
There was a problem hiding this comment.
Thanks @chindris-mihai-alexandru good job!
gioboa
left a comment
gioboa
left a comment
There was a problem hiding this comment.
Thanks @chindris-mihai-alexandru for your help 👏
Summary
This PR expands the Theme Management cookbook with practical guidance for common production scenarios:
useVisibleTask$alone causes theme flickeruseVisibleTask$withdocument-readystrategy: Shows how to sync toggle button state after hydration without causing flickerunsafe-inline, nonces for SSR, script hashes)root.tsxsetup for Cloudflare Pages and similar static hostsThis addresses the patterns discussed in closed issue #3391 (dark mode flicker) by documenting the recommended solutions that the community discovered.
Type of change
Checklist