SvelteKit

信息

提示

From version ^0.1.0, SvelteKitPWA has SvelteKit ^1.0.0 as peer dependency.

INFO

For 类型声明, Prompt for update and Periodic SW Updates go to Svelte entry.

提示

If you're using 0.1.* version of SvelteKitPWA, you should remove all references to SvelteKit service worker module to disable it on your application.

安装 @vite-pwa/sveltekit

To install the @vite-pwa/sveltekit plugin, just add it to your project as a dev dependency:

pnpmyarnnpm

bash

pnpm add -D @vite-pwa/sveltekit

bash

yarn add -D @vite-pwa/sveltekit

bash

npm install -D @vite-pwa/sveltekit

Workbox 配置

globPatterns

@vite-pwa/sveltekit configures the following globPatterns for you (workbox or injectManifest option depending on the strategy configured):

workbox: { globPatterns: ['client/**/*.{js,css,ico,png,svg,webp,webmanifest}', 'prerendered/**/*.html'] } or
injectManifest: { globPatterns: ['client/**/*.{js,css,ico,png,svg,webp,webmanifest}', 'prerendered/**/*.html'] }

@vite-pwa/sveltekit configures the .svelte-kit/output directory as the globDirectory for the workbox-build process (workbox or injectManifest option depending on the strategy configured). This directory will contain all the files generated by SvelteKit when building your application as an intermediate step before the final adapter build. This directory will have the following structure:

client directory: will contain all the client side files generated by SvelteKit (.js, .css) and all assets files in the static directory (.ico, .png, .svg, .webp).
prerendered directory: will contain all the prerendered pages (.html).
server directory: will contain all the server side files generated by SvelteKit (.js, .css).

If you want to add some extra files to the globPatterns configuration, remember to include the glob adding the client/ prefix, or you will end up including server assets in the service worker precache manifest and your application will fail when registering the service worker.

If you want to add the SvelteKit _app/version.json file to your service worker precache manifest, enable the kit.includeVersionFile option in your PWA configuration.

Generate Custom Service Worker

From version 0.2.0, SvelteKitPWA plugin will delegate your custom service worker build to SvelteKit, and so by default you will be expected to put your service worker in src/service-worker.js. If you would like, you can use a custom file location by changing the corresponding SvelteKit option:

// svelte.config.js
/** @type {import('@sveltejs/kit').Config} */
const config = {
  kit: {
    files: {
      serviceWorker: 'src/my-sw.js', // or `src/my-sw.ts`
    }
  }
};

export default config;

Then in your Vite config file:

// vite.config.js or vite.config.ts
/** @type {import('vite').UserConfig} */
const config = {
  plugins: [
    sveltekit(),
    SvelteKitPWA({
      strategies: 'injectManifest',
      srcDir: 'src',
      filename: 'my-sw.js', // or `my-sw.ts`
      /* other pwa options */  
    })
  ],
};

export default config;

You can check SvelteKit docs for more information about service workers.

You will need to exclude the service worker registration from the SvelteKit configuration if you're using any pwa virtual module (virtual:pwa-register or virtual:pwa-register/svelte):

// svelte.config.js
/** @type {import('@sveltejs/kit').Config} */
const config = {
  kit: {
    serviceWorker: {
      register: false
    }
  }
};

export default config;

警告

