Minimal H(TTP) framework built for high performance and portability.
npm install @vinxi/h3[![npm version][npm-version-src]][npm-version-href]
[![npm downloads][npm-downloads-src]][npm-downloads-href]
[![bundle][bundle-src]][bundle-href]
[![Codecov][codecov-src]][codecov-href]
[![License][license-src]][license-href]
[![JSDocs][jsdocs-src]][jsdocs-href]
H3 is a minimal h(ttp) framework built for high performance and portability.
đ Online Playground
âď¸ Portable: Works perfectly in Serverless, Workers, and Node.js
âď¸ Minimal: Small and tree-shakable
âď¸ Modern: Native promise support
âď¸ Extendable: Ships with a set of composable utilities but can be extended
âď¸ Router: Super fast route matching using unjs/radix3
âď¸ Compatible: Compatibility layer with node/connect/express middleware
``bashUsing npm
npm install h3
Using Nightly Releases
If you are directly using
h3 as a dependency:`json
{
"dependencies": {
"h3": "npm:h3-nightly@latest"
}
}
`h3:pnpm and yarn:
`json
{
"resolutions": {
"h3": "npm:h3-nightly@latest"
}
}
`npm:
`json
{
"overrides": {
"h3": "npm:h3-nightly@latest"
}
}
`Note: Make sure to recreate lockfile and
node_modules after reinstall to avoid hoisting issues.Usage
`ts
import { createServer } from "node:http";
import { createApp, eventHandler, toNodeListener } from "h3";const app = createApp();
app.use(
"/",
eventHandler(() => "Hello world!"),
);
createServer(toNodeListener(app)).listen(process.env.PORT || 3000);
`Example using listhen for an elegant listener:
`ts
import { createApp, eventHandler, toNodeListener } from "h3";
import { listen } from "listhen";const app = createApp();
app.use(
"/",
eventHandler(() => "Hello world!"),
);
listen(toNodeListener(app));
`Router
The
app instance created by h3 uses a middleware stack (see how it works) with the ability to match route prefix and apply matched middleware.To opt-in using a more advanced and convenient routing system, we can create a router instance and register it to app instance.
`ts
import { createApp, eventHandler, createRouter } from "h3";const app = createApp();
const router = createRouter()
.get(
"/",
eventHandler(() => "Hello World!"),
)
.get(
"/hello/:name",
eventHandler((event) =>
Hello ${event.context.params.name}!),
);app.use(router);
`Tip: We can register the same route more than once with different methods.
Routes are internally stored in a Radix Tree and matched using unjs/radix3.
For using nested routers, see this example
More app usage examples
`js
// Handle can directly return object or Promise`Utilities
H3 has a concept of composable utilities that accept
event (from eventHandler((event) => {})) as their first argument. This has several performance benefits over injecting them to event or app instances in global middleware commonly used in Node.js frameworks, such as Express. This concept means only required code is evaluated and bundled, and the rest of the utilities can be tree-shaken when not used.đ You can check list of exported built-in utils from JSDocs Documentation.
#### Body
-
readRawBody(event, encoding?)
- readBody(event)
- readValidatedBody(event, validate)
- readMultipartFormData(event)#### Request
-
getQuery(event)
- getValidatedQuery(event, validate)
- getRouterParams(event)
- getMethod(event, default?)
- isMethod(event, expected, allowHead?)
- assertMethod(event, expected, allowHead?)
- getRequestHeaders(event, headers) (alias: getHeaders)
- getRequestHeader(event, name) (alias: getHeader)
- getRequestURL(event)
- getRequestHost(event)
- getRequestProtocol(event)
- getRequestPath(event)
- getRequestIP(event, { xForwardedFor: boolean })#### Response
-
send(event, data, type?)
- sendNoContent(event, code = 204)
- setResponseStatus(event, status)
- getResponseStatus(event)
- getResponseStatusText(event)
- getResponseHeaders(event)
- getResponseHeader(event, name)
- setResponseHeaders(event, headers) (alias: setHeaders)
- setResponseHeader(event, name, value) (alias: setHeader)
- appendResponseHeaders(event, headers) (alias: appendHeaders)
- appendResponseHeader(event, name, value) (alias: appendHeader)
- defaultContentType(event, type)
- sendRedirect(event, location, code=302)
- isStream(data)
- sendStream(event, data)
- writeEarlyHints(event, links, callback)#### Sanitize
-
sanitizeStatusMessage(statusMessage)
- sanitizeStatusCode(statusCode, default = 200)#### Error
-
sendError(event, error, debug?)
- createError({ statusCode, statusMessage, data? })#### Route
-
useBase(base, handler)#### Proxy
-
sendProxy(event, { target, ...options })
- proxyRequest(event, { target, ...options })
- fetchWithEvent(event, req, init, { fetch? }?)
- getProxyRequestHeaders(event)#### Cookie
-
parseCookies(event)
- getCookie(event, name)
- setCookie(event, name, value, opts?)
- deleteCookie(event, name, opts?)
- splitCookiesString(cookiesString)#### Session
-
useSession(event, config = { password, maxAge?, name?, cookie?, seal?, crypto? })
- getSession(event, config)
- updateSession(event, config, update)
- sealSession(event, config)
- unsealSession(event, config, sealed)
- clearSession(event, config)#### Cache
-
handleCacheHeaders(event, opts)#### Cors
-
handleCors(options) (see h3-cors for more detail about options)
- isPreflightRequest(event)
- isCorsOriginAllowed(event)
- appendCorsHeaders(event, options) (see h3-cors for more detail about options)
- appendCorsPreflightHeaders(event, options) (see h3-cors for more detail about options)Community Packages
You can use more H3 event utilities made by the community.
Please check their READMEs for more details.
PRs are welcome to add your packages.
- h3-typebox
-
validateBody(event, schema)
- validateQuery(event, schema)
- h3-zod
- useValidatedBody(event, schema)
- useValidatedQuery(event, schema)
- h3-valibot
- useValidateBody(event, schema)
- useValidateParams(event, schema)`MIT
[npm-version-src]: https://img.shields.io/npm/v/h3?style=flat&colorA=18181B&colorB=F0DB4F
[npm-version-href]: https://npmjs.com/package/h3
[npm-downloads-src]: https://img.shields.io/npm/dm/h3?style=flat&colorA=18181B&colorB=F0DB4F
[npm-downloads-href]: https://npmjs.com/package/h3
[codecov-src]: https://img.shields.io/codecov/c/gh/unjs/h3/main?style=flat&colorA=18181B&colorB=F0DB4F
[codecov-href]: https://codecov.io/gh/unjs/h3
[bundle-src]: https://img.shields.io/bundlephobia/minzip/h3?style=flat&colorA=18181B&colorB=F0DB4F
[bundle-href]: https://bundlephobia.com/result?p=h3
[license-src]: https://img.shields.io/github/license/unjs/h3.svg?style=flat&colorA=18181B&colorB=F0DB4F
[license-href]: https://github.com/unjs/h3/blob/main/LICENSE
[jsdocs-src]: https://img.shields.io/badge/jsDocs.io-reference-18181B?style=flat&colorA=18181B&colorB=F0DB4F
[jsdocs-href]: https://www.jsdocs.io/package/h3