Skip to main content

Getting started

Install

Run the following command:

npm i -D @serwist/nuxt @serwist/vite serwist

Implementation

Step 1: Add Serwist’s Nuxt module and metadata

Update or create your Nuxt configuration file with the following content:

// https://nuxt.com/docs/api/configuration/nuxt-config
export default defineNuxtConfig({
  app: {
    head: {
      htmlAttrs: {
        lang: "en",
        dir: "ltr",
      },
      title: "Home",
      titleTemplate: "%s - PWA App",
      link: [
        {
          rel: "manifest",
          href: "/manifest.json",
        },
        {
          rel: "shortcut icon",
          href: "/favicon.ico",
        },
        {
          rel: "apple-touch-icon",
          href: "/apple-touch-icon.png",
          sizes: "180x180",
        },
      ],
      meta: [
        {
          name: "application-name",
          content: "PWA App",
        },
        {
          name: "description",
          content: "Best PWA app in the world!",
        },
        {
          name: "apple-mobile-web-app-capable",
          content: "yes",
        },
        {
          name: "apple-mobile-web-app-status-bar-style",
          content: "default",
        },
        {
          name: "apple-mobile-web-app-title",
          content: "My Awesome PWA App",
        },
        {
          name: "format-detection",
          content: "telephone=no",
        },
        {
          property: "og:type",
          content: "website",
        },
        {
          property: "og:title",
          content: "My Awesome PWA App",
        },
        {
          property: "og:description",
          content: "Best PWA app in the world!",
        },
        {
          property: "og:site:name",
          content: "PWA App",
        },
        {
          name: "twitter:card",
          content: "website",
        },
        {
          name: "twitter:title",
          content: "My Awesome PWA App",
        },
        {
          name: "twitter:description",
          content: "Best PWA app in the world!",
        },
        {
          name: "theme-color",
          content: "#FFFFFF",
        },
      ],
    },
  },
  devtools: { enabled: true },
  modules: ["@serwist/nuxt"],
  serwist: {},
});

Step 2: Update tsconfig.json

If you use TypeScript, you should add the following content to tsconfig.json in order to get the correct types:

{
  // Other stuff...
  "compilerOptions": {
    // Other options...
    "lib": [
      // Other libs...
      // Add this! Doing so adds WebWorker and ServiceWorker types to the global.
      "webworker"
    ],
  },
}

Otherwise, safely skip this step.

Step 3: Update .gitignore

If you use Git, update your .gitignore like so:

# Serwist
public/sw*
public/swe-worker*

Otherwise, safely skip this step.

Step 4: Create a service worker

Basic service worker template to get Serwist up and running:

import { defaultCache } from "@serwist/vite/worker";
import type { PrecacheEntry, SerwistGlobalConfig } from "serwist";
import { Serwist } from "serwist";

// This declares the value of `injectionPoint` to TypeScript.
// `injectionPoint` is the string that will be replaced by the
// actual precache manifest. By default, this string is set to
// `"self.__SW_MANIFEST"`.
declare global {
  interface WorkerGlobalScope extends SerwistGlobalConfig {
    __SW_MANIFEST: (PrecacheEntry | string)[] | undefined;
  }
}

declare const self: ServiceWorkerGlobalScope;

const serwist = new Serwist({
  precacheEntries: self.__SW_MANIFEST,
  skipWaiting: true,
  clientsClaim: true,
  navigationPreload: true,
  runtimeCaching: defaultCache,
});

serwist.addEventListeners();

Step 5: Add a web application manifest

Update public/manifest.json with the following content:

{
  "name": "My Awesome PWA app",
  "short_name": "PWA App",
  "icons": [
    {
      "src": "/icons/android-chrome-192x192.png",
      "sizes": "192x192",
      "type": "image/png",
      "purpose": "maskable"
    },
    {
      "src": "/icons/icon-512x512.png",
      "sizes": "512x512",
      "type": "image/png"
    }
  ],
  "theme_color": "#FFFFFF",
  "background_color": "#FFFFFF",
  "start_url": "/",
  "display": "standalone",
  "orientation": "portrait"
}

Step 6: Register the service worker

Add the following content to app.vue:

<script setup lang="ts">
// @ts-check
const { $serwist } = useNuxtApp();
$serwist?.addEventListener("installed", () => {
  console.log("Serwist installed!");
});
void $serwist?.register({ immediate: true });
</script>
<template>
  <div>
    <h1>Nuxt + Serwist</h1>
  </div>
</template>