preact-iso


Isomorphic async tools for Preact.

- Lazy-load components using lazy() and , which also enables progressive hydration.
- Generate static HTML for your app using prerender(), waiting for lazy() components and data dependencies.
- Implement async-aware client and server-side routing using , including seamless async transitions.

---

- Routing
- Prerendering
- Nested Routing
- Non-JS Servers
- API Docs
- \
- \
- \
- Path Segment Matching
- useLocation()
- useRoute()
- lazy()
- \
- hydrate()
- prerender()
- locationStub()

---

Routing

preact-iso offers a simple router for Preact with conventional and hooks-based APIs. The component is async-aware: when transitioning from one route to another, if the incoming route suspends (throws a Promise), the outgoing route is preserved until the new one becomes ready.

``js
import { lazy, LocationProvider, ErrorBoundary, Router, Route } from 'preact-iso';

// Synchronous
import Home from './routes/home.js';

// Asynchronous (throws a promise)
const Profiles = lazy(() => import('./routes/profiles.js'));
const Profile = lazy(() => import('./routes/profile.js'));
const NotFound = lazy(() => import('./routes/_404.js'));

const App = () => (




{/ Alternative dedicated route component for better TS support /}


{/ default prop indicates a fallback route. Useful for 404 pages /}




);
`

Progressive Hydration: When the app is hydrated on the client, the route (Home or Profile in this case) suspends. This causes hydration for that part of the page to be deferred until the route's import() is resolved, at which point that part of the page automatically finishes hydrating.

Seamless Routing: When switching between routes on the client, the Router is aware of asynchronous dependencies in routes. Instead of clearing the current route and showing a loading spinner while waiting for the next route, the router preserves the current route in-place until the incoming route has finished loading, then they are swapped.

Prerendering

prerender() renders a Virtual DOM tree to an HTML string using preact-render-to-string. The Promise returned from prerender() resolves to an Object with html and links[] properties. The html property contains your pre-rendered static HTML markup, and links is an Array of any non-external URL strings found in links on the generated page.

Primarily meant for use with prerendering via @preact/preset-vite or other prerendering systems that share the API. If you're server-side rendering your app via any other method, you can use preact-render-to-string (specifically renderToStringAsync()) directly.

`js
import { LocationProvider, ErrorBoundary, Router, lazy, prerender as ssr } from 'preact-iso';

// Asynchronous (throws a promise)
const Foo = lazy(() => import('./foo.js'));

const App = () => (







);

hydrate();

export async function prerender(data) {
return await ssr();
}
`

Nested Routing

Some applications would benefit from having routers of multiple levels, allowing to break down the routing logic into smaller components. This is especially useful for larger applications, and we solve this by allowing for multiple nested components.

Partially matched routes end with a wildcard (/*) and only the remaining value will be passed to descendant routers for further matching. This allows you to create a parent route that matches a base path, and then have child routes that match specific sub-paths.

`js
import { lazy, LocationProvider, ErrorBoundary, Router, Route } from 'preact-iso';

import AllMovies from './routes/movies/all.js';

const NotFound = lazy(() => import('./routes/_404.js'));

const App = () => (









);

const TrendingMovies = lazy(() => import('./routes/movies/trending.js'));
const SearchMovies = lazy(() => import('./routes/movies/search.js'));
const MovieDetails = lazy(() => import('./routes/movies/details.js'));

const Movies = () => (







);
`

The component will be used for the following routes:
- /movies/trending
- /movies/search
- /movies/Inception
- /movies/...

It will not be used for any of the following:
- /movies
- /movies/

Non-JS Servers

For those using non-JS servers (e.g., PHP, Python, Ruby, etc.) to serve your Preact app, you may want to use our "polyglot-utils", a collection of our route matching logic ported to various other languages. Combined with a route manifest, this will allow your server to better understand which assets will be needed at runtime for a given URL, allowing you to say insert preload tags for those assets in the HTML head prior to serving the page.

---

API Docs

$3

A context provider that provides the current location to its children. This is required for the router to function.

Props:

- scope?: string | RegExp - Sets a scope for the paths that the router will handle (intercept). If a path does not match the scope, either by starting with the provided string or matching the RegExp, the router will ignore it and default browser navigation will apply.

Typically, you would wrap your entire app in this provider:

`js
import { LocationProvider } from 'preact-iso';

const App = () => (

{/ Your app here /}

);
`

$3

Props:

- onRouteChange?: (url: string) => void - Callback to be called when a route changes.
- onLoadStart?: (url: string) => void - Callback to be called when a route starts loading (i.e., if it suspends). This will not be called before navigations to sync routes or subsequent navigations to async routes.
- onLoadEnd?: (url: string) => void - Callback to be called after a route finishes loading (i.e., if it suspends). This will not be called after navigations to sync routes or subsequent navigations to async routes.

`js
import { LocationProvider, Router } from 'preact-iso';

const App = () => (

onRouteChange={(url) => console.log('Route changed to', url)}
onLoadStart={(url) => console.log('Starting to load', url)}
onLoadEnd={(url) => console.log('Finished loading', url)}
>





);
`

$3


There are two ways to define routes using preact-iso:

1. Append router params to the route components directly:
2. Use the Route component instead:

Appending arbitrary props to components not unreasonable in JavaScript, as JS is a dynamic language that's perfectly happy to support dynamic & arbitrary interfaces. However, TypeScript, which many of us use even when writing JS (via TS's language server), is not exactly a fan of this sort of interface design.

TS does not (yet) allow for overriding a child's props from the parent component so we cannot, for instance, define as taking no props _unless_ it's a child of a , in which case it can have a path prop. This leaves us with a bit of a dilemma: either we define all of our routes as taking path props so we don't see TS errors when writing or we create wrapper components to handle the route definitions.

While is completely equivalent to , TS users may find the latter preferable.

`js
import { LocationProvider, Router, Route } from 'preact-iso';

