@meng-xi/vite-plugin 0.0.7 → 0.0.8

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (17) hide show
  1. package/README-en.md +199 -63
  2. package/README.md +201 -64
  3. package/dist/index.cjs +1 -1
  4. package/dist/index.d.cts +1 -1
  5. package/dist/index.d.mts +1 -1
  6. package/dist/index.d.ts +1 -1
  7. package/dist/index.mjs +1 -1
  8. package/dist/plugins/index.cjs +1 -1
  9. package/dist/plugins/index.d.cts +699 -2
  10. package/dist/plugins/index.d.mts +699 -2
  11. package/dist/plugins/index.d.ts +699 -2
  12. package/dist/plugins/index.mjs +1 -1
  13. package/dist/shared/vite-plugin.CIQOGuWb.cjs +484 -0
  14. package/dist/shared/vite-plugin.N63Ts2dO.mjs +484 -0
  15. package/package.json +1 -1
  16. package/dist/shared/vite-plugin.CIahO6bu.mjs +0 -37
  17. package/dist/shared/vite-plugin.DqgHJjxa.cjs +0 -37
package/README-en.md CHANGED
@@ -15,8 +15,7 @@
15
15
 
16
16
  ## Features
17
17
 
18
- - **Ready to Use** - Provides five practical plugins - buildProgress, copyFile, generateRouter, generateVersion, injectIco - covering build progress display, file copying, router generation, version management, and icon
19
- injection
18
+ - **Ready to Use** - Provides 6 practical plugins covering build progress display, file copying, router generation, version management, icon injection, and global Loading state management
20
19
  - **Plugin Development Framework** - Exports core components like BasePlugin, Logger, Validator for building custom Vite plugins
21
20
  - **Complete Lifecycle** - Supports initialization, config resolution, destroy lifecycle management with automatic hook composition
22
21
  - **Type Safe** - Complete TypeScript type definitions with configuration validators ensuring parameter correctness
@@ -51,7 +50,7 @@ pnpm add @meng-xi/vite-plugin -D
51
50
 
