Nuxt 3
信息
警告
This PWA module can only be used with Vite.
Nuxt 3 Integration
vite-plugin-pwa
provides the new @vite-pwa/nuxt
module that will allow you to use vite-plugin-pwa
in your Nuxt 3 applications.
You will need to install @vite-pwa/nuxt
using:
npx nuxi@latest module add @vite-pwa/nuxt
To update your project to use the new @vite-pwa/nuxt
module for Nuxt 3, you only need to change the Nuxt config file adding the @vite-pwa/nuxt
module, move the vite-plugin-pwa
options to the module options, and remove the vite-pwa-plugin
plugin (if present):
export default defineNuxtConfig({
modules: ['@vite-pwa/nuxt'],
pwa: {
/* your pwa options */
},
});
Using Nuxt 3 Plugin
@vite-pwa/nuxt
will register a plugin that will provide PWA logic via $pwa
property when the PWA is enabled ($pwa
will be undefined
if PWA disabled or running dev server without PWA dev options enabled).
You can access $pwa
property directly inside your Vue component templates. You can also access to $pwa
in your Vue script setup or in any other module via useNuxtApp().$pwa
.
The module will provide the following features via $pwa
property:
- Prompt for update and offline ready via
needRefresh
andofflineReady
properties. - Cancelling prompt for update application and offline via
closePrompt
function. - Update application when using
prompt for update
behaviour viaupdateServiceWorker
function. - Intercepting
beforeinstallprompt
event viashowInstallPrompt
property: this feature will prevent the browser to show the defaultInstall PWA Application
prompt. - Cancelling install prompt via
cancelInstall
function. Install PWA application
viainstall
function.- Service worker registration status via
swActivated
andregistrationError
properties. - Service worker registration via
getSWActivated
function.
You will need to activate pwa.client.installPrompt
property in your Nuxt config file to enable beforeinstallprompt
event interception: configure true
or the key name used in local storage to store the beforeinstallprompt
cancellation for your install prompt/widget.
Additionally, you can also configure periodic sync for updates, you can enable it via pwa.periodicSyncForUpdates
property in your Nuxt config file: configure the interval in seconds in previous property.
You can disable this plugin by setting pwa.client.registerPlugin
property to false
in your Nuxt config file. In that case, you will need to import VanillaJS
or Vue
PWA virtual module in your application, and previous features will not be available (you can only access to the features exposed by the virtual module).
INFO
This is the initial release of @vite-pwa/nuxt
integration, we're working to improve it and add more features.
PWA 安装 Status from v0.3.5+
@vite-pwa/nuxt
provides the new $pwa?.isPWAInstalled
reactive property to check if your PWA application is installed.
注册 Web Manifest
To register the PWA web manifest in your Nuxt 3 application, @vite-pwa/nuxt
provides the functional components VitePwaManifest
and NuxtPwaManifest
, you should add one of them to your app.vue
or to all of your layouts (add only VitePwaManifest
or NuxtPwaManifest
).
提示
You can enable registerWebManifestInRouteRules
property in PWA configuration to register the web manifest in Nitro routeRules
property: useful for example if your application is deployed to Netlify.
Payload Extraction from v0.3.1+ offline support
When you enable the experimental payloadExtraction
flag in your Nuxt configuration file, @vite-pwa/nuxt
will add **/_payload.json
to the globPatterns
array inside workbox
or injectManifest
option, depending on the configured strategy
.
App Manifest from v0.3.1+ from Nuxt v3.8+ offline support
When you enable the experimental appManifest
flag in your Nuxt configuration file, @vite-pwa/nuxt
will:
- add
_nuxt/builds/**/*.json
to theglobPatterns
array insideworkbox
orinjectManifest
option, depending on the configuredstrategy
- remove
revision
entry from all service worker precache manifest files inside_nuxt/builds/
folder matching<UUID>.json
pattern (UUID is a random generated string by Nuxt).
TypeScript
export interface PwaInjection {
/**
* @deprecated use `isPWAInstalled` instead
*/
isInstalled: boolean;
/**
* From version v0.3.5+.
*/
isPWAInstalled: Ref<boolean>;
showInstallPrompt: Ref<boolean>;
cancelInstall: () => void;
install: () => Promise<void>;
swActivated: Ref<boolean>;
registrationError: Ref<boolean>;
offlineReady: Ref<boolean>;
needRefresh: Ref<boolean>;
updateServiceWorker: (reloadPage?: boolean | undefined) => Promise<void>;
cancelPrompt: () => Promise<void>;
getSWRegistration: () => ServiceWorkerRegistration | undefined;
}
declare module '#app' {
interface NuxtApp {
$pwa: UnwrapNestedRefs<PwaInjection>;
}
}
示例
VitePwaManifest/NuxtPwaManifest in app.vue
When adding VitePwaManifest
or NuxtPwaComponent
component to your app.vue
:
<template>
<VitePwaManifest />
<NuxtPage />
</template>
或者
<template>
<NuxtPwaManifest />
<NuxtPage />
</template>
then, the web manifest link will be added to your HTML pages:
<html>
<head>
<link rel="manifest" href="/manifest.webmanifest" />
</head>
</html>
Prompt for update and offline ready
<script setup>
// If you want to use it in setup, import from the nuxtApp.
const { $pwa } = useNuxtApp();
const toast = useToast();
onMounted(() => {
if ($pwa.offlineReady) toast.success('App ready to work offline');
});
</script>
<template>
<!-- You can use $pwa directly in templates! -->
<div v-show="$pwa.needRefresh">
<span> New content available, click on reload button to update. </span>
<button @click="$pwa.updateServiceWorker()">Reload</button>
</div>
</template>
PWA Assets 实验性 从 v0.6.0
新功能包括:
- new
NuxtPwaAssets
component to include the PWA assets in your HTML pages: if you're usingVitePwaManifest
orNuxtPwaManifest
component, replace it withNuxtPwaAssets
: it will inject the web manifest link, thetheme-color
meta and the PWA icon links. - new
PwaAppleImage
,PwaAppleSplashScreenImage
,PwaFaviconImage
,PwaMaskableImage
andPwaTransparentImage
components to use PWA icons in your code base - new
useApplePwaIcon
,useAppleSplashScreenPwaIcon
,useFaviconPwaIcon
,useMaskablePwaIcon
anduseTransparentPwaIcon
composables - injects
$pwaIcons
with all configured PWA icons: you can use them viauseNuxtApp().$pwaIcons
or inside your Vue templates
New components, composables and $pwaIcons
injection are statically analisable, that's, pwa icons types are generated when running nuxt prepare
command: if you want to disable the PWA assets you don't need to remove the code (you can remove unused components/code later if you want to remove the new feature).