Registry / type-stubs / navigation-api-types

navigation-api-types

JSON →
library0.6.1jsnpmunverified

This package provides comprehensive TypeScript type definitions for the W3C Navigation API, accessible via `window.navigation` in modern browsers. It is a types-only package, meaning it does not include a polyfill or runtime implementation of the API, focusing solely on providing accurate typings for development. The current stable version is 0.6.1, with releases occurring periodically to align with updates and changes in the Navigation API specification. Its primary differentiator is offering early access to these types, enabling developers to leverage the Navigation API in TypeScript projects before broader `lib.dom` support or for specific browser targetting, ensuring type safety and improved developer experience.

npm install navigation-api-types
INSTALL
IMPORT
SIG · NAVIGATION-API-TYP
N
navigation-api-types
type-stubsjavascriptv0.6.1
Install
Import
Disk
Pass rate
0/ 6
Env Coverage0 / 6
glibc
1822
musl
1822
Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
node 18226 runs
build_error
glibc
node 18226 runs
build_error
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

All types (global ambient)
/// <reference types="navigation-api-types" /> // (Place this in a global .d.ts file, e.g., src/global.d.ts)
import 'navigation-api-types';
To make all Navigation API types (like `Navigation`, `NavigateEvent`, etc.) globally available across your entire project, place this triple-slash directive in a `.d.ts` file. This file must *not* contain any `import` or `export` statements to be treated as an ambient declaration file by TypeScript.
All types (file-specific)
/// <reference types="navigation-api-types" /> // (Place this at the top of a .ts file)
import type { Navigation } from 'navigation-api-types';
Use this directive at the top of specific `.ts` files if you only need the Navigation API types available within those files, avoiding global pollution. The package provides ambient types, so standard module `import` syntax will not work for accessing them.
NavigationEvent
declare const event: NavigationEvent;
import { NavigationEvent } from 'navigation-api-types';
Once the `/// <reference types="navigation-api-types" />` directive is correctly set up (either globally or file-specifically), types like `NavigationEvent`, `Navigation`, `NavigationHistoryEntry`, etc., become directly available in your TypeScript context without needing explicit `import` statements.

This example demonstrates how to set up the global ambient types for the Navigation API and then use `window.navigation` with full type safety to add event listeners and access properties, preventing TypeScript errors.

import './src/global.d.ts'; // Ensure your global type definitions are included (or adjust path) // src/global.d.ts (or similar file in your project): // /// <reference types="navigation-api-types" /> // --- main.ts (or any application file) --- function setupNavigationListener() { if ('navigation' in window) { console.log('Navigation API is supported.'); // 'navigation' property now has types due to the reference directive window.navigation.addEventListener('navigate', (event: NavigateEvent) => { console.log(`Navigation event caught: ${event.destination.url}`); if (event.destination.url.includes('/sensitive')) { event.intercept({ async handler() { console.log('Intercepting navigation to sensitive area.'); // Simulate some async work, e.g., auth check await new Promise(resolve => setTimeout(resolve, 500)); console.log('Navigation intercepted and handled.'); // You might redirect or prevent default here } }); } }); console.log('Navigation event listener added.'); } else { console.warn('Navigation API is not supported in this browser.'); } } setupNavigationListener(); // Example of directly accessing a typed API property if ('navigation' in window && window.navigation.currentEntry) { console.log('Current navigation entry ID:', window.navigation.currentEntry.id); } // To make this runnable, ensure a tsconfig.json is set up to include global.d.ts // and compile with tsc.
Debug
Known issues
breakingVersions 0.3.1 and 0.4.0 introduced breaking changes by deprecating and removing older type definitions to align with updates in the Navigation API specification. Specifically, `0.4.0` removed deprecated types and added `hasUAVisualTransition` to `NavigateEvent`.
fix
Review the package's changelog for specific changes and update your code to use the latest type definitions and adhere to the current Navigation API specification. This may involve renaming types or adjusting property access.
affects: >=0.3.1
gotchaWhen using a global `.d.ts` file (e.g., `src/global.d.ts`) to make `navigation-api-types` ambiently available, the file must *not* contain any `import` or `export` statements. If such statements are present, TypeScript will treat the file as a module, causing the types to no longer be implicitly available globally.
fix
Ensure your global `.d.ts` file contains only `/// <reference types="navigation-api-types" />` and other ambient declarations, without any `import` or `export` keywords.
affects: >=0.1.0
gotchaThis package provides ambient type definitions, which are made available via triple-slash reference directives (`/// <reference types="..." />`). Attempting to import types using standard ES module syntax (e.g., `import type { Navigation } from 'navigation-api-types';`) will not work, as the types are not exported as named module members.
fix
Always use `/// <reference types='navigation-api-types' />` at the top of your `.ts` files or in a global `.d.ts` file to make the types available. Do not use `import` statements for this package's types.
affects: >=0.1.0
Errors
Common errors & fixes
Property 'navigation' does not exist on type 'Window & typeof globalThis'.
The TypeScript compiler cannot find the ambient type definitions for `window.navigation`.
fix
Ensure you have correctly added `/// <reference types="navigation-api-types" />` to either a global `.d.ts` file or at the top of the specific `.ts` file where you are using `window.navigation`.
Cannot find name 'NavigateEvent'.
Specific types provided by `navigation-api-types` are not recognized by the TypeScript compiler.
fix
Verify that your `/// <reference types="navigation-api-types" />` directive is correctly placed and visible to TypeScript according to your `tsconfig.json` settings. For global availability, ensure the `.d.ts` file containing the directive is not treated as a module (no `import`/`export` statements).
A 'global.d.ts' file must not contain any 'import' or 'export' declarations.
You've added `import` or `export` statements to a `.d.ts` file intended for ambient declarations, which causes TypeScript to treat it as a module.
fix
Remove all `import` and `export` statements from your `global.d.ts` (or similar ambient type declaration) file. It should only contain `declare` statements or triple-slash directives.
Upgrade
Version history
0.6.1latest on npm
Audit
Dependencies

No dependency data recorded yet.

Agent activity
22 hits · last 30 days
node
18
Amazon
1
OpenAI (training)
1
Resources
navigation-api-types — npm install navigation-api-types · libregistry