Getting Started

Overview

⚡ H3 (short for H(TTP), pronounced as /eɪtʃθriː/, like h-3) is a lightweight, fast, and composable server framework for modern JavaScript runtimes. It is based on web standard primitives such as Request, Response, URL, and Headers. You can integrate H3 with any compatible runtime or mount other web-compatible handlers to H3 with almost no added latency.

H3 is designed to be extendable and composable. Instead of providing one big core, you start with a lightweight H3 instance and then import built-in, tree-shakable utilities or bring your own for more functionality. Composable utilities has several advantages:

• The server only includes used code and runs them exactly where is needed.
• Application size can scale better. Usage of utilities is explicit and clean, with less global impact.
• H3 is minimally opinionated and won't limit your choices.

All utilities, share an H3Event context.

Quick Start

Install h3 as a dependency:

npm i h3@beta

yarn add h3@beta

pnpm i h3@beta

bun i h3@beta

deno i h3@beta

Create a new file for server entry:

import { H3, serve } from "h3";

const app = new H3().get("/", (event) => "⚡️ Tadaa!");

serve(app, { port: 3000 });

Then, run the server using your favorite runtime:

node --watch ./server.mjs

deno run -A --watch ./server.mjs

bun run --watch server.mjs

And tadaa! We have a web server running locally.

What Happened?

Okay, let's now break down our hello world example.

We first created an H3 app instance using new H3():

const app = new H3();

H3 is a tiny class capable of matching routes, generating responses and calling middleware and global hooks.

Then we add a route for handling HTTP GET requests to / path.

app.get("/", (event) => {
  return { message: "⚡️ Tadaa!" };
});

We simply returned an object. H3 automatically converts values into web responses.

Finally, we use serve method to start the server listener. Using serve method you can easily start an H3 server in various runtimes.

serve(app, { port: 3000 });

We also have app.fetch which can be directly used to run H3 apps in any web-compatible runtime or even directly called for testing purposes.

import { H3, serve } from "h3";

const app = new H3().get("/", () => "⚡️ Tadaa!");

// Test without listening
const response = await app.fetch("/");
console.log(await response.text());

You can directly import h3 library from CDN alternatively. This method can be used for Bun, Deno and other runtimes such as Cloudflare Workers.

import { H3 } from "https://esm.sh/h3@beta";

const app = new H3().get("/", () => "⚡️ Tadaa!");

export const fetch = app.fetch;