const App = () => (


{/ Both of these are equivalent /}








);
`

Props for any route component:

- path: string - The path to match (read on)
- default?: boolean - If set, this route is a fallback/default route to be used when nothing else matches

Specific to the Route component:

- component: AnyComponent - The component to render when the route matches

#### Path Segment Matching

Paths are matched using a simple string matching algorithm. The following features may be used:

- :param - Matches any URL segment, binding the value to the label (can later extract this value from useRoute())
- /profile/:id will match /profile/123 and /profile/abc
- /profile/:id? will match /profile and /profile/123
- /profile/:id* will match /profile, /profile/123, and /profile/123/abc
- /profile/:id+ will match /profile/123, /profile/123/abc
- * - Matches one or more URL segments
- /profile/* will match /profile/123, /profile/123/abc, etc.

These can then be composed to create more complex routes:

- /profile/:id/* will match /profile/123/abc, /profile/123/abc/def, etc.

The difference between /:id and /:id/ is that in the former, the id param will include the entire path after it, while in the latter, the id is just the single path segment.

- /profile/:id*, with /profile/123/abc
- id is 123/abc
- /profile/:id/*, with /profile/123/abc
- id is 123

You can narrow prop types for your routes using RoutePropsForPath:
`ts
import type { RoutePropsForPath } from 'preact-iso'

function User(props: RoutePropsForPath<'/user/:id'>) {
props.user.id2 // type error
props.user.id // no type error
}
`

$3

A hook to work with the LocationProvider to access location context.

Returns an object with the following properties:

- url: string - The current path & search params
- path: string - The current path
- query: Record - The current query string parameters (/profile?name=John -> { name: 'John' })
- route: (url: string, replace?: boolean) => void - A function to programmatically navigate to a new route. The replace param can optionally be used to overwrite history, navigating them away without keeping the current location in the history stack.

$3

A hook to access current route information. Unlike useLocation, this hook only works within components.

Returns an object with the following properties:

- path: string - The current path
- query: Record - The current query string parameters (/profile?name=John -> { name: 'John' })
- params: Record - The current route parameters (/profile/:id -> { id: '123' })

$3

Make a lazily-loaded version of a Component.

lazy() takes an async function that resolves to a Component, and returns a wrapper version of that Component. The wrapper component can be rendered right away, even though the component is only loaded the first time it is rendered.

`js
import { lazy, LocationProvider, Router } from 'preact-iso';

// Synchronous, not code-splitted:
import Home from './routes/home.js';

// Asynchronous, code-splitted:
const Profiles = lazy(() => import('./routes/profiles.js').then(m => m.Profiles)); // Expects a named export called Profiles
const Profile = lazy(() => import('./routes/profile.js')); // Expects a default export

const App = () => (







);
`

The result of lazy() also exposes a preload() method that can be used to load the component before it's needed for rendering. Entirely optional, but can be useful on focus, mouse over, etc. to start loading the component a bit earlier than it otherwise would be.

`js
const Profile = lazy(() => import('./routes/profile.js'));

function Home() {
return (
Profile.preload()}>
Profile Page -- Hover over me to preload the module!

);
}
`

$3

A simple component to catch errors in the component tree below it.

Props:

- onError?: (error: Error) => void - A callback to be called when an error is caught

`js
import { LocationProvider, ErrorBoundary, Router } from 'preact-iso';

const App = () => (

console.log(e)}>







);
`

$3

A thin wrapper around Preact's hydrate export, it switches between hydrating and rendering the provided element, depending on whether the current page has been prerendered. Additionally, it checks to ensure it's running in a browser context before attempting any rendering, making it a no-op during SSR.

Pairs with the prerender() function.

Params:

- jsx: ComponentChild - The JSX element or component to render
- parent?: Element | Document | ShadowRoot | DocumentFragment - The parent element to render into. Defaults to document.body if not provided.

`js
import { hydrate } from 'preact-iso';

const App = () => (


hydrate();
`

However, it is just a simple utility method. By no means is it essential to use, you can always use Preact's hydrate export directly.

$3

Renders a Virtual DOM tree to an HTML string using preact-render-to-string. The Promise returned from prerender() resolves to an Object with html and links[] properties. The html property contains your pre-rendered static HTML markup, and links is an Array of any non-external URL strings found in links on the generated page.

Pairs primarily with @preact/preset-vite's prerendering.

Params:

- jsx: ComponentChild - The JSX element or component to render

`js
import { LocationProvider, ErrorBoundary, Router, lazy, prerender } from 'preact-iso';

// Asynchronous (throws a promise)
const Foo = lazy(() => import('./foo.js'));
const Bar = lazy(() => import('./bar.js'));

const App = () => (








);

const { html, links } = await prerender();
`

$3

A utility function to imitate the location object in a non-browser environment. Our router relies upon this to function, so if you are using preact-iso outside of a browser context and are not prerendering via @preact/preset-vite (which does this for you), you can use this utility to set a stubbed location object.

`js
import { locationStub } from 'preact-iso/prerender';

locationStub('/foo/bar?baz=qux#quux');

console.log(location.pathname); // "/foo/bar"
``

License

MIT