Getting started

Create a Hum app, start it locally, and make your first change. The default template is a Node.js app built with Vite, Preact, and Hono.

Create and run the app

Use Node.js 22.18 or later. The scaffold uses npm by default; pnpm and other package managers work too.

npm create hum@latest my-app
cd my-app
npm install
npm run dev

Open the local URL printed by Vite. The starter page is in routes/index.tsx; edit its title or markup and save to see the change with HMR.

Add an island

Pages render to HTML on the server. To add browser-side component state or event handlers, export a component declared with defineIsland and import it into a route. Hum generates its ID and client registration; no special directory or client-entry import is needed. For example:

// components/Counter.tsx — no special directory required
import { defineIsland } from "@humjs/core/client";
import { useSignal } from "@preact/signals";

export const Counter = defineIsland(({ start = 0 }: { start?: number }) => {
  const count = useSignal(start);
  return <button onClick={() => count.value++}>{count}</button>;
});

The generated template already includes a default-exported island in islands/Counter.tsx:

// routes/index.tsx
import Counter from "../islands/Counter.js";

export default function Home() {
  return (
    <main>
      <h1>Welcome to my app</h1>
      <p>This page is rendered as HTML on the server.</p>
      <Counter start={0} />
    </main>
  );
}

Only the island is hydrated in the browser; the rest of the page remains server-rendered HTML. For an interaction that does not need component state, see the page-level reactivity guide.

Build and serve

The basic template compiles the server app to ESM modules and bundles client assets into dist/. npm dependencies stay external. Build and run the Node server with:

npm run build
npm start

For a simple deployment, add standalone: true to your existing Hum plugin options and rebuild. Copy the entire dist/ directory to your server and run node dist/server.js; no dependency installation is needed there. The Cloudflare template already selects this mode.

Native addons and packages that require their installed resources need a non-standalone build with production dependencies. The deployment guide starts with standalone, then covers installing production dependencies for an ordinary project and handling local packages in a monorepo, with pnpm as an example.

The server listens on port 3000 by default; set PORT to change it. The Hono guide explains middleware and API routes.

Next: Routing and rendering →