52
51
  ```typescript
53
52
  import { defineConfig } from 'vite'
54
- import { buildProgress, copyFile, generateRouter, generateVersion, injectIco } from '@meng-xi/vite-plugin'
53
+ import { buildProgress, copyFile, generateRouter, generateVersion, injectIco, injectLoading } from '@meng-xi/vite-plugin'
55
54
 
56
55
  export default defineConfig({
57
56
  plugins: [
@@ -79,6 +78,12 @@ export default defineConfig({
79
78
  // Inject website icon
80
79
  injectIco({
81
80
  base: '/assets'
81
+ }),
82
+
83
+ // Inject global Loading
84
+ injectLoading({
85
+ defaultVisible: true,
86
+ autoHideOn: 'DOMContentLoaded'
82
87
  })
83
88
  ]
84
89
  })
@@ -246,19 +251,28 @@ Log output format:
246
251
 
247
252
  ## Built-in Plugins
248
253
 
254
+ | Plugin | Description |
255
+ | --------------- | ----------------------------------------------------------------------------------------- |
256
+ | buildProgress | Real-time build progress bar in terminal, supports bar / spinner / minimal |
257
+ | copyFile | Copy files or directories after build, supports incremental copying |
258
+ | generateRouter | Auto-generate router config from pages.json (uni-app) |
259
+ | generateVersion | Auto-generate version numbers, supports file output and global variable injection |
260
+ | injectIco | Inject website icon links into HTML files |
261
+ | injectLoading | Inject global Loading state management with request interception and white-screen Loading |
262
+
249
263
  ### buildProgress
250
264
 
251
265
  Display real-time build progress bar in terminal during Vite build, supporting three display formats.
252
266
 
253
267
  | Option | Type | Default | Description |
254
268
  | --------------- | ------------------------------------- | ------- | ---------------------------------------------------- |
255
- | width | number | 30 | Progress bar width (characters) |
256
- | format | `'bar'` \| `'spinner'` \| `'minimal'` | 'bar' | Progress bar display format |
257
- | completeChar | string | '█' | Fill character for completed portion |
258
- | incompleteChar | string | '░' | Fill character for incomplete portion |
259
- | clearOnComplete | boolean | true | Whether to clear progress bar on build completion |
260
- | showModuleName | boolean | true | Whether to show the currently processing module name |
261
- | theme | [ProgressTheme](#progresstheme) | - | Custom color theme |
269
+ | width | `number` | `30` | Progress bar width (characters) |
270
+ | format | `'bar'` \| `'spinner'` \| `'minimal'` | `'bar'` | Progress bar display format |
271
+ | completeChar | `string` | `'█'` | Fill character for completed portion |
272
+ | incompleteChar | `string` | `'░'` | Fill character for incomplete portion |
273
+ | clearOnComplete | `boolean` | `true` | Whether to clear progress bar on build completion |
274
+ | showModuleName | `boolean` | `true` | Whether to show the currently processing module name |
275
+ | theme | `ProgressTheme` | - | Custom color theme |
262
276
 
263
277
  **ProgressTheme**
264
278
 
@@ -293,77 +307,199 @@ buildProgress({
293
307
 
294
308
  Copy files or directories to specified locations after Vite build is completed.
295
309
 
296
- | Option | Type | Default | Description |
297
- | ----------- | ------- | ------- | ------------------------------------------ |
298
- | sourceDir | string | - | Source directory path (required) |
299
- | targetDir | string | - | Target directory path (required) |
300
- | overwrite | boolean | true | Whether to overwrite existing files |
301
- | recursive | boolean | true | Whether to recursively copy subdirectories |
302
- | incremental | boolean | true | Whether to enable incremental copying |
310
+ | Option | Type | Default | Description |
311
+ | ----------- | --------- | ------- | ------------------------------------------ |
312
+ | sourceDir | `string` | - | Source directory path (required) |
313
+ | targetDir | `string` | - | Target directory path (required) |
314
+ | overwrite | `boolean` | `true` | Whether to overwrite existing files |
315
+ | recursive | `boolean` | `true` | Whether to recursively copy subdirectories |
316
+ | incremental | `boolean` | `true` | Whether to enable incremental copying |
303
317
 
304
318
  ### generateRouter
305
319
 
306
320
  Automatically generate router configuration files based on uni-app project's `pages.json`.
307
321
 
308
- | Option | Type | Default | Description |
309
- | -------------------- | --------------------------------------------------------- | ---------------------- | ------------------------------------------------ |
310
- | pagesJsonPath | string | 'src/pages.json' | Path to pages.json file |
311
- | outputPath | string | 'src/router.config.ts' | Output file path |
312
- | outputFormat | `'ts'` \| `'js'` | 'ts' | Output file format |
313
- | nameStrategy | `'path'` \| `'camelCase'` \| `'pascalCase'` \| `'custom'` | 'camelCase' | Route name strategy |
314
- | customNameGenerator | `(path: string) => string` | - | Custom route name generator function |
315
- | includeSubPackages | boolean | true | Whether to include sub-package routes |
316
- | watch | boolean | true | Whether to watch changes and auto-regenerate |
317
- | metaMapping | `Record<string, string>` | - | Mapping from page style fields to meta |
318
- | exportTypes | boolean | true | Whether to export type definitions |
319
- | preserveRouteChanges | boolean | true | Whether to preserve user modifications to routes |
322
+ | Option | Type | Default | Description |
323
+ | -------------------- | --------------------------------------------------------- | ------------------------ | ------------------------------------------------ |
324
+ | pagesJsonPath | `string` | `'src/pages.json'` | Path to pages.json file |
325
+ | outputPath | `string` | `'src/router.config.ts'` | Output file path |
326
+ | outputFormat | `'ts'` \| `'js'` | `'ts'` | Output file format |
327
+ | nameStrategy | `'path'` \| `'camelCase'` \| `'pascalCase'` \| `'custom'` | `'camelCase'` | Route name strategy |
328
+ | customNameGenerator | `(path: string) => string` | - | Custom route name generator function |
329
+ | includeSubPackages | `boolean` | `true` | Whether to include sub-package routes |
330
+ | watch | `boolean` | `true` | Whether to watch changes and auto-regenerate |
331
+ | metaMapping | `Record<string, string>` | - | Mapping from page style fields to meta |
332
+ | exportTypes | `boolean` | `true` | Whether to export type definitions |
333
+ | preserveRouteChanges | `boolean` | `true` | Whether to preserve user modifications to routes |
320
334
 
321
335
  ### generateVersion
322
336
 
323
337
  Automatically generate version numbers during the Vite build process.
324
338
 
325
- | Option | Type | Default | Description |
326
- | ------------ | --------------------------------------------------------------------------------- | ----------------- | ------------------------------ |
327
- | format | `'timestamp'` \| `'date'` \| `'datetime'` \| `'semver'` \| `'hash'` \| `'custom'` | 'timestamp' | Version format |
328
- | customFormat | string | - | Custom format template |
329
- | semverBase | string | '1.0.0' | Semantic version base |
330
- | outputType | `'file'` \| `'define'` \| `'both'` | 'file' | Output type |
331
- | outputFile | string | 'version.json' | Output file path |
332
- | defineName | string | '**APP_VERSION**' | Global variable name to inject |
333
- | hashLength | number | 8 | Hash length (1-32) |
334
- | prefix | string | - | Version number prefix |
335
- | suffix | string | - | Version number suffix |
336
- | extra | `Record<string, unknown>` | - | Extra info (JSON file only) |
339
+ | Option | Type | Default | Description |
340
+ | ------------ | --------------------------------------------------------------------------------- | ------------------- | ------------------------------ |
341
+ | format | `'timestamp'` \| `'date'` \| `'datetime'` \| `'semver'` \| `'hash'` \| `'custom'` | `'timestamp'` | Version format |
342
+ | customFormat | `string` | - | Custom format template |
343
+ | semverBase | `string` | `'1.0.0'` | Semantic version base |
344
+ | outputType | `'file'` \| `'define'` \| `'both'` | `'file'` | Output type |
345
+ | outputFile | `string` | `'version.json'` | Output file path |
346
+ | defineName | `string` | `'__APP_VERSION__'` | Global variable name to inject |
347
+ | hashLength | `number` | `8` | Hash length (1-32) |
348
+ | prefix | `string` | - | Version number prefix |
349
+ | suffix | `string` | - | Version number suffix |
350
+ | extra | `Record<string, unknown>` | - | Extra info (JSON file only) |
337
351
 
338
352
  ### injectIco
339
353
 
340
354
  Inject website icon links into the head of HTML files during the Vite build process.
341
355
 
342
- | Option | Type | Default | Description |
343
- | ----------- | ------ | ------- | ------------------------------- |
344
- | base | string | '/' | Base path for icon files |
345
- | url | string | - | Complete URL for the icon |
346
- | link | string | - | Custom complete link tag HTML |
347
- | icons | Icon[] | - | Custom icon array |
348
- | copyOptions | object | - | Icon file copying configuration |
356
+ | Option | Type | Default | Description |
357
+ | ----------- | -------- | ------- | ------------------------------- |
358
+ | base | `string` | `'/'` | Base path for icon files |
359
+ | url | `string` | - | Complete URL for the icon |
360
+ | link | `string` | - | Custom complete link tag HTML |
361
+ | icons | `Icon[]` | - | Custom icon array |
362
+ | copyOptions | `object` | - | Icon file copying configuration |
349
363
 
350
364
  `Icon` interface definition:
351
365
 
352
- | Property | Type | Required | Description |
353
- | -------- | ------ | -------- | ------------------ |
354
- | rel | string | Yes | Icon relation type |
355
- | href | string | Yes | Icon URL |
356
- | sizes | string | No | Icon sizes |
357
- | type | string | No | Icon MIME type |
366
+ | Property | Type | Required | Description |
367
+ | -------- | -------- | -------- | ------------------ |
368
+ | rel | `string` | Yes | Icon relation type |
369
+ | href | `string` | Yes | Icon URL |
370
+ | sizes | `string` | No | Icon sizes |
371
+ | type | `string` | No | Icon MIME type |
358
372
 
359
373
  `copyOptions` interface definition:
360
374
 
361
- | Property | Type | Required | Default | Description |
362
- | --------- | ------- | -------- | ------- | --------------------------- |
363
- | sourceDir | string | Yes | - | Icon source directory |
364
- | targetDir | string | Yes | - | Icon target directory |
365
- | overwrite | boolean | No | true | Whether to overwrite files |
366
- | recursive | boolean | No | true | Whether to copy recursively |
375
+ | Property | Type | Required | Default | Description |
376
+ | --------- | --------- | -------- | ------- | --------------------------- |
377
+ | sourceDir | `string` | Yes | - | Icon source directory |
378
+ | targetDir | `string` | Yes | - | Icon target directory |
379
+ | overwrite | `boolean` | No | `true` | Whether to overwrite files |
380
+ | recursive | `boolean` | No | `true` | Whether to copy recursively |
381
+
382
+ ### injectLoading
383
+
384
+ Inject global Loading state management with XHR/Fetch request interception, white-screen Loading, custom styles, and lifecycle callbacks.
385
+
386
+ | Option | Type | Default | Description |
387
+ | -------------- | ----------------------------------------------- | ----------------------- | ------------------------------------------------------- |
388
+ | position | `'center'` \| `'top'` \| `'bottom'` | `'center'` | Loading display position |
389
+ | defaultText | `string` | `'Loading...'` | Default display text |
390
+ | spinnerType | `'spinner'` \| `'dots'` \| `'pulse'` \| `'bar'` | `'spinner'` | Spinner icon type |
391
+ | style | `LoadingStyle` | - | Custom style configuration |
392
+ | transition | `TransitionConfig` | `{ enabled: true }` | Transition animation configuration |
393
+ | minDisplayTime | `MinDisplayTime` | `{ enabled: true }` | Minimum display time configuration |
394
+ | delayShow | `DelayShow` | `{ enabled: true }` | Delayed show configuration |
395
+ | debounceHide | `DebounceHide` | `{ enabled: false }` | Debounced hide configuration |
396
+ | autoBind | `'fetch'` \| `'xhr'` \| `'all'` \| `'none'` | `'none'` | Auto-bind request interception mode |
397
+ | requestFilter | `RequestFilter` | - | Request filter configuration |
398
+ | globalName | `string` | `'__LOADING_MANAGER__'` | Global variable name injected into browser |
399
+ | customTemplate | `string` | - | Custom HTML template (must include `data-loading-text`) |
400
+ | defaultVisible | `boolean` | `false` | Whether initially visible (white-screen Loading) |
401
+ | autoHideOn | `'DOMContentLoaded'` \| `'load'` \| `'manual'` | `'DOMContentLoaded'` | Auto-hide timing (requires `defaultVisible: true`) |
402
+ | callbacks | `LoadingCallbacks` | - | Lifecycle callbacks |
403
+
404
+ **LoadingStyle**
405
+
406
+ | Property | Type | Default | Description |
407
+ | ------------------ | --------- | ------------------------- | ------------------------------- |
408
+ | overlayColor | `string` | `'rgba(255,255,255,0.7)'` | Overlay background color |
409
+ | spinnerColor | `string` | `'#4361ee'` | Spinner color |
410
+ | spinnerSize | `string` | `'40px'` | Spinner size |
411
+ | textColor | `string` | `'#333'` | Text color |
412
+ | textSize | `string` | `'14px'` | Text size |
413
+ | customClass | `string` | - | Custom CSS class name |
414
+ | customStyle | `string` | - | Custom inline style string |
415
+ | zIndex | `number` | `9999` | z-index value |
416
+ | pointerEvents | `boolean` | `false` | Whether to allow click-through |
417
+ | backdropBlur | `boolean` | `false` | Whether to enable backdrop blur |
418
+ | backdropBlurAmount | `number` | `4` | Backdrop blur amount (px) |
419
+
420
+ **TransitionConfig**
421
+
422
+ | Property | Type | Default | Description |
423
+ | -------- | --------- | ------------ | ---------------------------- |
424
+ | enabled | `boolean` | `true` | Whether to enable transition |
425
+ | duration | `number` | `200` | Transition duration (ms) |
426
+ | easing | `string` | `'ease-out'` | Easing function |
427
+
428
+ **MinDisplayTime**
429
+
430
+ | Property | Type | Default | Description |
431
+ | -------- | --------- | ------- | ------------------------- |
432
+ | enabled | `boolean` | `true` | Whether to enable |
433
+ | duration | `number` | `300` | Minimum display time (ms) |
434
+
435
+ **DelayShow**
436
+
437
+ | Property | Type | Default | Description |
438
+ | -------- | --------- | ------- | ------------------------------------------------------------------------------ |
439
+ | enabled | `boolean` | `true` | Whether to enable |
440
+ | duration | `number` | `200` | Delay duration (ms); if request completes within this time, Loading won't show |
441
+
442
+ **DebounceHide**
443
+
444
+ | Property | Type | Default | Description |
445
+ | -------- | --------- | ------- | ----------------------- |
446
+ | enabled | `boolean` | `false` | Whether to enable |
447
+ | duration | `number` | `100` | Debounce wait time (ms) |
448
+
449
+ **RequestFilter**
450
+
451
+ | Property | Type | Description |
452
+ | ------------------ | ---------- | --------------------------------------------------------------------- |
453
+ | excludeUrls | `RegExp[]` | Array of URL regex patterns to exclude |
454
+ | includeUrls | `RegExp[]` | Array of URL regex patterns to include (higher priority than exclude) |
455
+ | excludeMethods | `string[]` | Array of HTTP methods to exclude |
456
+ | excludeUrlPrefixes | `string[]` | Array of URL prefixes to exclude (prefix matching, more efficient) |
457
+
458
+ **LoadingCallbacks**
459
+
460
+ Callbacks are provided as **function body strings** (injected into browser at build time, function references cannot be passed).
461
+
462
+ | Property | Type | Description |
463
+ | ------------ | -------- | ----------------------------------------------- |
464
+ | onBeforeShow | `string` | Before show callback, `return false` to prevent |
465
+ | onShow | `string` | After show callback |
466
+ | onBeforeHide | `string` | Before hide callback, `return false` to prevent |
467
+ | onHide | `string` | After hide callback |
468
+ | onDestroy | `string` | On destroy callback |
469
+
470
+ **LoadingManager API**
471
+
472
+ Access via `window.__LOADING_MANAGER__`:
473
+
474
+ | Method | Description |
475
+ | ------------------- | ------------------------------------------------------------------- |
476
+ | `show(text?)` | Show Loading, optionally pass text |
477
+ | `hide()` | Hide Loading (subject to min display time and debounce constraints) |
478
+ | `forceHide()` | Force hide, ignoring min display time and debounce |
479
+ | `destroy()` | Destroy instance and restore original interceptors |
480
+ | `updateText(t)` | Update text content |
481
+ | `isVisible()` | Get whether Loading is currently visible |
482
+ | `getPendingCount()` | Get the number of pending requests |
483
+
484
+ ```typescript
485
+ // White-screen Loading: visible on page load, auto-hide on DOMContentLoaded
486
+ injectLoading({ defaultVisible: true, autoHideOn: 'DOMContentLoaded' })
487
+
488
+ // Auto-intercept all requests
489
+ injectLoading({ autoBind: 'all' })
490
+
491
+ // Custom styles + request filtering
492
+ injectLoading({
493
+ style: { overlayColor: 'rgba(0,0,0,0.5)', spinnerColor: '#fff' },
494
+ autoBind: 'fetch',
495
+ requestFilter: { excludeUrls: [/\/api\/health/] }
496
+ })
497
+
498
+ // Manual control
499
+ injectLoading()
500
+ window.__LOADING_MANAGER__.show('Saving...')
501
+ window.__LOADING_MANAGER__.hide()
502
+ ```
367
503
 
368
504
  ## Sub-path Exports
369
505
 
@@ -371,17 +507,17 @@ Support importing modules on demand to reduce bundle size:
371
507
 
372
508
  ```typescript
