🪀 Multipage Fallback

Fallback unhandled requests to the nearest specified index within your single or multi page applications

• How does it work?
• Use with Express
• Use with Hono
• Use with Vite

Introduction

The multipage-fallback package is intended for managing unhandled requests in multipage applications. It automatically serves the nearest index file based on your configuration, with or without redirecting requests. This is especially beneficial when developing web applications that consist of multiple pages and routes.

With multipage-fallback, allows your application to gracefully handle situations where a specific route is not found. Instead of showing a 404 error page, the package will fallback to the nearest index file, providing a smooth user experience.

To use multipage-fallback, you simply need to install the package and configure it according to your project's needs. The package integrates seamlessly with popular frameworks and build tools, making it easy to incorporate into your existing development workflow.

How does it work?

Suppose you have the following source code structure:

├── package.json
├── vite.config.js
├── index.html
├── main.js
└── nested
    ├── index.html
    ├── nested.js
    └── subroute
        └─ index.html

multipage-fallback attempts to locate an index.html file that best matches the requested path. For instance, if the path is /nested/subroute/my/secret/path, the following file paths will be considered in order:

1. nested/subroute/my/secret/index.html
2. nested/subroute/my/index.html
3. nested/subroute/index.html
4. nested/index.html
5. index.html

In this situation, nested/subroute/index.html is selected because that file exists. If it were not available, the fallback would then be nested/index.html, and if that were also absent, it would further fall back to index.html at the root level.

The reason nested/subroute/my/secret/path/index.html is not considered in this process is due to the absence of a trailing /. If you want to include this path, you can set the strictTrailingSlash option to false.

Use with Express

📄 express.js

Always remember to include the multipage-fallback middleware at the very end of your app.

import express from "express"
import { expressMiddleware as multipageFallback } from "multipage-fallback"

const app = express()

// your routes/middlewares

app.use(multipageFallback())

app.listen(3000)

⚙️ Options

| Name | Default Value | Valid Types | | ---------------------- | ------------------ | ------------------ | | root | "./dist/" | string | | index | "index.html" | string | | nestingLimit | 8 | number | | sendOptions | SendOptions | SendOptions | | strictTrailingSlash | true | boolean | | redirect | false | boolean | | redirectRegex | /(?:)/ | RegExp | | redirectRemoveFileName | true | boolean |

Use with Hono

📄 hono.js

Always remember to include the multipage-fallback middleware at the very end of your app.

import { Hono } from "hono"
import { serve } from "@hono/node-server"
import { serveStatic } from "@hono/node-server/serve-static"
import { honoMiddleware as multipageFallback } from "multipage-fallback"

const app = new Hono()

// your routes/middlewares

app.use("/*", multipageFallback())

serve({ fetch: app.fetch, port: 3000 })

⚙️ Options

| Name | Default Value | Valid Types | | ---------------------- | -------------- | ----------- | | root | "./dist/" | string | | index | "index.html" | string | | nestingLimit | 8 | number | | strictTrailingSlash | false | boolean | | redirect | false | boolean | | redirectRegex | /(?:)/ | RegExp | | redirectRemoveFileName | true | boolean |

Use with Vite

📄 vite.config.js

import { vitePlugin as multipageFallback } from "multipage-fallback"

export default defineConfig({
  appType: "mpa",
  plugins: [multipageFallback()],
})

⚙️ Options

| Name | Default Value | Valid Types | | ---------------------- | -------------- | ----------- | | index | "index.html" | string | | nestingLimit | 8 | number | | strictTrailingSlash | true | boolean | | redirect | false | boolean | | redirectRegex | /(?:)/ | RegExp | | redirectRemoveFileName | true | boolean |

License

MIT