Introducing Serwist.

[DuCanhGH]

Serwist

I'm proud to announce Serwist, the successor of @ducanh2912/next-pwa. Here is its current home: https://github.com/serwist/serwist. What have changed between @ducanh2912/[email protected] and @serwist/[email protected] are listed here.

It is a fork of Workbox, which is why Workbox's commit history and list of contributors remain intact. We don't, however, have it marked as a fork because it causes issues with searching for the repo on Github. Two months of work (I actually slacked off a lot to be honest) went into it so as to remove unnecessary burden on the codebase.

It is also a successor of @ducanh2912/next-sw, which used to be my silly attempt at reinventing the wheel...

Future plans

• Reintroduce a documentation website.
• Add @serwist/vite.
• Remove unused code.
• Re-add examples.
• Re-add tests.
• Re-add temporarily removed features.

Why?

Maintenance for Workbox pretty much... stopped. There hasn't been any activity from its active maintainer for nearly half a year, and that last activity also took place after nearly a year of hiatus. Some of its dependencies are deprecated/vulnerable, which leaves us to a hellhole of security risks. I felt like taking the project under my wing, but, same as @ducanh2912/next-pwa, this project won't be advertised around.

What does this mean for @ducanh2912/next-pwa?

This changes things for the package. While I won't add a lot of new features like in the past, I will keep it maintained. This repo was what truly introduced me to the world of doing open source, and it has taught me a lot of things.

Note that @ducanh2912/next-pwa@10, the last (or not?) major release, will be released soon (approx. 3 weeks). Being essentially a backport from @serwist/[email protected], it will change and remove a lot of unnecessary features.

Why was GenerateSW removed?

I felt like it was too much burden on Serwist's codebase for pretty much nothing. In exchange, I added @serwist/sw, which exports installSerwist, a function that works like GenerateSW in InjectManifest. Simply put, to migrate from @ducanh2912/next-pwa to @serwist/next, you only need to add app/sw.{ts,js}:

import { defaultCache } from "@serwist/next/browser";
import type { PrecacheEntry } from "@serwist/precaching";
import { installSerwist } from "@serwist/sw";

declare const self: ServiceWorkerGlobalScope & {
  // Change this attribute's name to your `injectionPoint`.
  __SW_MANIFEST: (PrecacheEntry | string)[] | undefined;
};

installSerwist({
  precacheEntries: self.__SW_MANIFEST,
  skipWaiting: true,
  clientsClaim: true,
  navigationPreload: true,
  runtimeCaching: defaultCache,
});

Then change your next.config.mjs:

// @ts-check
import withSerwistInit from "@serwist/next";

const withSerwist = withSerwistInit({
  cacheOnFrontEndNav: true,
  swSrc: "app/sw.ts",
  swDest: "public/sw.js",
});

/** @type {import("next").NextConfig} */
const nextConfig = {
  reactStrictMode: true,
};

export default withSerwist(nextConfig);

This allows you to use modules in urlPattern since we no longer try to stringify the function.

NodeNext support

While moduleResolution: "nodenext" with "type": "module" works fine, "type": "commonjs" doesn't for now. This is because I've not figured out a way to emit .d.cts for .ts files with tsc (it would emit .d.cts for .cts files, but I'd rather not duplicate code for such a silly reason) without rollup-plugin-dts (this package doesn't play nice with declarationMap for obvious reasons). So, unfortunately, I guess you'd have to use moduleResolution: "node" for now (or just start using "type": "module") if you are using Serwist.

The above issue 🤓☝️ has been fixed.

Afterword

Thank you for your continued support! It really means a lot to me :)

I'd also like to thank @KPixel (sorry for tagging you the millionth time) for helping me out with the project!

Happy thoughts...

[SahilAggarwal2004]

Although serwist is good, but there are some features that are available in your next-pwa fork but not in @serwist/next.
Can we expect those features in serwist or should I stick with next-pwa?

