1. Journal Stack Home

The simplest and quickest way to get started with Remix PWA is the CLI tool. It's available as a standalone executable that you can use to scaffold Remix PWA in your project.


Installation

Firstly, run the CLI executable.

Terminal
npx remix-pwa@latest init

This will prompt you to customise your PWA and install the dependencies.

Possible options are:

  • Language: The language you want to use for your service worker. Wether TypeScript or JavaScript.
  • Workbox: Wether you want to utilise Workbox or not. Currently, this is not supported.
  • Precache: Utilise Remix PWA precaching feature or not.
  • Features: Choose the features you want to use in your service worker. This could be: Service Worker, Background Sync, Web Manifest, Push Notifications, Client Utilities and Test Icons.
  • Remix app location: Where your app directory is located. This is the directory where your Remix application is located.
  • Install Dependencies: Wether you want to install the dependencies or not.

To explore the CLI the detail, check out this guide.

Set Up your Remix Config

Once you've installed Remix PWA, you need to set up your Remix config to use the service worker. To add typings, open up your Remix config file and add the following to the top of your file:

remix.config.ts
/** @type {import('@remix-pwa/dev').WorkerConfig} */
module.exports = {
  // ...
}

Check out the config section for a full rundown.

You should know!

Remix PWA compiler utilises the Remix configuration file under the hood. This allows you to change settings such as your worker runtime, build options, sourcemap and more.

You don't need to change any other thing in your Remix config. This would give you autocomplete and type checking for Remix PWA in your Remix config file.

Register your Service Worker

Remix currently knows nothing about your service worker. To register your service worker, open up your entry.client.tsx file and add the following to the bottom:

app/entry.client.tsx
import { loadServiceWorker } from '@remix-pwa/sw'

// ...

loadServiceWorker()

This will register your service worker and enable all the features you've enabled in the CLI.

To enable caching on client-side navigation (which you most definitely want to do), add the useSWEffect hook to the top of your root component.

app/root.tsx
import { useSWEffect } from '@remix-pwa/sw'

export default function App() {
  useSWEffect();

  return (
    <html lang="en">
      {/* ... */}
    </html>
  );
}

Add Service Worker HMR support

In your root.tsx file, replace the LiveReload component from @remix-run/react with LiveReload from @remix-pwa/sw. This will enable HMR support for your service worker and allow you to see changes in the service worker thread in real time.

app/root.tsx
import { LiveReload } from '@remix-pwa/sw'

export default function App() {
  return (
    <html lang="en">
      {/* ... */}
      <body>
        {/* ... */}
        <LiveReload />
      </body>
    </html>
  );
}

That's it! You've successfully set up Remix PWA in your Remix application. You can now start using Remix PWA features in your application or explore the docs to find out what else was shipped with Remix PWA v3.