Hwy

What is Hwy?

On the surface, Hwy is a simple, lightweight, and flexible web framework, featuring nested routing, concurrent data pre-fetching, and optional server-side rendering. At a deeper level, Hwy is just a protocol for passing nested, prefetched route data between (theoretically) any backend server and any client UI library.

Features

Nested, file-based routing
Optional SSR
Remix-style actions and parallel loaders
100% type-safe
ESM only
Server framework and UI library agnostic
Built-in critical CSS inlining and stylesheet bundling
CSS hot reloading
And more...

Project Goals

Be boring
Avoid feature bloat
Be easy to debug and understand
Keep dev and prod as identical as possible
Build on stable, "lowest-common-denominator" primitives
Be as tech-agnostic as possible
Change as little as possible over time
Avoid vendor-specific code
Prefer dumb solutions over clever ones

Quick Start

To create a new Hwy app using NodeJS, h3, and React, run the following command:

npx create-hwy@latest

This will simply copy the code contained at https://github.com/sjc5/hwy/examples/react into a new directory of your choosing. You can then run npm install and npm run dev to start the dev server.

Simple usage

Below is an example of a simple Hwy page at route your-domain.com/user/123. You'll notice it looks a lot like Remix, and you're right!

Server-side data files (for loaders, actions, and head tag definitions)

Hwy's server-side data files live inside the pages folder and contain .data. before their file extensions. These files are primarily responsible for pre-fetching data that will ultimately be fed into your UI components. Loaders are run concurrently to avoid waterfalls.

// src/pages/user/$user_id.data.ts

import type { DataProps } from "hwy";
import { getUser } from "./some-server-side-code.js";

export async function loader({ params }: DataProps) {
  return await getUser(params.user_id);
}

Isomorphic UI files

Hwy's isomorphic UI files live inside the pages folder and contain .ui. before their file extensions. These files are responsible for rendering the UI. Any data prefetched by the loaders is passed into the UI component as a prop.

// src/pages/user/$user_id.ui.tsx

import type { UIProps } from "@hwy-js/react";
import type { loader } from "./$user_id.data.ts";
import { UserProfile } from "./some-ui-code.js";

export default function ({ loaderData }: UIProps<typeof loader>) {
  return <UserProfile user={loaderData} />;
}

Project Status

Hwy is in alpha stage and is not recommended for use in production unless you know what you're doing. All APIs are subject to change without notice, so if you do decide to use Hwy, pin your versions, and be prepared to update your code frequently.

Additionally, Hwy is not currently open for contributions. If you have a feature request or bug report, please open an issue on GitHub.

// src/pages/user/$user_id.data.ts import type { DataProps } from "hwy"; import { getUser } from "./some-server-side-code.js"; export async function loader({ params }: DataProps) { return await getUser(params.user_id); }

// src/pages/user/$user_id.ui.tsx import type { UIProps } from "@hwy-js/react"; import type { loader } from "./$user_id.data.ts"; import { UserProfile } from "./some-ui-code.js"; export default function ({ loaderData }: UIProps<typeof loader>) { return <UserProfile user={loaderData} />; }