@express-worker/router (EWR)

EWR provides a simple Next.js-like API for serving dynamically-generated, React-hydrated HTML web pages inside a Service Worker.

This is part of the @express-worker ecosystem. It depends on @express-worker/app to serve the routes. If this project is too opinionated for your needs, consider using @express-worker/app directly.

Features

App Router

Similar to Next.js, routes are defined as a directory structure under src/app.

React SSR

The initial page HTML is rendered by React-DOM/Server which then gets hydrated by React-DOM/Client.

Static File Handling

Static files in the public directory are cached and served by the service worker.

Installation

The repository needs to be set up with a specific directory structure.

Base the directory structure on the starter kit.

Usage

To add a new page:

1. Create a new folder in the src/app directory and create a page.tsx file inside it.

   Dynamic routes are defined by using square brackets in the folder name. For example, if you want to create a dynamic route for user profiles, you can create a folder with a path of src/app/profiles/[id].

   Each route folder should have a page.tsx inside. (Unlike Next.js, there is no layout.tsx file.)

2. Define the React component for the page as the default export.

3. Define and export getStaticProps and metadata. (See below.)

4. Run npm run build to regenerate the routes.

Static Props

getStaticProps is a function used to fetch data at render time. It allows you to fetch data from an API or database and pass it as props to the page component. The path params are passed to this function. You can define getStaticProps as follows:

export const getStaticProps: GetStaticProps = async function ({
  params: { id },
}) {
  const data = await fetchData({ id });

  return {
    props: {
      data,
    },
  };
};

Metadata

metadata is an object that contains information about the page, such as the title and description. You can define metadata as follows:

export const metadata: Metadata = {
  title: 'Page Title',
  description: 'Page description',
};

If you need to access the route params, you can export a function instead:

export const metadata: GetMetadata = ({ params: { id } }) => ({
  title: 'Note ' + id,
});

Page Component

The default export should be the Page component. It will receive the props defined in getStaticProps. It will be wrapped in the PageShell.

export default function HomePage({ data }: { data: Data }) {
  return <main>{data.foo}</main>;
}

Development

Run ewr dev during development.

For easiest debugging, in the Web Inspector, under the Application tab, under Service Workers, select the checkbox for "Update on reload".

Production Builds

Run ewr build to generate a production build/

The built-in strategy for invalidating the old cache and serving the updated content is through incrementing the version in router.config.json.

Publish the public directory to a static file hosting service. A 404.html file should be served as a catch-all route.

Benefits

Fast Page Rendering

Routes can pre-cache or inline key assets. This allows navigation between pages to be nearly instantaneous.

Simplified Hosting

The server only needs to be able to serve the initial static assets. This project uses Firebase Static Hosting.

Offline-Ready

When a user navigates to a route while offline, the service worker can serve a previously cached response or generate a new one based on stored data.

Drawbacks

No Search Engine Indexing

Pages generated by a service worker aren't indexed by search engines. You may need alternative strategies for SEO, such as generating static HTML snapshots or using a separate build process to create server-rendered pages.

License

This project is licensed under the MIT License.