Merge pull request #58 from LayerXcom/feat/disable-for-testing

Add disableForTesting option to useNavigationGuard

Author: ypresto

.github/workflows/e2e-tests.yml

@@ -24,6 +24,7 @@ jobs:
             "15.4",
             "15.5",
             "16.0",
+            "16.1",
           ]
         node-version: [20]
     steps:

CHANGELOG

@@ -7,6 +7,13 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.3.0] - 2026-02-26
+
+### Added
+
+- Add `disableForTesting` option to `useNavigationGuard` to make the hook a complete no-op without requiring `NavigationGuardProvider` context, intended for test and storybook environments.
+- Support Next.js 16 as peer dependency and add E2E CI targets for v16.0 and v16.1.
+
 ## [0.2.0] - 2025-06-28
 
 ### Added
@@ -38,7 +45,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 - The initial release of next-navigation-guard.
 
-[unreleased]: https://github.com/LayerXcom/next-navigation-guard/compare/v0.2.0...HEAD
+[unreleased]: https://github.com/LayerXcom/next-navigation-guard/compare/v0.3.0...HEAD
+[0.3.0]: https://github.com/LayerXcom/next-navigation-guard/compare/v0.2.0...v0.3.0
 [0.2.0]: https://github.com/LayerXcom/next-navigation-guard/releases/tag/v0.2.0
 [0.1.2]: https://github.com/LayerXcom/next-navigation-guard/releases/tag/v0.1.2
 [0.1.1]: https://github.com/LayerXcom/next-navigation-guard/releases/tag/v0.1.1

package.json

@@ -1,6 +1,6 @@
 {
   "name": "next-navigation-guard",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Navigation Guard for Next.js App Router and Pages Router.",
   "main": "./dist/index.js",
   "module": "./dist/index.js",
@@ -32,7 +32,7 @@
   },
   "packageManager": "pnpm@9.9.0+sha512.60c18acd138bff695d339be6ad13f7e936eea6745660d4cc4a776d5247c540d0edee1a563695c183a66eb917ef88f2b4feb1fc25f32a7adcadc7aaf3438e99c1",
   "peerDependencies": {
-    "next": "^14 || ^15",
+    "next": "^14 || ^15 || ^16",
     "react": "^18.0.0 || ^19.0.0 || ^19.0.0-rc"
   },
   "devDependencies": {

src/hooks/useNavigationGuard.ts

@@ -8,7 +8,7 @@ import { debug } from "../utils/debug";
 export function useNavigationGuard(options: NavigationGuardOptions) {
   const callbackId = useId();
   const guardMapRef = useContext(NavigationGuardProviderContext);
-  if (!guardMapRef)
+  if (!guardMapRef && !options.disableForTesting)
     throw new Error(
       "useNavigationGuard must be used within a NavigationGuardProvider"
     );
@@ -18,6 +18,8 @@ export function useNavigationGuard(options: NavigationGuardOptions) {
   } | null>(null);
 
   useIsomorphicLayoutEffect(() => {
+    if (options.disableForTesting) return;
+
     const callback: NavigationGuardCallback = (params) => {
       debug(`Guard callback called with:`, params);
       if (options.confirm) {
@@ -36,17 +38,17 @@ export function useNavigationGuard(options: NavigationGuardOptions) {
 
     const enabled = options.enabled;
 
-    guardMapRef.current.set(callbackId, {
+    guardMapRef!.current.set(callbackId, {
       enabled: typeof enabled === "function" ? enabled : () => enabled ?? true,
       callback,
     });
 
     return () => {
-      guardMapRef.current.delete(callbackId);
+      guardMapRef!.current.delete(callbackId);
     };
-  }, [callbackId, guardMapRef, options.confirm, options.enabled]);
+  }, [callbackId, guardMapRef, options.confirm, options.enabled, options.disableForTesting]);
 
-  const active = pendingState !== null;
+  const active = options.disableForTesting ? false : pendingState !== null;
 
   const accept = useCallback(() => {
     if (!pendingState) return;

src/types.ts

@@ -2,6 +2,13 @@ export interface NavigationGuardOptions {
   /** @default true */
   enabled?: boolean | ((params: NavigationGuardParams) => boolean);
   confirm?: NavigationGuardCallback;
+  /**
+   * When true, the hook becomes a complete no-op: no guard is registered,
+   * NavigationGuardProvider context is not required, and `active` is always false.
+   * Intended for test and storybook environments.
+   * @default false
+   */
+  disableForTesting?: boolean;
 }
 
 export interface NavigationGuardParams {