index.d.ts 12 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401
  1. import { ResolvedConfig, Plugin } from 'vite';
  2. import { InjectManifestOptions, GenerateSWOptions, ManifestEntry, RuntimeCaching } from 'workbox-build';
  3. import { OutputBundle } from 'rollup';
  4. type InjectManifestVitePlugins = string[] | ((vitePluginIds: string[]) => string[]);
  5. type CustomInjectManifestOptions = InjectManifestOptions & {
  6. /**
  7. * Configure the format to use in the Rollup build.
  8. *
  9. * @default 'es'
  10. */
  11. rollupFormat?: 'es' | 'iife';
  12. /**
  13. * `Vite` plugin ids to use on `Rollup` build.
  14. *
  15. * **WARN**: this option is for advanced usage, beware, you can break the service worker build.
  16. */
  17. vitePlugins?: InjectManifestVitePlugins;
  18. };
  19. interface PWAIntegration {
  20. closeBundleOrder?: 'pre' | 'post' | null;
  21. configureOptions?: (viteOptions: ResolvedConfig, options: Partial<VitePWAOptions>) => void | Promise<void>;
  22. }
  23. /**
  24. * Plugin options.
  25. */
  26. interface VitePWAOptions {
  27. /**
  28. * Build mode
  29. *
  30. * @default process.env.NODE_ENV or "production"
  31. */
  32. mode?: 'development' | 'production';
  33. /**
  34. * @default 'public'
  35. */
  36. srcDir?: string;
  37. /**
  38. * @default 'dist'
  39. */
  40. outDir?: string;
  41. /**
  42. * @default 'sw.js'
  43. */
  44. filename?: string;
  45. /**
  46. * @default 'manifest.webmanifest'
  47. */
  48. manifestFilename?: string;
  49. /**
  50. * @default 'generateSW'
  51. */
  52. strategies?: 'generateSW' | 'injectManifest';
  53. /**
  54. * The scope to register the Service Worker
  55. *
  56. * @default same as `base` of Vite's config
  57. */
  58. scope?: string;
  59. /**
  60. * Inject the service worker register inlined in the index.html
  61. *
  62. * With `auto` set, depends on whether you used the `import { registerSW } from 'virtual:pwa-register'`
  63. * it will do nothing or use the `script` mode
  64. *
  65. * `inline` - inject a simple register, inlined with the generated html
  66. *
  67. * `script` - inject <script/> in <head>, with the `sr` to a generated simple register
  68. *
  69. * `null` - do nothing, you will need to register the sw you self, or imports from `virtual:pwa-register`
  70. *
  71. * @default 'auto'
  72. */
  73. injectRegister: 'inline' | 'script' | 'auto' | null | false;
  74. /**
  75. * Mode for the virtual register.
  76. * Does NOT available for `injectRegister` set to `inline` or `script`
  77. *
  78. * `prompt` - you will need to show a popup/dialog to the user to confirm the reload.
  79. *
  80. * `autoUpdate` - when new content is available, the new service worker will update caches and reload all browser
  81. * windows/tabs with the application open automatically, it must take the control for the application to work
  82. * properly.
  83. *
  84. * @default 'prompt'
  85. */
  86. registerType?: 'prompt' | 'autoUpdate';
  87. /**
  88. * Minify the generated manifest
  89. *
  90. * @default true
  91. */
  92. minify: boolean;
  93. /**
  94. * The manifest object
  95. */
  96. manifest: Partial<ManifestOptions> | false;
  97. /**
  98. * Whether to add the `crossorigin="use-credentials"` attribute to `<link rel="manifest">`
  99. * @default false
  100. */
  101. useCredentials?: boolean;
  102. /**
  103. * The workbox object for `generateSW`
  104. */
  105. workbox: Partial<GenerateSWOptions>;
  106. /**
  107. * The workbox object for `injectManifest`
  108. */
  109. injectManifest: Partial<CustomInjectManifestOptions>;
  110. /**
  111. * Override Vite's base options only for PWA
  112. *
  113. * @default "base" options from Vite
  114. */
  115. base?: string;
  116. /**
  117. * `public` resources to be added to the PWA manifest.
  118. *
  119. * You don't need to add `manifest` icons here, it will be auto included.
  120. *
  121. * The `public` directory will be resolved from Vite's `publicDir` option directory.
  122. */
  123. includeAssets: string | string[] | undefined;
  124. /**
  125. * By default, the icons listed on `manifest` option will be included
  126. * on the service worker *precache* if present under Vite's `publicDir`
  127. * option directory.
  128. *
  129. * @default true
  130. */
  131. includeManifestIcons: boolean;
  132. /**
  133. * Disable service worker registration and generation on `build`?
  134. *
  135. * @default false
  136. */
  137. disable: boolean;
  138. /**
  139. * Vite PWA Integration.
  140. */
  141. integration?: PWAIntegration;
  142. /**
  143. * Development options.
  144. */
  145. devOptions?: DevOptions;
  146. /**
  147. * Unregister the service worker?
  148. *
  149. * @default false
  150. */
  151. selfDestroying?: boolean;
  152. }
  153. interface ResolvedVitePWAOptions extends Required<VitePWAOptions> {
  154. swSrc: string;
  155. swDest: string;
  156. workbox: GenerateSWOptions;
  157. injectManifest: InjectManifestOptions;
  158. rollupFormat: 'es' | 'iife';
  159. vitePlugins: InjectManifestVitePlugins;
  160. }
  161. interface ManifestOptions {
  162. /**
  163. * @default _npm_package_name_
  164. */
  165. name: string;
  166. /**
  167. * @default _npm_package_name_
  168. */
  169. short_name: string;
  170. /**
  171. * @default _npm_package_description_
  172. */
  173. description: string;
  174. /**
  175. *
  176. */
  177. icons: Record<string, any>[];
  178. /**
  179. *
  180. */
  181. file_handlers: Record<string, any>[];
  182. /**
  183. * @default `routerBase + '?standalone=true'`
  184. */
  185. start_url: string;
  186. /**
  187. * Restricts what web pages can be viewed while the manifest is applied
  188. */
  189. scope: string;
  190. /**
  191. * A string that represents the identity for the application
  192. */
  193. id: string;
  194. /**
  195. * Defines the default orientation for all the website's top-level
  196. */
  197. orientation: 'any' | 'natural' | 'landscape' | 'landscape-primary' | 'landscape-secondary' | 'portrait' | 'portrait-primary' | 'portrait-secondary';
  198. /**
  199. * @default `standalone`
  200. */
  201. display: string;
  202. /**
  203. * @default []
  204. */
  205. display_override: string[];
  206. /**
  207. * @default `#ffffff`
  208. */
  209. background_color: string;
  210. /**
  211. * @default '#42b883
  212. */
  213. theme_color: string;
  214. /**
  215. * @default `ltr`
  216. */
  217. dir: 'ltr' | 'rtl';
  218. /**
  219. * @default `en`
  220. */
  221. lang: string;
  222. /**
  223. * @default A combination of `routerBase` and `options.build.publicPath`
  224. */
  225. publicPath: string;
  226. /**
  227. * @default []
  228. */
  229. related_applications: {
  230. platform: string;
  231. url: string;
  232. id?: string;
  233. }[];
  234. /**
  235. * @default false
  236. */
  237. prefer_related_applications: boolean;
  238. /**
  239. * @default []
  240. */
  241. protocol_handlers: {
  242. protocol: string;
  243. url: string;
  244. }[];
  245. /**
  246. * @default []
  247. */
  248. shortcuts: {
  249. name: string;
  250. short_name?: string;
  251. url: string;
  252. description?: string;
  253. icons: Record<string, any>[];
  254. }[];
  255. /**
  256. * @default []
  257. */
  258. screenshots: {
  259. src: string;
  260. sizes: string;
  261. label?: string;
  262. platform?: 'narrow' | 'wide' | 'android' | 'ios' | 'kaios' | 'macos' | 'windows' | 'windows10x' | 'chrome_web_store' | 'play' | 'itunes' | 'microsoft-inbox' | 'microsoft-store' | string;
  263. type?: string;
  264. }[];
  265. /**
  266. * @default []
  267. */
  268. categories: string[];
  269. /**
  270. * @default ''
  271. */
  272. iarc_rating_id: string;
  273. }
  274. interface WebManifestData {
  275. href: string;
  276. useCredentials: boolean;
  277. /**
  278. * Returns the corresponding link tag: `<link rel="manifest" href="<webManifestUrl>" />`.
  279. */
  280. toLinkTag: () => string;
  281. }
  282. interface RegisterSWData {
  283. shouldRegisterSW: boolean;
  284. /**
  285. * When this flag is `true` the service worker must be registered via inline script otherwise registered via script with src attribute `registerSW.js` .
  286. */
  287. inline: boolean;
  288. /**
  289. * The path for the inline script: will contain the service worker url.
  290. */
  291. inlinePath: string;
  292. /**
  293. * The path for the src script for `registerSW.js`.
  294. */
  295. registerPath: string;
  296. /**
  297. * The scope for the service worker: only required for `inline: true`.
  298. */
  299. scope: string;
  300. /**
  301. * The type for the service worker: only required for `inline: true`.
  302. */
  303. type: WorkerType;
  304. /**
  305. * Returns the corresponding script tag if `shouldRegisterSW` returns `true`.
  306. */
  307. toScriptTag: () => string | undefined;
  308. }
  309. interface VitePluginPWAAPI {
  310. /**
  311. * Is the plugin disabled?
  312. */
  313. disabled: boolean;
  314. /**
  315. * Running on dev server?
  316. */
  317. pwaInDevEnvironment: boolean;
  318. /**
  319. * Returns the PWA webmanifest url for the manifest link:
  320. * <link rel="manifest" href="<webManifestUrl>" />
  321. *
  322. * Will also return if the manifest will require credentials:
  323. * <link rel="manifest" href="<webManifestUrl>" crossorigin="use-credentials" />
  324. */
  325. webManifestData(): WebManifestData | undefined;
  326. /**
  327. * How the service worker is being registered in the application.
  328. *
  329. * This option will help some integrations to inject the corresponding script in the head.
  330. */
  331. registerSWData(): RegisterSWData | undefined;
  332. extendManifestEntries(fn: ExtendManifestEntriesHook): void;
  333. generateBundle(bundle?: OutputBundle): OutputBundle | undefined;
  334. generateSW(): Promise<void>;
  335. }
  336. type ExtendManifestEntriesHook = (manifestEntries: (string | ManifestEntry)[]) => (string | ManifestEntry)[] | undefined;
  337. /**
  338. * Development options.
  339. */
  340. interface DevOptions {
  341. /**
  342. * Should the service worker be available on development?.
  343. *
  344. * @default false
  345. */
  346. enabled?: boolean;
  347. /**
  348. * The service worker type.
  349. *
  350. * @default 'classic'
  351. */
  352. type?: WorkerType;
  353. /**
  354. * This option will enable you to not use the `runtimeConfig` configured on `workbox.runtimeConfig` plugin option.
  355. *
  356. * **WARNING**: this option will only be used when using `generateSW` strategy.
  357. *
  358. * @default false
  359. */
  360. disableRuntimeConfig?: boolean;
  361. /**
  362. * This option will allow you to configure the `navigateFallback` when using `registerRoute` for `offline` support:
  363. * configure here the corresponding `url`, for example `navigateFallback: 'index.html'`.
  364. *
  365. * **WARNING**: this option will only be used when using `injectManifest` strategy.
  366. */
  367. navigateFallback?: string;
  368. /**
  369. * This option will allow you to configure the `navigateFallbackAllowlist`: new option from version `v0.12.4`.
  370. *
  371. * Since we need at least the entry point in the service worker's precache manifest, we don't want the rest of the assets to be intercepted by the service worker.
  372. *
  373. * If you configure this option, the plugin will use it instead the default.
  374. *
  375. * **WARNING**: this option will only be used when using `generateSW` strategy.
  376. *
  377. * @default [/^\/$/]
  378. */
  379. navigateFallbackAllowlist?: RegExp[];
  380. /**
  381. * On dev mode the `manifest.webmanifest` file can be on other path.
  382. *
  383. * For example, **SvelteKit** will request `/_app/manifest.webmanifest`, when `webmanifest` added to the output bundle, **SvelteKit** will copy it to the `/_app/` folder.
  384. *
  385. * **WARNING**: this option will only be used when using `generateSW` strategy.
  386. *
  387. * @default `${vite.base}${pwaOptions.manifestFilename}`
  388. * @deprecated This option has been deprecated from version `v0.12.4`, the plugin will use navigateFallbackAllowlist instead.
  389. * @see navigateFallbackAllowlist
  390. */
  391. webManifestUrl?: string;
  392. }
  393. declare const cachePreset: RuntimeCaching[];
  394. declare const defaultInjectManifestVitePlugins: string[];
  395. declare function VitePWA(userOptions?: Partial<VitePWAOptions>): Plugin[];
  396. export { CustomInjectManifestOptions, DevOptions, ExtendManifestEntriesHook, InjectManifestVitePlugins, ManifestOptions, VitePWAOptions as Options, PWAIntegration, RegisterSWData, ResolvedVitePWAOptions, VitePWA, VitePWAOptions, VitePluginPWAAPI, WebManifestData, cachePreset, defaultInjectManifestVitePlugins };