Sapling

A framework agnostic, runtime agnostic, and router agnostic web-standards driven islands architecture solution for implementing selective hydration in your web applications.

Islands architecture allows you to progressively hydrate parts of your page, loading JavaScript and styles only when needed for optimal performance. Most of your page remains static HTML, with interactive "islands" that get hydrated with JavaScript when needed.

• Zero dependencies - Pure vanilla JavaScript web components
• Framework agnostic - Works with any framework or vanilla HTML
• Multiple loading strategies - Load on visibility, idle time, media queries, or immediately
• Web standards driven - Built on Custom Elements and other standard APIs
• Tiny footprint - Under 2KB for the core island component

Getting Started

NPM

npm install sapling-island

import "sapling-island";

CDN

<script
  type="module"
  src="https://cdn.jsdelivr.net/npm/sapling-island@0.2.2"
></script>

Basic Usage

Wrap any content that requires JavaScript in a <sapling-island> component:

<sapling-island loading="visible">
  <template>
    <script src="/scripts/interactive.js" type="module"></script>
    <style>
      /* Styles only loaded when needed */
    </style>
  </template>
  <div>Your interactive content here</div>
</sapling-island>

Loading Strategies

• loading="load" - Load immediately (default)
• loading="visible" - Load when visible in viewport
• loading="idle" - Load when browser is idle
• loading="(min-width: 768px)" - Load based on media query
• timeout="5000" - Force load after timeout

Packages

Package	Description	Version
create	A CLI for creating Sapling projects
create-sapling	A CLI for creating Sapling projects with npm
sapling-island	A web component for partial hydration	CDN

Example: Interactive Time Display

<sapling-island loading="visible">
  <template>
    <script>
      const time = document.querySelector("time");
    setInterval(() => {
      time.textContent = new Date().toLocaleTimeString();
    }, 1000);
    </script>
  </template>
  <div>
    <p>The time updates every second after hydration:</p>
    <p>Current time: <time>00:00</time></p>
  </div>
</sapling-island>

More Examples

Check out the Sapling Examples Repository for more examples of islands architecture patterns.

Why Islands Architecture?

Islands architecture significantly improves web performance by:

• Reducing JavaScript bundle size - Only load what's needed
• Faster initial page loads - Most content remains static HTML
• Better Core Web Vitals - Less JavaScript means better LCP and CLS scores
• Progressive enhancement - Works even when JavaScript fails to load
• Selective hydration - Hydrate components based on user interaction patterns

Browser Support

• Uses standard Web APIs (Custom Elements, IntersectionObserver)
• Falls back gracefully for older browsers
• Supports all modern browsers with ES6 module support