0
# Parcel WebManifest Transformer
1

2
Parcel transformer plugin for processing web app manifest files. Validates manifest structure against the Web App Manifest specification and resolves resource dependencies (icons, screenshots) for proper bundling.
3

4
## Package Information
5

6
- **Package Name**: @parcel/transformer-webmanifest
7
- **Package Type**: npm
8
- **Language**: JavaScript (Flow typed)
9
- **Installation**: `npm install @parcel/transformer-webmanifest`
10

11
## Core Imports
12

13
This transformer is automatically used by Parcel when processing `.webmanifest` files. No direct imports are typically needed in user code, as it integrates with Parcel's asset pipeline.
14

15
For direct usage (advanced):
16

17
```javascript
18
import transformer from "@parcel/transformer-webmanifest";
19
```
20

21
CommonJS:
22

23
```javascript
24
const transformer = require("@parcel/transformer-webmanifest");
25
```
26

27
**Dependencies used internally:**
28

29
```javascript
30
import { parse } from "@mischnic/json-sourcemap";
31
import { getJSONSourceLocation } from "@parcel/diagnostic";
32
import { Transformer } from "@parcel/plugin";
33
import { validateSchema } from "@parcel/utils";
34
```
35

36
## Basic Usage
37

38
This transformer is automatically used by Parcel for `.webmanifest` files. Simply include a web manifest in your project:
39

40
```json
41
// manifest.webmanifest
42
{
43
  "name": "My Web App",
44
  "short_name": "MyApp",
45
  "start_url": "/",
46
  "display": "standalone",
47
  "icons": [
48
    {
49
      "src": "./icons/icon-192.png",
50
      "sizes": "192x192",
51
      "type": "image/png"
52
    }
53
  ],
54
  "screenshots": [
55
    {
56
      "src": "./screenshots/desktop.png",
57
      "sizes": "1280x720",
58
      "type": "image/png"
59
    }
60
  ]
61
}
62
```
63

64
The transformer will:
65
1. Validate the manifest schema
66
2. Process resource URLs (icons, screenshots) as Parcel dependencies
67
3. Generate proper source location tracking for error reporting
68

69
## Capabilities
70

71
### Default Export
72

73
The main export is a configured Parcel Transformer instance that processes web manifest files.
74

75
```javascript { .api }
76
/**
77
 * Parcel transformer instance for web manifest files
78
 * Automatically validates schema and resolves resource dependencies
79
 */
80
export default transformer: Transformer;
81
```
82

83
### Transform Method
84

85
Core transformation functionality that processes web manifest assets.
86

87
```javascript { .api }
88
/**
89
 * Transforms web manifest JSON with validation and dependency resolution
90
 * @param options - Transform options containing the asset and other context
91
 * @param options.asset - The web manifest asset to transform
92
 * @param options.config - Transformer configuration (if any)
93
 * @param options.resolve - Function to resolve dependencies
94
 * @param options.options - Plugin options
95
 * @param options.logger - Plugin logger instance
96
 * @param options.tracer - Plugin tracer instance
97
 * @returns Promise resolving to array containing the transformed asset
98
 */
99
async function transform({
100
  asset,
101
  config,
102
  resolve,
103
  options,
104
  logger,
105
  tracer
106
}): Promise<Array<MutableAsset>>;
107
```
108

109
**Process:**
110
1. Parses JSON with source mapping using `@mischnic/json-sourcemap`
111
2. Validates against Web App Manifest schema
112
3. Converts resource URLs to Parcel dependencies with source location tracking
113
4. Sets asset type to 'webmanifest' and updates content
114

115
### Schema Validation
116

117
Built-in schema validation for Web App Manifest specification compliance using `validateSchema.diagnostic` function.
118

119
```javascript { .api }
120
/**
121
 * Validates manifest data against schema with detailed error reporting
122
 * @param schema - Schema entity defining validation rules
123
 * @param data - Data object containing source, map, and filePath
124
 * @param transformerName - Name of the transformer for error context
125
 * @param message - Error message for validation failures
126
 */
127
function validateSchema.diagnostic(
128
  schema: SchemaEntity,
129
  data: {
130
    source: string,
131
    map: { data: any, pointers: object },
132
    filePath: string
133
  },
134
  transformerName: string,
135
  message: string
136
): void;
137
```
138

139
**Schema Structure:**
140

141
```javascript { .api }
142
/**
143
 * Resource schema for validating icon and screenshot objects
144
 */
145
const RESOURCES_SCHEMA: SchemaEntity = {
146
  type: 'array',
147
  items: {
148
    type: 'object',
149
    properties: {
150
      src: {
151
        type: 'string',
152
        __validate: (s) => s.length === 0 ? 'Must not be empty' : undefined
153
      }
154
    },
155
    required: ['src']
156
  }
157
};
158

159
/**
160
 * Main manifest schema for validation
161
 */
162
const MANIFEST_SCHEMA: SchemaEntity = {
163
  type: 'object',
164
  properties: {
165
    icons: RESOURCES_SCHEMA,
166
    screenshots: RESOURCES_SCHEMA,
167
    shortcuts: {
168
      type: 'array',
169
      items: {
170
        type: 'object',
171
        properties: {
172
          icons: RESOURCES_SCHEMA
173
        }
174
      }
175
    },
176
    file_handlers: {
177
      type: 'array',
178
      items: {
179
        type: 'object',
180
        properties: {
181
          icons: RESOURCES_SCHEMA
182
        }
183
      }
184
    }
185
  }
186
};
187
```
188

189
**Validated Properties:**
190
- `icons`: Array of resource objects with required `src` property
191
- `screenshots`: Array of resource objects with required `src` property  
192
- `shortcuts`: Array of objects with optional `icons` property
193
- `file_handlers`: Array of objects with optional `icons` property
194