Edit: The feature I want the most is offline fallbacks. I just read that you have removed it temporarily.

[DuCanhGH]

@SahilAggarwal2004 bloody hell. Just found out that we forgot to handle method for handler of type string...

[SahilAggarwal2004]

I don't know how to react to this situation. Although I am stuck but this still seems funny, more because it is very much relatable to me (I do these type of silly mistakes very often).
Anyways, I am happy that I was able to contribute to the library indirectly.

[SahilAggarwal2004]

I see that the issue has now been resolved in v8.4.3. Thanks a lot for that!
But when I log the request on console, there is no header info, it's an empty object for all the requests. Do I need to configure something so that I can receive the headers too?

[SahilAggarwal2004]

Also, I don't know why but Link component imported from next/link doesn't work for the first time when client goes offline and navigates perfectly on further tries. I am not able to figure out what could be the reason for this

[DuCanhGH]

@SahilAggarwal2004 try adding .entries() to the log.

Also, I don't know why but Link component imported from next/link doesn't work for the first time when client goes offline and navigates perfectly on further tries. I am not able to figure out what could be the reason for this

You have to visit a page once before it is available offline. If that's not what you want, precache those pages.

[maiconsanson]

@DuCanhGH the URL of https://github.com/serwist/serwist is going to https://www.youtube.com/watch?v=dQw4w9WgXcQ 😄

Maybe this little migration guide could be in a place more visible.
Thank you for your effort, by the way.

[DuCanhGH]

@maiconsanson oops, called out 🫢 Removing that :D

[MatsG23]

I cannot install this package. It is like only macOS had been specifically targeted yet.

npm ERR! code EBADPLATFORM
npm ERR! notsup Unsupported platform for [email protected]: wanted {"os":"darwin"} (current: {"os":"linux"})
npm ERR! notsup Valid os:  darwin
npm ERR! notsup Actual os: linux

[DuCanhGH]

@MatsG23 I daily drive Linux 🤨 Seems that everything works fine on my end, which is weird. Can you try other package managers such as pnpm, bun, and yarn? Perhaps they don't enforce this OS requirement.

Edit: try 8.0.3, in which I removed fsevents! Seems that it isn't even used anyway.

[maiconsanson]

I've migrated without problems from "@ducanh2912/next-pwa": "9.7.2" to "@serwist/next": "8.0.2" using Ventura 13.6 and pnpm 8.11.0 at M1 PRO.

[DuCanhGH]

@maiconsanson well, this problem specifically does not happen to macOS users 😅 It's the opposite, actually. Not that I could reproduce that, but fsevents does indeed have an "os" array in its package.json.

[maiconsanson]

Sure! Now I see that I was dumb. 😄 Sorry for the hurry.

[MatsG23]

Works with version 8.0.3 without fsevents! Thanks.

[Murkrage]

I'm not sure if this is good or not, haven't looked into it enough yet, but I really appreciate your continued effort! Would you recommend to continue using @serwist/sw or is there an alternative to get PWA's working for Next?

[DuCanhGH]

@Murkrage obviously I would recommend using Serwist, but if that doesn't work, there are other alternatives such as @ducanh2912/next-pwa (it remains supported by the way), Workbox, vite-plugin-pwa (if you want to migrate from Next.js to Vite, that is), and next-pwa (it is pretty much abandoned though).

[Murkrage]

Oh yeah no I mostly mean the way we configure Next. Is the recommended way still to use the Next configuration file together with the generate / install method?

[DuCanhGH]

@Murkrage I actually lost you there 😅 Seems that you are not very familiar with English. But if I inferred this right, then no, Serwist doesn't have GenerateSW, which means that there's no plug-n-play way of using it. @serwist/sw exists to fill its vacant spot, but using this package still obviously involves a bit of code. You can use InjectManifest like how you would with Workbox though, so that's an alternative.

[Murkrage]

Seems that you are not very familiar with English

What an odd thing to say... I'm a native speaker but I'm not sure how that's relevant 🙃

