🏝 Islands Architecture

When running jaspr on the client, the Dart source code of your app will be compiled to javascript and shipped to the browser. This javascript bundle might get quite large for a more complex app or website.

When you are building a more content-heavy or mostly static website (static meaning without much user interaction) you probably don't need to ship your whole app structure to the client, but rather only relevant parts of your app - so called Islands - to allow certain parts to be interactive.

The 'Islands Architecture' pattern became popular again with recent web development trends. Islands are interactive parts of the page, that can be loaded and hydrated separately from each other.

You can read more about this architecture pattern at these resources:

Getting Started#

You should already be familiar with the @client annotation for components and the Document() component. Using these concepts jaspr already supports the islands architecture out of the box and there is no additional setup required.

Simply use one or multiple @client components when rendering the app on the server.

Manual setup#

If you choose not to use the recommended approach using the @client annotation or want to build a purely client-side app, you can also set this up manually.

In general, jaspr supports this architecture by allowing multiple parallel apps on the client. For example in your web/main.dart you can do this:

void main() {
  runApp(Header(), attachTo: '#header');
  runApp(Sidebar(), attachTo: '#sidebar');
  runApp(Content(), attachTo: '#content');
}

This will run three apps simultaneously, attached to the specified root elements. This example might expect a page layout like this:

<body>
  <div id="header"></div>
  <div>
    <div id="content"></div>
    <div id="sidebar"></div>
  </div>
</body>

The advantage of this approach is that you can leave other parts of your app, e.g. a static footer, out of the bundled javascript and thereby reducing loading and startup time.

Be aware that on the server, you must still construct the complete app layout and and render the targeted island components manually at the right location.