0
# Workbox Navigation Preload
1

2
Workbox Navigation Preload provides a simple interface for enabling and disabling Navigation Preload functionality in service workers. Navigation Preload is a browser optimization that allows network requests to be started in parallel with service worker activation, reducing the time between navigation startup and network response.
3

4
## Package Information
5

6
- **Package Name**: workbox-navigation-preload
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install workbox-navigation-preload`
10
- **Dependencies**: `workbox-core@7.3.0`
11

12
## Core Imports
13

14
```typescript
15
import { enable, disable, isSupported } from "workbox-navigation-preload";
16
```
17

18
For CommonJS:
19

20
```javascript
21
const { enable, disable, isSupported } = require("workbox-navigation-preload");
22
```
23

24
## Basic Usage
25

26
```typescript
27
import { enable, disable, isSupported } from "workbox-navigation-preload";
28

29
// Check if Navigation Preload is supported
30
if (isSupported()) {
31
  // Enable Navigation Preload with default header
32
  enable();
33
  
34
  // Or enable with custom header value
35
  enable("custom-preload-header");
36
  
37
  // Disable Navigation Preload
38
  disable();
39
} else {
40
  console.log("Navigation Preload not supported in this browser");
41
}
42
```
43

44
## Architecture
45

46
Workbox Navigation Preload uses an event-driven architecture that integrates with the Service Worker lifecycle:
47

48
- **Event Listener Pattern**: Functions register `activate` event listeners on the service worker
49
- **Lifecycle Integration**: Uses `event.waitUntil()` to extend the activation lifecycle until operations complete
50
- **Asynchronous Operations**: All Navigation Preload API calls return promises that are properly awaited
51
- **Graceful Degradation**: Automatically checks browser support before attempting operations
52
- **Development Logging**: Provides runtime feedback via `workbox-core` logger utilities
53

54
## Capabilities
55

56
### Browser Support Detection
57

58
Checks whether Navigation Preload is supported in the current browser environment.
59

60
```typescript { .api }
61
/**
62
 * Checks if Navigation Preload is supported in the current browser
63
 * @returns true if supported, false otherwise
64
 */
65
function isSupported(): boolean;
66
```
67

68
**Usage Example:**
69

70
```typescript
71
import { isSupported } from "workbox-navigation-preload";
72

73
if (isSupported()) {
74
  console.log("Navigation Preload is available");
75
} else {
76
  console.log("Navigation Preload is not supported");
77
}
78
```
79

80
### Enable Navigation Preload
81

82
Enables Navigation Preload functionality with optional custom header configuration.
83

84
```typescript { .api }
85
/**
86
 * Enables Navigation Preload if supported by the browser
87
 * @param headerValue - Optional custom value for the Service-Worker-Navigation-Preload header
88
 */
89
function enable(headerValue?: string): void;
90
```
91

92
**Usage Examples:**
93

94
```typescript
95
import { enable } from "workbox-navigation-preload";
96

97
// Enable with default header (Service-Worker-Navigation-Preload: true)
98
enable();
99

100
// Enable with custom header value
101
enable("my-custom-preload-value");
102
```
103

104
**Behavior:**
105
- Checks browser support via `isSupported()` before proceeding
106
- Registers an 'activate' event listener on the service worker
107
- Uses `event.waitUntil()` to extend the activation event lifecycle until completion
108
- Asynchronously calls `self.registration.navigationPreload.enable()`
109
- Sets custom header value if provided via `self.registration.navigationPreload.setHeaderValue()`
110
- Provides development-time logging via `workbox-core/logger`
111
- Silently does nothing if Navigation Preload is not supported
112

113
### Disable Navigation Preload
114

115
Disables Navigation Preload functionality.
116

117
```typescript { .api }
118
/**
119
 * Disables Navigation Preload if supported by the browser
120
 */
121
function disable(): void;
122
```
123

124
**Usage Example:**
125

126
```typescript
127
import { disable } from "workbox-navigation-preload";
128

129
// Disable Navigation Preload
130
disable();
131
```
132

133
**Behavior:**
134
- Checks browser support via `isSupported()` before proceeding
135
- Registers an 'activate' event listener on the service worker
136
- Uses `event.waitUntil()` to extend the activation event lifecycle until completion
137
- Asynchronously calls `self.registration.navigationPreload.disable()`
138
- Provides development-time logging via `workbox-core/logger`
139
- Silently does nothing if Navigation Preload is not supported
140

141
## Type Definitions
142

143
```typescript { .api }
144
/**
145
 * Represents the current state of Navigation Preload
146
 */
147
interface NavigationPreloadState {
148
  enabled?: boolean;
149
  headerValue?: string;
150
}
151

152
/**
153
 * Interface for managing Navigation Preload functionality
154
 */
155
interface NavigationPreloadManager {
156
  disable(): Promise<void>;
157
  enable(): Promise<void>;
158
  getState(): Promise<NavigationPreloadState>;
159
  setHeaderValue(value: string): Promise<void>;
160
}
161
```
162

163
**Global Type Extension:**
164

165
```typescript { .api }
166
declare global {
167
  interface ServiceWorkerRegistration {
168
    readonly navigationPreload: NavigationPreloadManager;
169
  }
170
}
171

172
/**
173
 * Service Worker global scope interface
174
 */
175
interface ServiceWorkerGlobalScope extends WorkerGlobalScope {
176
  registration: ServiceWorkerRegistration;
177
  addEventListener(type: 'activate', listener: (event: ExtendableEvent) => void): void;
178
}
179

180
/**
181
 * Extendable event interface for service worker lifecycle events
182
 */
183
interface ExtendableEvent extends Event {
184
  waitUntil(f: Promise<any>): void;
185
}
186
```
187

188
## Service Worker Context Requirements
189

190
This library is designed to run in a Service Worker context and requires:
191

192
- `self` global scope (ServiceWorkerGlobalScope)
193
- `self.registration` property
194
- `self.registration.navigationPreload` API support
195

196
## Error Handling
197

198
The library handles unsupported browsers gracefully:
199

200
- All functions check `isSupported()` before attempting operations
201
- No exceptions are thrown for unsupported browsers
202
- Development-time logging indicates support status
203
- Functions become no-ops when Navigation Preload is unavailable
204

205
## Development vs Production Behavior
206

207
- **Development**: Provides console logging for all operations and support status
208
- **Production**: Logging is disabled via `process.env.NODE_ENV` checks