I'm indeed referring to a plug-and-play solution like next-pwa, or now serwist/sw. Whether the plug-and-play solution is the recommended way, which comes with a support burden on your end, or if we should try to move away from that solution and instead work with the core set of tools Serwist, like Workbox, provides.

[DuCanhGH]

@Murkrage huh, sorry for that then. I assumed that because I noticed a grammar error and you seemed to struggle with describing your question (I actually didn't understand "generate / install method")... Perhaps it's actually the native speakers that don't emphasize on the importance of grammar, which has been grilled into my head after having learnt English for too long. Putting this problem aside, @serwist/sw is the abstraction on top of Serwist's tools, replacing GenerateSW, so you can think of it as the "plug-and-play" way of using Serwist. How you would use it is described in the post :)

[ajayvignesh01]

Somehow, I wasn't able to get your fork of next-pwa working, but this is working like a charm lol.

[DuCanhGH]

💀
I'd like you to elaborate further if possible :D

[SahilAggarwal2004]

Woah, usually the reverse happens😂

[maiconcarraro]

Just migrated from next-pwa to serwist few hours ago, looking great so far, do you think about enabling the sponsor for the new project?

[DuCanhGH]

@maiconcarraro Well, this problem has been brought up quite a few times, so I'm just gonna be frankly honest about the biggest problem, being that I don't even have a credit card, which is required for foreign services like GitHub Sponsors. I actually have a domestic banking account (I use it to buy most things, including games on Steam), but that isn't supported obviously. I'm thinking about acquiring one though. Workbox's codebase actually had me wanting to kick myself in the nuts a few times (not as badly as back when I was actively contributing to Next.js though), so that whole open source spirit was straight up thrown out of the window 💀

[maiconcarraro]

gotcha, in case you have an amazon wishlist or steam wishlist, I'm happy to buy you something as well

[maniraj1234]

Ig you can use paypal @DuCanhGH

[aNyMoRe0505]

just come here to say thank you for your effort ❤️

[aNyMoRe0505]

Hello, I'd like to confirm if my understanding is correct on the following points:

1. @serwist/next only supports versions of Next.js that are v14 and above, and it specifically works with app routes (not compatible with page routes).

2. If we want to use a custom worker, we just need to write the logic under app/sw.js.

Thank you.

[DuCanhGH]

@aNyMoRe0505 what makes you think that the package only supports App Router? The Getting started page specifically includes pages/_app.tsx templates. swSrc: "app/sw.ts" was only used to make an example. You can set this value to anything that points to a valid file, such as "service-worker/index.ts".

[aNyMoRe0505]

@DuCanhGH
sorry, I read too quickly and I haven't started the migration process yet.
I thought sw.js could only be placed in the app folder
I apologize for the misunderstanding. I'll take the time to properly migrate to serwist.
Thank you.

[maniraj1234]

Hey @DuCanhGH,
This migration guide is pretty seamless. however I'm getting a linting issue with sw.ts which I couldn't resolve :(
5:21 error 'ServiceWorkerGlobalScope' is not defined no-undef

[DuCanhGH]

{
  // Other stuff...
  "compilerOptions": {
    // Other options...
    "types": [
      // Other types...
      // This allows Serwist to type `window.serwist`.
      "@serwist/next/typings"
    ],
    "lib": [
      // Other libs...
      // Add this! Doing so adds WebWorker and ServiceWorker types to the global.
      "webworker"
    ],
  },
}

[maniraj1234]

still same issue. PR ref: https://github.com/maniraj1234/kuberviz/pull/13/files

[DuCanhGH]

@maniraj1234 just ESLint things. Simply disable no-undef.

See https://eslint.org/docs/latest/rules/no-undef#handled_by_typescript. This rule is not recommended for TS projects.

[maniraj1234]

This worked. thanks.

[DuCanhGH]

Please stop using this thread to ask questions related to Serwist. You should open a new Discussion in Serwist's repo instead.