373
509
  // Full import
374
- import { buildProgress, copyFile, BasePlugin, Logger } from '@meng-xi/vite-plugin'
510
+ import { buildProgress, copyFile, injectLoading, BasePlugin, Logger } from '@meng-xi/vite-plugin'
375
511
 
376
512
  // Module-level import
377
513
  import { BasePlugin, createPluginFactory } from '@meng-xi/vite-plugin/factory'
378
514
  import { Logger } from '@meng-xi/vite-plugin/logger'
379
- import { buildProgress, copyFile, generateRouter } from '@meng-xi/vite-plugin/plugins'
515
+ import { buildProgress, copyFile, generateRouter, injectLoading } from '@meng-xi/vite-plugin/plugins'
380
516
  import { Validator, readFileContent, writeFileContent } from '@meng-xi/vite-plugin/common'
381
517
 
382
518
  // Type imports (on-demand type definitions from sub-paths)
383
519
  import type { PluginWithInstance, PluginFactory, BasePluginOptions } from '@meng-xi/vite-plugin/factory'
384
- import type { BuildProgressOptions, GenerateVersionOptions, InjectIcoOptions, Icon } from '@meng-xi/vite-plugin/plugins'
520
+ import type { BuildProgressOptions, GenerateVersionOptions, InjectIcoOptions, InjectLoadingOptions, Icon } from '@meng-xi/vite-plugin/plugins'
385
521
  import type { DateFormatOptions } from '@meng-xi/vite-plugin/common'
386
522
  ```
387
523