195
### Resource Dependency Processing
196

197
The transformer automatically converts resource URLs to Parcel dependencies using `addURLDependency` with precise source location tracking.
198

199
```javascript { .api }
200
/**
201
 * Utility function to get JSON source location for error reporting
202
 * @param pointer - JSON pointer from source map
203
 * @param type - Type of location ('key' | 'value')
204
 * @returns Source location object with start/end positions
205
 */
206
function getJSONSourceLocation(
207
  pointer: object,
208
  type: 'key' | 'value'
209
): { start: Position, end: Position };
210

211
/**
212
 * JSON source map parser from @mischnic/json-sourcemap
213
 * @param source - JSON string to parse
214
 * @returns Parsed data with source map pointers
215
 */
216
function parse(source: string): JSONSourceMap;
217
```
218

219
**Processing Behavior:**
220
- Processes `icons` and `screenshots` arrays at the top level
221
- Processes nested `icons` within `shortcuts` and `file_handlers`
222
- Each resource `src` URL is converted to a Parcel dependency
223
- Maintains precise source location tracking for error reporting
224
- Uses JSON pointer paths like `/icons/0/src` for location tracking
225

226
### Internal Processing Functions
227

228
The transformer uses internal helper functions for resource processing:
229

230
```javascript { .api }
231
/**
232
 * Internal function to add resource list dependencies to asset
233
 * @param list - Array of resource objects with src properties
234
 * @param parent - Parent JSON pointer path for location tracking
235
 */
236
function addResourceListToAsset(list: Array<any>, parent: string): void;
237
```
238

239
**Internal Processing Logic:**
240
1. Parse JSON with source mapping using `@mischnic/json-sourcemap`
241
2. Validate against `MANIFEST_SCHEMA` using `validateSchema.diagnostic`
242
3. Process top-level `icons` and `screenshots` arrays
243
4. Process nested `icons` within `shortcuts` and `file_handlers`
244
5. Convert each `src` URL to Parcel dependency with precise location
245
6. Set asset type to 'webmanifest' and update content
246

247
## Types
248

249
```javascript { .api }
250
/**
251
 * Parcel asset interface for transformation
252
 */
253
interface MutableAsset {
254
  /** Get the current code/content of the asset */
255
  getCode(): Promise<string>;
256
  /** Set the code/content of the asset */
257
  setCode(content: string): void;
258
  /** Add a general dependency to the asset */
259
  addDependency(options: DependencyOptions): string;
260
  /** Add a URL dependency to the asset (used for resource references) */
261
  addURLDependency(url: string, options: DependencyOptions): string;
262
  /** The asset's type (initially corresponds to file extension) */
263
  type: string;
264
  /** Absolute file path of the asset */
265
  filePath: string;
266
  /** Optional unique key for the asset */
267
  uniqueKey?: string;
268
  /** Symbol information for the asset */
269
  +symbols: MutableAssetSymbols;
270
}
271

272
/**
273
 * Options for dependency creation
274
 */
275
interface DependencyOptions {
276
  /** Source location for error reporting */
277
  loc?: SourceLocation;
278
  /** Environment conditions for the dependency */
279
  env?: EnvironmentOptions;
280
  /** Whether this is an optional dependency */
281
  isOptional?: boolean;
282
  /** Priority of the dependency */
283
  priority?: 'sync' | 'parallel' | 'lazy';
284
}
285

286
/**
287
 * Source location for error reporting and debugging
288
 */
289
interface SourceLocation {
290
  filePath: string;
291
  start: Position;
292
  end: Position;
293
}
294

295
/**
296
 * Position information for source locations
297
 */
298
interface Position {
299
  line: number;
300
  column: number;
301
}
302

303
/**
304
 * Schema entity for validation rules
305
 */
306
interface SchemaEntity {
307
  type: 'object' | 'array' | 'string' | 'number' | 'boolean';
308
  properties?: { [key: string]: SchemaEntity };
309
  items?: SchemaEntity;
310
  required?: string[];
311
  __validate?: (value: any) => string | undefined;
312
}
313

314
/**
315
 * JSON source map parsing result
316
 */
317
interface JSONSourceMap {
318
  data: any;
319
  pointers: { [jsonPointer: string]: SourceLocation };
320
}
321

322
/**
323
 * Asset symbols interface for mutable assets
324
 */
325
interface MutableAssetSymbols {
326
  ensure(): void;
327
  set(exportSymbol: Symbol, local: Symbol): void;
328
  get(exportSymbol: Symbol): Symbol | null;
329
  hasExportSymbol(exportSymbol: Symbol): boolean;
330
  hasLocalSymbol(local: Symbol): boolean;
331
  exportSymbols(): Iterable<Symbol>;
332
}
333
```
334

335
## Error Handling
336

337
The transformer provides detailed error reporting with source location tracking:
338

339
- **Schema Validation Errors**: Invalid manifest structure with precise location information
340
- **Resource Processing Errors**: Issues with resource URL resolution
341
- **JSON Parsing Errors**: Malformed JSON with source mapping
342

343
Errors are reported through Parcel's diagnostic system with file paths and line/column positions.
344

345
## Integration Notes
346

347
- **Automatic Usage**: No manual registration required - Parcel automatically uses this transformer for `.webmanifest` files
348
- **Asset Pipeline**: Integrates seamlessly with Parcel's asset processing pipeline
349
- **Source Maps**: Maintains source mapping for debugging and error reporting
350
- **Type Safety**: Flow typed for enhanced development experience
351
- **Dependency Tracking**: Automatically tracks icon and screenshot dependencies for proper bundling