Skip to content

Private previewMost of the architecture is written. First public release in 2027.

Directory structure

Hamur reads these folders and files by name; everything else is yours. hamur init writes the ones it needs and you add the rest.

PathWhat it holds
app/pages/Pages. A file is a route: about.ts is /about, blog/[slug].ts is /blog/:slug, [[...path]].ts matches every path.
app/layouts/Layouts. default.ts wraps every page.
app/middleware/Route middleware that runs before a page renders.
app/plugins/App plugins, run in file name order. A .client.ts or .server.ts suffix limits a plugin to one side.
app/app.tsThe root component. It wraps every layout and page. The extension follows the library: app.tsx, app.vue, app.svelte. See Routing.
app/error.tsThe error page. Without it the library's default error page is used.
app/app.config.tsThe app config, merged over appConfig in the config. It is public.
app/env.tsdefineEnv({ … }): the environment variables the app reads, validated and typed. See Environment.
app/components/Components used without an import, with components: true. See Modules.
app/composables/, app/utils/Their exports are auto-imported in app files with imports.autoImport. See Modules.
app/favicon.ico, app/icon.*, app/apple-icon.*Icon files, found by name: every document links them. favicon.ico is served as /favicon.ico; icon.(ico|png|svg|jpg|jpeg), icon<n>.* and apple-icon.(png|jpg|jpeg), apple-icon<n>.* get a hashed URL under app.buildAssetsDir. See Head.
app/opengraph-image.*, app/twitter-image.*, the same in any folder of app/pages/, with *.alt.txtOpen Graph and Twitter image files: the image tags of the pages in that folder and below, the nearest file winning. A page file with either name fails the build. See Head.
app/graphql/The app's own GraphQL operations, *.graphql. See GraphQL.
server/index.tsThe door of the server. Its named exports are the handlers pages can call, and its default export, defineServer({ plugins, middleware, handlerMiddleware }), is the rest. See Server.
server/**Any other file under server/ is yours: handler definitions, helpers, anything. Folders mean nothing, and a file is reachable only through server/index.ts.
server/utils/Their exports are auto-imported in server files with imports.autoImport. See Modules.
server/graphql/The GraphQL schema (*.graphql), resolvers (*.resolver.ts) and context.ts, with server.graphql. See GraphQL.
shared/Code for both sides, imported through the #shared alias. Nothing in it is auto-imported.
public/Static files, copied into the build as they are, except dotfiles and dot-directories (.env, .git/), which are skipped with a warning; only public/.well-known/ is published. See Assets.
hamur.config.tsThe config.

.hamur/ holds build files and .output/ holds the build. Both are generated and belong in .gitignore.

Pages and layouts

A page and a layout with the html library:

ts
import { Link } from "@hamur/adapter-html";
import type { HtmlProps } from "@hamur/adapter-html";

export default function DefaultLayout({ children }: HtmlProps): string {
  return `<div>
  <header>${Link({ to: "/", children: "Home" })} ${Link({ to: "/about", children: "About" })}</header>
  ${children}
</div>`;
}

A page that needs a value before it renders has a load file next to it, with the same name and a .load.ts ending. blog/[slug].load.ts loads the data for blog/[slug].ts. It runs on the server for the first render and in the browser for every navigation, and it calls handlers for anything that lives on the server. See Data.

ts
import type { Load } from "hamur/app";

export const load = (({ params }) => ({ title: `Post ${params.slug}` })) satisfies Load;

Server

A handler is defineHandler({ … }) in any file under server/. What a page calls, and what a URL answers, is what server/index.ts exports. A handler with a route answers that URL; this one answers GET /api/hello:

ts
import { defineHandler } from "hamur/server";

export const hello = defineHandler({
  route: "/api/hello",
  method: "GET",
  handler() {
    return { message: "Hello" };
  },
});

server/index.ts exports it with export { hello } from "./hello.ts";. A file name carries no path and no method; the definition says both. Server files are TypeScript: server/index.ts is .ts, and so are the files that define handlers.

Styles

Importing a .scss, .sass, .less or .styl file fails the build with app/main.scss: Sass needs a CSS preprocessor plugin; install @hamur/css and sass (06 §2) (Less and Stylus name their own tools), unless a module plugin compiles the file. Compile the file to CSS before the build and import the .css file, or add a module whose plugin compiles the extension.

sh
bunx sass app/main.scss app/main.css

Assets

An image, font, audio, video or PDF file that app code imports becomes a hashed asset URL. import logo from "./logo.png" gives a string such as /_hamur/logo-49779094.png, the same in the server HTML and in the browser, under app.buildAssetsDir and app.baseURL. The build copies the file into .output/public/. Files in public/ are not imported: they are served as they are, at the path they have in the folder.

Image size: ?meta

import hero from "./hero.jpg?meta" gives { src, width, height, format } instead of the URL string: src is the asset URL a plain import gives, and the file is emitted the same way. The size comes from the file's header at build time, so the server HTML and the browser get the same value, and nothing is decoded. format is "png", "jpeg", "gif", "webp", "avif" or "svg"; animated: true is added for a GIF with more than one frame and a WebP with the animation flag. A JPEG with EXIF orientation 5 to 8 gives its width and height swapped, as it is shown.

ts
import hero from "./hero.jpg?meta"; // { src: "/_hamur/hero-1a2b3c4d.jpg", width: 1600, height: 900, format: "jpeg" }

?meta takes PNG, JPEG, GIF, WebP, AVIF and SVG files. The generated types declare every ?meta import as ImageMeta from hamur. One query per import: ./hero.jpg?meta&x and ./hero.jpg?size fail the build, and so does a with { type: ... } attribute on a query import. A file that is not the image its extension says fails the build with its path, such as app/hero.png: not a PNG file (no IHDR chunk). For a file in public/ or one read by a module, readImageMeta of hamur/kit reads the same header.

Blur placeholder: ?placeholder

import blur from "./hero.jpg?placeholder" gives a string data:image/png;base64,…: a ThumbHash blur of the image from Bun.Image#placeholder(), a PNG of at most 32 px (0.9 to 2.6 KB measured), computed at build, so the server HTML and the browser get the same value. The file itself is not emitted. Pass it to Img or Picture of @hamur/image as placeholder.

tsx
import hero from "./hero.jpg?meta";
import blur from "./hero.jpg?placeholder";

<Img src={hero} alt="" sizes="100vw" placeholder={blur} />;

?placeholder takes PNG, JPEG, WebP and GIF files; any other type fails the build with its path, such as app/pages/index.ts: "./hero.avif?placeholder": ?placeholder takes PNG, JPEG, WebP or GIF files, and so does a file Bun.Image cannot decode. The generated types declare every ?placeholder import as string; the one-query rule of ?meta applies.

Inline SVG: ?component

import Logo from "./logo.svg?component" gives a component of your UI library that renders the SVG inline, so CSS can style it and currentColor reaches it. Props go on the root <svg> over the file's own attributes: class (className in React), width, height, style, aria-* and any other attribute. title becomes the first child <title>; without title, aria-label or aria-labelledby the <svg> gets aria-hidden="true", as a decorative image should.

tsx
import Logo from "./logo.svg?component";

<Logo class="logo" width={32} title="Hamur" />

The build reads the file and keeps only what is safe to put in a page: SVG 2's elements and attributes (no <script>, <foreignObject>, <style>, class or on* attribute), links that are #…, http: or https: on <a>, or a PNG, JPEG, GIF or WebP data: URL on <image>, and presentation attributes and style properties with plain values: colours, lengths, url(#…), and transform functions on a transform; !important is dropped. Since <style> and class go, export your SVGs with presentation attributes, as Figma does by default and Illustrator does with the "Presentation Attributes" CSS option, so fill and stroke sit on each shape. The ids in the file, and the url(#…) and href="#…" references to them, get a prefix per rendered copy from the library's SSR-stable id (useId, createUniqueId, $props.id()), so two logos on one page keep their own gradients, and the server HTML and the hydrated page agree. A file with its own aria-label, aria-labelledby, aria-hidden or <title> keeps it, and gets no aria-hidden from the component. The generated types declare *.svg?component as your library's component type; a plain import logo from "./logo.svg" still gives the URL.