[Violation] Permissions policy violation: unload is not allowed in this document.

[how2j-coder]

[Violation] Permissions policy violation: unload is not allowed in this document.

Description

When running a Next.js application in Chrome/Edge browsers, the console shows a permissions policy violation warning: [Violation] Permissions policy violation: unload is not allowed in this document.

Steps to Reproduce

1. Create a new Next.js project: npx create-next-app@latest
2. Run the development server: npm run dev
3. Open http://localhost:3000 in Chrome/Edge
4. Open Developer Tools (F12) and check the Console
5. Navigate to another page or close the tab

Expected behavior: No permissions policy violations in console.

Actual behavior: Console shows: [Violation] Permissions policy violation: unload is not allowed in this document.

Code Example

The error appears without any custom unload event listeners. However, it can be reproduced by adding:

// In any component or page
useEffect(() => {
  window.addEventListener('unload', () => {
    console.log('Page unloading');
  });
  
  return () => {
    window.removeEventListener('unload', () => {
      console.log('Page unloading');
    });
  };
}, []);

Root Cause

Chrome/Edge browsers have implemented stricter Permissions Policies to improve performance and security. The unload event is being deprecated because it prevents pages from using the back/forward cache (bfcache), which significantly impacts user experience during navigation.

The default Permissions Policy in modern browsers restricts unload unless explicitly allowed.

Environment

• Next.js Version: 14.x+ (but affects earlier versions too)
• Node.js Version: 18.x+
• Browser: Chrome 115+, Edge 115+
• OS: macOS, Windows, Linux
• Reproduction: Both development and production builds

Possible Solutions

1. Replace unload with pagehide (Recommended)

// Instead of:
window.addEventListener('unload', handler);

// Use:
window.addEventListener('pagehide', (event) => {
  if (event.persisted) {
    // Page is being cached in bfcache
  } else {
    // Page is being unloaded
  }
});

2. Configure Permissions Policy in Next.js

// next.config.js
module.exports = {
  async headers() {
    return [
      {
        source: '/(.*)',
        headers: [
          {
            key: 'Permissions-Policy',
            value: 'unload=self' // Allow unload for same origin
          }
        ]
      }
    ]
  }
}

3. Use Middleware (Next.js 12+)

// middleware.js
import { NextResponse } from 'next/server'

export function middleware(request) {
  const response = NextResponse.next()
  response.headers.set('Permissions-Policy', 'unload=self')
  return response
}

Related Issues

• Chrome's plan to deprecate unload: https://developer.chrome.com/blog/page-lifecycle-api/#the-unload-event
• bfcache optimization: https://web.dev/bfcache/
• Permissions Policy specification: https://w3c.github.io/webappsec-permissions-policy/

Additional Context

1. This warning appears even when no explicit unload listeners are added, suggesting Next.js internals or third-party libraries might be using it.
2. The warning doesn't break functionality but indicates future compatibility issues.
3. Using pagehide instead of unload enables bfcache, improving navigation performance by up to 10x.
4. For analytics or cleanup operations, consider visibilitychange + sendBeacon instead of unload.

Workaround Status

• ✅ Short-term: Configure Permissions Policy header
• ✅ Medium-term: Audit and replace unload usage in codebase
• ✅ Long-term: Adopt Page Lifecycle API (pagehide/pageshow)

Request

1. Could the Next.js team audit internal usage of unload events?
2. Consider updating templates/documentation to recommend pagehide over unload
3. Provide guidance for handling third-party libraries that use unload

---

Labels: bug, browser-compatibility, performance, documentation

Additional information

No response

Example

No response