Islands Architecture

Hyperspan is a server-oriented framework, which means that all JavaScript code that is sent to the client is explicitly opt-in. Hyperspan uses Islands Architecture to make specific areas of the page interactive, while leaving the rest of the page static and server-rendered.

If you need an area with client interactivity, you can use a Dynamic Island to render and hydrate a Preact (or React) component on the client.

Using Dynamic Islands

You can use the createPreactIsland function from the assets path to create a dynamic island for your Preact components.

import { html } from '@hyperspan/html';
import { createRoute } from '@hyperspan/framework';
import { createPreactIsland } from '@hyperspan/framework/assets';

// Bun supports top-level await, so this compiles at build/server start time
const ExampleCounter = await createPreactIsland(import.meta.resolve('@/src/components/ExampleCounter.tsx'));

export default createRoute(() => {
  return html`
    <div>
      <!-- Call the component as a function and pass any props you need! -->
      ${ExampleCounter({ count: 5 })}
    </div>
  `;
});

This will render a <script type="module"> tag with the component contents in it and a <div> tag that the component will mount and render into.

Example Client Counter Component

Using Other Frontend Frameworks

If you want to use a different frontend framework like Vue, Svelete, etc., feel free to do so! There is no magic here — Hyperspan is just using Bun.build() to get the JavaScript output of your component file, putting that in a <script> tag, and then adding a bit of extra code to render it as a component into a corresponding <div> tag.

Although Hyperspan only provides support for Preact/React components out of the box, you can use the same approach to create islands for other frameworks as well. Just look at the implementation of createPreactIsland on GitHub to get an idea of how to do it.