Islands - Feather

An island is declared in JavaScript and mounted by a data-island attribute. When state changes, only the selectors you name are re-rendered.

island("counter", {
  persist: true,
  state: { count: 0 },
  actions: {
    increment() { this.state.count++; },
    decrement() { this.state.count--; }
  },
  render(state) {
    return { ".count": state.count };
  }
});

<div data-island="counter">
    <button data-action="decrement">-</button>
    <span class="count">0</span>
    <button data-action="increment">+</button>
</div>

Optimistic updates

Update the UI immediately, then reconcile with the server. The first callback runs at once. If the second fails, the first is rolled back.

await this.optimistic(
  () => { this.state.liked = true; },              // instant UI update
  () => api.post(`/posts/${this.data.id}/like`)    // rolls back on failure
);

Use ApiUtility from api.js rather than raw fetch. It handles CSRF tokens and retries, and raw fetch is a feather check error.

Drag and drop

Available through the draggable config, documented in full in the CLAUDE.md that ships with every project. Pair it with OrderingMixin on the model so positions persist.

Generating an island

feather generate island like-button

This writes the island file and wires it into the build. feather check reports an island no template mounts (orphan-island), and a template mounting an island that does not exist (missing-island).