docs: Improve Content Security Policy documentation #80580
Conversation
- Add detailed explanation of how nonces flow through Next.js rendering system - Document static vs dynamic rendering implications and performance trade-offs - Add experimental SRI (Subresource Integrity) configuration documentation - Include development vs production CSP considerations - Add comprehensive troubleshooting section for common CSP issues - Provide practical examples for different CSP implementation approaches - Address community feedback from Reddit thread about CSP documentation gaps Addresses community concerns about: - Lack of clarity on nonce propagation through Next.js - Missing documentation on hash-based CSP alternatives - Performance implications not clearly explained - Production deployment issues with nonces - Static site generation challenges with strict CSP Co-Authored-By: lee@vercel.com <lee@vercel.com>
🤖 Devin AI EngineerI'll be helping with this pull request! Here's what you should know: ✅ I will automatically:
Note: I can only respond to comments from users who have write access to this repository. ⚙️ Control Options:
|
|
Allow CI Workflow Run
Note: this should only be enabled once the PR is ready to go and can only be enabled by a maintainer |
- Replace 'sha256-{hash-will-be-generated}' with proper comment explaining Next.js automatic hash insertion
- Addresses graphite-app[bot] feedback about invalid CSP syntax that would cause policy errors
Co-Authored-By: lee@vercel.com <lee@vercel.com>
|
DevinAI can you address the comments from @icyJoseph? |
- Clarify build behavior: builds succeed but runtime errors may occur - Add PPR incompatibility note for nonce-based CSP - Remove incorrect CSP header from request headers (CSP should only be on response) - Add complete error boundary example for handling CSP violations - Wrap SRI sections in AppOnly since they're App Router exclusive - Wrap Static Site example in AppOnly for consistency Addresses all actionable comments from @icyJoseph on PR #80580 Co-Authored-By: lee@vercel.com <lee@vercel.com>
|
I've removed the combined approach snippets - which we haven't verified, some simple testing showed it to be broken, but perhaps I was doing something wrong. I've also removed the Error Boundary handling. I want to verify if the other error handling recommendations, do in fact work. These type of CSP issues, mostly show up in the browser logs. Often you can still see content, but interactivity is broken. |
| // Force dynamic rendering for pages using nonces | ||
| import { connection } from 'next/server' | ||
|
|
||
| export default function Page() { |
There was a problem hiding this comment.
The function declaration is missing the async keyword but uses await connection() inside the function body, causing a syntax error.
View Details
Analysis
In the "Forcing dynamic rendering" section, both the TypeScript and JavaScript examples show function declarations that use await connection() without marking the functions as async. This is a syntax error in JavaScript/TypeScript.
The current code shows:
export default function Page() {
await connection()
// Your page content
}This will cause a compilation error because await can only be used inside async functions. The error will prevent the code from running and could mislead developers trying to implement CSP with Next.js.
Recommendation
Add the async keyword to both function declarations on lines 199 and 209:
export default async function Page() {
await connection()
// Your page content
}This matches the pattern used consistently in other examples throughout the documentation where await is used with Next.js APIs like headers().
| // Force dynamic rendering for pages using nonces | ||
| import { connection } from 'next/server' | ||
|
|
||
| export default function Page() { |
|
@icyJoseph I think the section about Using SRI with CSP is just wrong.
Have you verified this or was this just AI hallucination? Edit: I might be wrong, as I just saw that the the CSP is set in the |
|
Yeah I tested these, but there were some paper cuts for sure. Most of the time spent on this PR was verifying claims. Let me just test once again I have an app with SRI. Edit: Building the app with the csp header from next.config file I did also run into the client chunks issue when testing this. |
|
@darthmaim I see the issue now - ugh - PR coming up |
Improve Content Security Policy Documentation
This PR comprehensively improves the Next.js Content Security Policy (CSP) documentation to address community feedback from Reddit and GitHub discussions about gaps in the current documentation.
Changes Made
1. Enhanced Nonce Flow Explanation
2. Static vs Dynamic Rendering Documentation
3. Experimental SRI (Subresource Integrity) Documentation
sri.algorithmconfiguration option4. Development vs Production Considerations
'unsafe-eval'in development for HMR5. Comprehensive Troubleshooting Section
6. Practical Examples
7. Enhanced Pages Router Documentation
_document.tsxnonce access examplegetServerSidePropsexamplesCommunity Feedback Addressed
This PR directly addresses the Reddit thread feedback about:
Technical Details
docs/01-app/02-guides/content-security-policy.mdxTesting
Link to Devin run: https://app.devin.ai/sessions/e7e5fa95dc0146b3ab79aac72c53ed13
Requested by: lee@vercel.com