If your custom service working is importing any workbox-* module (workbox-routing, workbox-strategies, etc), you will need to hack Vite build process in order to remove non ESM special replacements from the build process (if you don't include process.env.NODE_ENV, the service worker will not be registered). You only need to add this entry in your Vite config file:

// vite.config.js or vite.config.ts
/** @type {import('vite').UserConfig} */
const config = {
  define: {
    'process.env.NODE_ENV': process.env.NODE_ENV === 'production' 
      ? '"production"'
      : '"development"'
  }
};

export default config;

SvelteKit PWA Plugin

vite-plugin-pwa provides the new SvelteKitPWA plugin that will allow you to use vite-plugin-pwa in your SvelteKit applications.

To update your project to use the new vite-plugin-pwa for SvelteKit, you only need to change the Vite config file (you don't need oldest pwa and pwa-configuration modules):

// vite.config.js / vite.config.ts
import { SvelteKitPWA } from '@vite-pwa/sveltekit'

/** @type {import('vite').UserConfig} */
const config = {
  plugins: [
    sveltekit(),
    SvelteKitPWA({/* pwa options */})
  ],
}

export default config

In addition to the configuration above, it's necessary to add the PWA web manifest, currently the easiest way to do this, is to add it to any layout to your kit project:

svelte

<!-- src/routes/+layout.svelte -->
<script>
  import { pwaInfo } from 'virtual:pwa-info'; 

  $: webManifestLink = pwaInfo ? pwaInfo.webManifest.linkTag : '' 
</script> 
  
<svelte:head> 
 	{@html webManifestLink} 
</svelte:head>

Check out the virtual:pwa-info documentation to learn more about the virtually exposed module pwa-info.

SvelteKit PWA Plugin Options

SvelteKit PWA Plugin options

import type { VitePWAOptions } from 'vite-plugin-pwa'

export interface KitOptions {
  /**
   * The base path for your application: by default will use the Vite base.
   *
   * @deprecated since ^0.1.0 version, the plugin has SvelteKit ^1.0.0 as peer dependency, Vite's base is now properly configured.
   * @default '/'
   * @see https://kit.svelte.dev/docs/configuration#paths
   */
  base?: string

  /**
   * @default '.svelte-kit'
   * @see https://kit.svelte.dev/docs/configuration#outdir
   */
  outDir?: string

  /**
   * @see https://github.com/sveltejs/kit/tree/master/packages/adapter-static#fallback
   */
  adapterFallback?: string

  /**
   * @default 'never'
   * @see https://kit.svelte.dev/docs/configuration#trailingslash
   */
  trailingSlash?: 'never' | 'always' | 'ignore'
}

export interface SvelteKitPWAOptions extends Partial<VitePWAOptions> {
  kit?: KitOptions
}

SvelteKit Pages

If you want your application to work offline, you should ensure you have not set csr: false on any of your pages since it will prevent injecting JavaScript into the layout for offline support.

自动更新

Since SvelteKit uses SSR/SSG, we need to call the vite-plugin-pwa virtual module using a dynamic import.

The best place to include the virtual call will be in main layout of the application (you should register it in any layout):

src/routes/+layout.svelte

html

<script>
  import { onMount } from 'svelte'
  import { pwaInfo } from 'virtual:pwa-info'
  
  onMount(async () => {
    if (pwaInfo) {
      const { registerSW } = await import('virtual:pwa-register')
      registerSW({
        immediate: true,
        onRegistered(r) {
          // uncomment following code if you want check for updates
          // r && setInterval(() => {
          //    console.log('Checking for sw update')
          //    r.update()
          // }, 20000 /* 20s for testing purposes */)
          console.log(`SW Registered: ${r}`)
        },
        onRegisterError(error) {
          console.log('SW registration error', error)
        }
      })
    }
  })
  
  $: webManifest = pwaInfo ? pwaInfo.webManifest.linkTag : ''
</script>

<svelte:head>
    {@html webManifest}
</svelte:head>

<main>
  <slot />
</main>

Prompt for update

Since SvelteKit uses SSR/SSG, we need to add the ReloadPrompt component using a dynamic import.

The best place to include the ReloadPrompt component will be in main layout of the application (you should register it in any layout):

src/routes/+layout.svelte

html

<script>
  import { pwaInfo } from 'virtual:pwa-info'

  $: webManifest = pwaInfo ? pwaInfo.webManifest.linkTag : ''  
</script>

<svelte:head>
    {@html webManifest}
</svelte:head>

<main>
  <slot />
</main>

{#await import('$lib/ReloadPrompt.svelte') then { default: ReloadPrompt}}
  <ReloadPrompt />
{/await}

$lib/ReloadPrompt.svelte

html

<script lang="ts">
	import { useRegisterSW } from 'virtual:pwa-register/svelte'
	const {
		needRefresh,
		updateServiceWorker,
		offlineReady
	} = useRegisterSW({
		onRegistered(r) {
		// uncomment following code if you want check for updates
		// r && setInterval(() => {
		//    console.log('Checking for sw update')
		//    r.update()
		// }, 20000 /* 20s for testing purposes */)
			console.log(`SW Registered: ${r}`)
		},
		onRegisterError(error) {
			console.log('SW registration error', error)
		},
	})
	const close = () => {
		offlineReady.set(false)
		needRefresh.set(false)
	}
	$: toast = $offlineReady || $needRefresh
</script>

{#if toast}
	<div class="pwa-toast" role="alert">
		<div class="message">
			{#if $offlineReady}
				<span>
					App ready to work offline
				</span>
			{:else}
				<span>
					New content available, click on reload button to update.
				</span>
			{/if}
		</div>
		{#if $needRefresh}
			<button on:click={() => updateServiceWorker(true)}>
				Reload
			</button>
		{/if}
		<button on:click={close}>
			Close
		</button>
	</div>
{/if}

<style>
	.pwa-toast {
		position: fixed;
		right: 0;
		bottom: 0;
		margin: 16px;
		padding: 12px;
		border: 1px solid #8885;
		border-radius: 4px;
		z-index: 2;
		text-align: left;
		box-shadow: 3px 4px 5px 0 #8885;
		background-color: white;
	}
	.pwa-toast .message {
		margin-bottom: 8px;
	}
	.pwa-toast button {
		border: 1px solid #8885;
		outline: none;
		margin-right: 5px;
		border-radius: 2px;
		padding: 3px 10px;
	}
</style>

SvelteKit and Adapters

If you set certain SvelteKit options, you should also configure the PWA plugin properly using the kit option:

警告

Some kit options may have been moved/deprecated, review the SvelteKit documentation site:

trailingSlash: now it should be configured in the page options, and so, we cannot control it in the plugin.

PWA Assets 实验性 from v0.4.0

We suggest you using external configuration file, @vite-pwa/sveltekit plugin will watch it for changes, avoiding dev server restarts. If you use inlined configuration, Vite will restart the dev server when changing any option.

To inject the PWA icons links and the theme-color, you can use the virtual:pwa-assets/head virtual module in your +layout.svelte component:

add import 'vite-plugin-pwa/pwa-assets'; to your src/app.d.ts file
remove all links with rel icon, apple-touch-icon and apple-touch-startup-image from <svelte:head> or from your app.html file
remove the theme-color meta tag from <svelte:head> or from your app.html file
add the virtual import
include theme color and icons links using code-snippet shown below

svelte

<script>
import { pwaAssetsHead } from 'virtual:pwa-assets/head';
</script>

<svelte:head>
	{#if pwaAssetsHead.themeColor}
	<meta name="theme-color" content={pwaAssetsHead.themeColor.content} />
	{/if}
	{#each pwaAssetsHead.links as link}
	<link {...link} />
	{/each}
</svelte:head>

You can find a working example in the examples folder.

SvelteKit ​

安装 @vite-pwa/sveltekit ​

Workbox 配置 ​

globPatterns ​

Generate Custom Service Worker ​

SvelteKit PWA Plugin ​

SvelteKit PWA Plugin Options ​

SvelteKit Pages ​

自动更新 ​

Prompt for update ​

SvelteKit and Adapters ​

PWA Assets 实验性 from v0.4.0 ​

SvelteKit

安装 @vite-pwa/sveltekit

Workbox 配置

globPatterns

Generate Custom Service Worker

SvelteKit PWA Plugin

SvelteKit PWA Plugin Options

SvelteKit Pages

自动更新

Prompt for update

SvelteKit and Adapters

PWA Assets 实验性 from v0.4.0