0
# PWA Module
1

2
The main PWA module coordinates all sub-modules and handles the overall PWA setup process for Nuxt.js applications.
3

4
## Capabilities
5

6
### Main Module Function
7

8
The primary entry point that orchestrates all PWA functionality during the Nuxt.js build process.
9

10
```typescript { .api }
11
/**
12
 * Main PWA module function for Nuxt.js
13
 * @param moduleOptions - Configuration options for all PWA sub-modules
14
 */
15
function pwa(moduleOptions: PWAOptions): Promise<void>;
16

17
interface PWAOptions {
18
  /** Meta tag configuration options or false to disable */
19
  meta?: Partial<MetaOptions> | false;
20
  /** Icon generation options or false to disable */
21
  icon?: Partial<IconOptions> | false;
22
  /** Service worker and caching options or false to disable */
23
  workbox?: Partial<WorkboxOptions> | false;
24
  /** Web app manifest options or false to disable */
25
  manifest?: Partial<ManifestOptions> | false;
26
}
27
```
28

29
**Usage Example:**
30

31
```typescript
32
// nuxt.config.ts
33
export default {
34
  modules: ['@nuxtjs/pwa'],
35
  pwa: {
36
    meta: {
37
      name: 'My PWA',
38
      description: 'Progressive Web Application'
39
    },
40
    icon: {
41
      sizes: [192, 384, 512]
42
    },
43
    workbox: {
44
      offline: true
45
    },
46
    manifest: {
47
      background_color: '#ffffff'
48
    }
49
  }
50
}
51
```
52

53
### Module Orchestration
54

55
The module handles coordination between sub-modules and manages the build process.
56

57
```typescript { .api }
58
/**
59
 * PWA context shared between all sub-modules
60
 */
61
interface PWAContext {
62
  meta?: MetaOptions;
63
  icon?: IconOptions;
64
  workbox?: WorkboxOptions;
65
  manifest?: ManifestOptions;
66
  _manifestMeta: any;
67
}
68
```
69

70
The module automatically:
71
- Processes configuration options for each sub-module
72
- Executes sub-modules in the correct sequence (icon → manifest → meta → workbox)
73
- Handles build-time vs runtime behavior
74
- Sets up development middleware for asset serving
75

76
### Configuration Inheritance
77

78
The module supports configuration inheritance from top-level Nuxt options:
79

80
```typescript
81
// nuxt.config.ts
82
export default {
83
  modules: ['@nuxtjs/pwa'],
84
  // Top-level configuration (backward compatibility)
85
  meta: {
86
    name: 'My App'
87
  },
88
  // PWA-specific configuration (preferred)
89
  pwa: {
90
    meta: {
91
      description: 'My PWA App' // Merged with top-level
92
    }
93
  }
94
}
95
```
96

97
### Development Mode
98

99
The module includes special handling for development mode:
100

101
```typescript { .api }
102
/**
103
 * Runtime meta loading for SPA mode
104
 */
105
function metaRuntime(nuxt: any): void;
106
```
107

108
```typescript { .api }
109
/**
110
 * Build mode detection and handling
111
 */
112
interface BuildModes {
113
  /** Standard build process */
114
  isBuild: boolean;      // nuxt.options._build
115
  /** Static site generation */
116
  isGenerate: boolean;   // nuxt.options.target === 'static' && !nuxt.options.dev
117
  /** Runtime/development mode */
118
  isRuntime: boolean;    // !isBuild && !isGenerate
119
}
120
```
121

122
In development, the module:
123
- Serves static assets through middleware from `buildDir/dist/client`
124
- Enables hot reloading for PWA assets
125
- Provides debugging information
126
- Skips resource-intensive operations when appropriate
127
- Only loads meta.json for SPA renderer in runtime mode
128

129
### Module Registration
130

131
The module integrates with Nuxt.js module system using standard patterns:
132

133
```typescript { .api }
134
/**
135
 * Package metadata from package.json
136
 */
137
const PKG = {
138
  name: '@nuxtjs/pwa',
139
  version: '3.3.5'
140
};
141

142
// Module metadata for Nuxt.js
143
pwa.meta = PKG;
144
```
145

146
**Module Declaration:**
147

148
```typescript { .api }
149
declare module '@nuxt/types/config/index' {
150
  interface NuxtOptions {
151
    pwa?: Partial<PWAOptions>;
152
    meta?: Partial<MetaOptions> | false;
153
    icon?: Partial<IconOptions> | false;
154
    workbox?: Partial<WorkboxOptions> | false;
155
    manifest?: Partial<ManifestOptions> | false;
156
  }
157
}
158
```
159

160
### Error Handling
161

162
The module includes robust error handling:
163
- Graceful degradation when assets are missing
164
- Warning messages for configuration issues
165
- Validation of required dependencies
166
- Safe fallbacks for missing icons or manifests