Get Started

Start by installing Sietch (currently this has a prerequisite on having Go installed).

# TODO: Update when there are cross platform binaries available
go install github.com/danprince/sietch

Create a new directory for your site and add an index.md file like the one below.

---
title: Example Post
date: 2022-10-10
---

This is an example post.

Then run sietch to build your site.

sietch

During development you can serve your site locally with livereloading.

sietch --serve

Add the following counter.ts file to the directory.

export let render = ({ count }) => `<button>${count}</button>`;

export let hydrate = ({ count }, element: HTMLElement) => {
  let btn = element.querySelector("button")!;
  btn.onclick = () => btn.textContent = String(++count);
};

Then add the code to render it to your index.md page.

{{ component "./counter" (props "count" 0) }}

Islands are static by default, which means they're rendered at build time and no JS is sent to the client.

That means that the button below won't actually do anything.

We can fix that with the hydrate function. Opting-in to hydration means we'll ship the JS required to make the component interactive.

{{ component "./counter" (props "count" 0) | hydrate }}

Let's see it in action.

Note that the button was still rendered at build time, so browsers with slow connections, or JavaScript disabled would still see a button as soon as they opened the page.

If you take a peek at the bundle we're sending to the client now, you'll notice that we aren't shipping the render function to the client, because it isn't used.

You can also use Preact for your islands.

Now rename the counter.ts to counter.tsx and update the code to work with Preact.

import { useState } from "preact/hooks";

export default ({ count: init = 0 }) => {
  let [count, setCount] = useState(init);
  return <button onClick={() => setCount(count + 1)}>{count}</button>;
}

Now your island is powered by Preact.

Check out the islands reference for more information on using islands and writing components.