This section documents version-specific API changes in nuxt-security v2.x — prioritize recent major/minor releases and breaking changes.
-
NEW: nonce support in development (style nonce) — v2.0.0 added automatic style nonce generation for development builds, pairs with existing script nonce functionality source
-
NEW: NuxtIsland (server-only components) support — v2.0.0 enabled security headers delivery for server-only components, headers properly applied to island responses source
-
NEW: Vite-native logger removal — v2.1.0 introduced native Vite method for removing console loggers as alternative to regex-based approach, set removeLoggers: true or use RemoveOptions object for configuration (deprecated, use boolean instead) source
-
NEW: Trusted Types CSP support — v2.1.0 added CSP trusted types directive configuration to defend against DOM-based XSS in applications using Trusted Types API source
-
NEW: Cloudflare Workers crypto compatibility — v2.1.0 added support for crypto APIs in Cloudflare Workers runtime, enables SRI and nonce generation in edge computing environments source
-
NEW: SRI virtual file system — v2.0.0 replaced cheerio with regex-based HTML parsing for Subresource Integrity calculation, dramatically reduces bundle size for edge runtimes source
-
Start with default configuration (strict: false) and only add restrictions as needed. Nuxt Security's defaults provide an A+ Mozilla Observatory score without breaking typical applications — gradually migrate to strict mode once your app is stable source
-
Use defuReplaceArray (not defu) when merging CSP directives in runtime hooks — it replaces array values entirely, whereas defu appends to them, which can cause unintended directives to persist source
-
Prefer the useScript composable over useHead for loading external scripts under Strict CSP — it's isomorphic, automatically loaded under 'strict-dynamic', handles async loading, and avoids inline event handlers that CSP can block source
-
Use useState in composables instead of global ref declarations to prevent Cross-Request State Pollution in SSR — each request gets isolated state, preventing unintended data leaks between users source
-
Restrict API response payloads using pick in useFetch/useAsyncData to return only required fields — avoids leaking sensitive data like email addresses or payment info to the client source
-
Recognize that the built-in rate limiter is unsuitable for complex production applications — use infrastructure-layer solutions like Cloudflare DDoS protection or fail2ban instead source
-
Configure rate limiter drivers with camelCase names (vercelKv, not vercel-kv) when switching from the default lruCache to unstorage backends — the naming convention is critical for unstorage driver resolution source
-
Use the nuxt-security:routeRules Nitro hook to fetch security configuration at runtime from external secret managers — enables multi-tenant deployments and keeps secrets out of build artifacts source
-
Enable contentSecurityPolicyReportOnly: true during development to monitor CSP violations without blocking content — switch to enforcing mode in production after validating all legitimate resources source
-
Disable specific security headers for third-party services (e.g., crossOriginOpenerPolicy: false for Firebase Auth, crossOriginEmbedderPolicy: 'unsafe-none' for Cloudflare) — most integration issues stem from COEP/COOP incompatibility with external APIs source
-
Force a full page reload when navigating to routes with different headers using <NuxtLink :external="true"> or a route middleware — client-side navigation skips server header calculation, so CSP policies won't update unless you reload source
-
In SSG Strict CSP deployments, load external scripts via useScript in client-only mode rather than injecting them at build time — prevents integrity hash mismatches when static hosting providers modify assets source
-
Place security configuration in the security property of routeRules, not the standard headers property — the security property is namespaced to avoid conflicts and takes precedence when both are defined source
-
Never combine nonces or hashes with 'unsafe-inline' for the same directive — they cancel each other out, reverting to unrestricted inline execution source
