Architecture

Fresh is a server-first web framework. Pages are rendered on the server and only the interactive parts (islands) ship JavaScript to the browser. This page explains how a request flows through the framework.

Request lifecycle

Key concepts

Server-first rendering

Every page is fully rendered to HTML on the server before being sent to the browser. This means:

• Pages are visible immediately - no blank loading screens
• Search engines see complete content
• Pages work without JavaScript enabled

Islands architecture

Fresh uses the islands architecture. Only components in the islands/ directory are hydrated in the browser. Everything else is static HTML that never runs JavaScript on the client.

This means a page with a single interactive button only ships the JavaScript for that button - not for the entire page.

Middleware chain

Middlewares execute in registration order, wrapping the handler. Each middleware calls ctx.next() to pass control to the next middleware (or handler). This creates an onion-like pattern where middlewares can act on both the request (before ctx.next()) and the response (after ctx.next()):

app.use(async (ctx) => {
  // Before: runs on the way in
  console.log("Request:", ctx.url.pathname);

  const response = await ctx.next();

  // After: runs on the way out
  console.log("Status:", response.status);
  return response;
});

Scoped middleware runs only for requests that match a specific path prefix. Pass a path pattern as the first argument to app.use():

app.use("/admin/*", async (ctx) => {
  // Only runs for /admin/* routes
  const user = ctx.state.user;
  if (!user?.isAdmin) return new Response("Forbidden", { status: 403 });
  return ctx.next();
});

Global middleware runs on every request; scoped middleware lets you apply logic like authentication or logging to a subset of routes.

Layout inheritance

Layouts wrap page components and are inherited from parent directories. A page at routes/blog/post.tsx inherits layouts from:

1. routes/_layout.tsx (root layout)
2. routes/blog/_layout.tsx (section layout)

Layouts nest from the outside in: the root layout is outermost, each deeper layout wraps closer to the page, and the innermost layout directly wraps the page component. The app wrapper (_app.tsx) wraps everything.

Build and deploy

Fresh uses Vite to bundle island JavaScript for production. The deno task build command:

1. Discovers all islands and their dependencies
2. Bundles client-side JavaScript with code splitting
3. Generates a server entry point (_fresh/server.js)
4. Hashes assets for cache busting

In production, _fresh/server.js serves the pre-built assets. In development, Vite provides Hot Module Replacement for instant feedback.