Fresh

https://usefresh.dev/docs/
Admin
Fresh is a small, fast and extensible full stack web framework built on Web Standards, designed for...
Tokens:72,406
Snippets:699
Trust Score:3.5
Update:2 weeks ago
Show doc for...
Tokens:
Raw
### Create a basic App with static files and a GET route

Source: https://usefresh.dev/docs/concepts/app

Initializes a new App, adds static file serving, defines a root route, and starts the server. This is the minimal setup for a Fresh application.

```typescript
const app = new App()
  .use(staticFiles())
  .get("/", () => new Response("hello"));

// Start server
app.listen();
```

--------------------------------

### Start production server with deno task start

Source: https://usefresh.dev/docs/deployment

Runs the start task, which executes deno serve -A _fresh/server.js to serve the built assets in production mode.

```bash
deno task start
```

--------------------------------

### Quick start with app.ws()

Source: https://usefresh.dev/docs/advanced/websockets

Registers a GET route that automatically upgrades to WebSocket and wires up event handlers. Handlers include open, message, and close.

```typescript
import { App } from "fresh";

const app = new App()
  .ws("/ws", {
    open(socket) {
      console.log("Client connected");
    },
    message(socket, event) {
      socket.send(`Echo: ${event.data}`);
    },
    close(socket, code, reason) {
      console.log("Client disconnected", code, reason);
    },
  });
```

--------------------------------

### Verify migration with deno tasks

Source: https://usefresh.dev/docs/advanced/vite

Run deno install to pull new npm packages, then use deno task dev, build, and start to verify the Vite setup. The output layout under _fresh/ remains the same as the Builder produced.

```bash
deno task dev      # starts Vite with HMR
deno task build    # writes _fresh/server.js and client assets
deno task start    # deno serve -A _fresh/server.js
```

--------------------------------

### .listen()

Source: https://usefresh.dev/docs/concepts/app

Starts the server.

```APIDOC
## [METHOD] .listen()

### Description
Starts the server.

### Method
Method

### Endpoint
`app.listen()`

### Request Example
```js
app.listen();
```

### Response
Starts the server.
```

--------------------------------

### Quick Start Command

Source: https://usefresh.dev/docs

Initializes a new Fresh app by running the deno run command with the @fresh/init package.

```bash
deno run -Ar jsr:@fresh/init
```

--------------------------------

### Install vite-imagetools

Source: https://usefresh.dev/docs/concepts/static-files

Installs vite-imagetools as a dev dependency for build-time image optimization.

```bash
deno add -D npm:vite-imagetools
```

--------------------------------

### app.listen() with port option

Source: https://usefresh.dev/docs/concepts/app

Pass an options object to customize which port to listen on and other aspects. Note: .listen() is only used when running your app directly with deno run -A main.ts; the default project setup uses deno task dev and deno task start, which spawn their own servers - calling .listen() alongside these will create a second server and cause AddrInUse errors.

```tsx
app.listen({ port: 4000 });
```

--------------------------------

### Install dependencies with Deno

Source: https://usefresh.dev/docs/advanced/troubleshooting

Install dependencies when Deno complains about missing packages. Add -r to force a clean reinstall if caching issues are suspected.

```bash
deno install --allow-scripts
```

--------------------------------

### Dockerfile for Fresh project

Source: https://usefresh.dev/docs/deployment/docker

Dockerfile for a Fresh project. Sets DENO_DEPLOYMENT_ID from a build argument, installs dependencies with deno install --allow-scripts (required to populate node_modules and run post-install scripts like Tailwind CSS), builds the project, exposes port 8000, and runs the server.

```dockerfile
FROM denoland/deno:latest

ARG GIT_REVISION
ENV DENO_DEPLOYMENT_ID=${GIT_REVISION}

WORKDIR /app

COPY . .
RUN deno install --allow-scripts
RUN deno task build

EXPOSE 8000

CMD ["deno", "serve", "-A", "_fresh/server.js"]
```

--------------------------------

### Example project structure for routes/

Source: https://usefresh.dev/docs/concepts/file-routing

Shows a typical routes/ directory layout with route groups, layouts, components, and islands.

```text
<project root>
├── deno.json
├── main.ts
├── vite.config.ts
└── routes
    ├── (marketing)  # Route group, used to group related routes
    │   ├── _layout.tsx  # Apply layout to all routes in this directory
    │   ├── about.tsx    # /about route
    │   ├── career.tsx   # /career route
    │   ├── (_components)  # related components
    │   │   └── newsletter-cta.tsx
    │   └── (_islands)  # Local island directory
    │       └── interactive-stats.tsx # Fresh treats this as an island
    └── shop
        ├── (_components)
        │   └── product-card.tsx
        ├── (_islands)
        │   └── cart.tsx # Fresh treats this as an island
        └── index.tsx
```

--------------------------------

### csp()

Source: https://usefresh.dev/docs/plugins/csp

Documentation for the csp() middleware from the Fresh framework, including usage examples and options.

```APIDOC
## csp()

### Description
The `csp()` middleware adds Content-Security-Policy headers to HTTP responses, restricting which resources a document is allowed to load. It can be configured with options for report-only mode, reporting endpoints, additional directives, and nonce-based CSP.

### Method
Middleware (use)

### Usage
```ts
import { csp } from "fresh";

const app = new App()
  .use(csp({
    // If true, sets Content-Security-Policy-Report-Only header instead
    // of Content-Security-Policy
    reportOnly: true,
    // If set, adds Reporting-Endpoints, report-to, and report-uri
    // directive.
    reportTo: "/api/csp-reports",
    // Additional CSP directives to add or override the defaults
    csp: [
      "script-src 'self' 'unsafe-inline' 'https://example.com'",
    ],
  }))
  .get("/", () => new Response("hello"));
```

### Parameters
#### Options (object)
- **reportOnly** (boolean) - Optional - If true, sets Content-Security-Policy-Report-Only header instead of Content-Security-Policy.
- **reportTo** (string) - Optional - If set, adds Reporting-Endpoints, report-to, and report-uri directive.
- **csp** (string[]) - Optional - Additional CSP directives to add or override the defaults.
- **useNonce** (boolean) - Optional - Enables nonce-based CSP. When enabled, Fresh automatically injects a unique nonce attribute onto every inline `<script>` and `<style>` tag during server rendering, and the CSP header replaces `'unsafe-inline'` with `'nonce-{value}'` in `script-src`, `style-src`, `default-src`, `script-src-elem`, `style-src-elem`, and `style-src-attr` directives. Each request gets a fresh nonce. Non-rendered responses (e.g. API routes returning JSON) fall back to `'unsafe-inline'`.

### Example with useNonce
```ts
import { csp } from "fresh";

const app = new App()
  .use(csp({ useNonce: true }))
  .get("/", (ctx) => {
    return ctx.render(
      <html>
        <head>
          <style>{"body { color: red; }"}</style>
        </head>
        <body>
          <h1>Hello</h1>
        </body>
      </html>,
    );
  });
```

### Notes
- If you set an explicit `nonce` attribute on a tag, it will be preserved in the HTML, but the CSP header will only contain the Fresh-generated nonce. The browser will block the tag unless its nonce matches the one in the CSP header. To avoid this, let Fresh manage nonces automatically.
- See the API docs for a list of all supported options.
```

--------------------------------

### Respond to GET request with app.get()

Source: https://usefresh.dev/docs/concepts/app

Handles a GET request to `/about` and returns a response with the pathname.

```javascript
app.get("/about", async (ctx) => {
  return new Response(`GET: ${ctx.url.pathname}`);
});
```

--------------------------------

### Install Vite and Fresh Vite plugin

Source: https://usefresh.dev/docs/migration-guide

Command to add the required dependencies to deno.json imports.

```bash
deno install npm:vite jsr:@fresh/plugin-vite
```

--------------------------------

### deno.json build and start tasks

Source: https://usefresh.dev/docs/deployment/deno-deploy

Required tasks in deno.json for Deno Deploy. The build task runs 'vite build' and the start task runs 'deno serve -A _fresh/server.js'.

```json
{
  "tasks": {
    "build": "vite build",
    "start": "deno serve -A _fresh/server.js"
  }
}
```

--------------------------------

### Render markdown file to HTML with @deno/gfm in Fresh

Source: https://usefresh.dev/docs/examples/markdown

Create a markdown file and a Fresh route that reads it and renders it as HTML using @deno/gfm. The route imports CSS and render from @deno/gfm, reads the file with Deno.readTextFile, and injects the generated HTML and CSS via dangerouslySetInnerHTML. Requires installing @deno/gfm with deno install jsr:@deno/gfm.

```markdown
## some heading

and some interesting text here

> oh look a blockquote
```

```tsx
import { define } from "@/utils.ts";
import { CSS, render as renderMarkdown } from "@deno/gfm";

export default define.page(async () => {
  const content = await Deno.readTextFile("./content/example.md");
  const html = renderMarkdown(content);

  return (
    <div>
      <h1>Here comes a markdown post:</h1>
      {/* deno-lint-ignore react-no-danger */}
      <style dangerouslySetInnerHTML={{ __html: CSS }} />
      {/* deno-lint-ignore react-no-danger */}
      <div dangerouslySetInnerHTML={{ __html: html }} />
    </div>
  );
});
```

--------------------------------

### Basic Fresh App Example

Source: https://usefresh.dev/docs

Creates a Fresh app with two routes: a root route returning a plain text response and a /jsx route rendering JSX. The app listens on the default port.

```typescript
import { App } from "fresh";

const app = new App()
  .get("/", () => new Response("hello world"))
  .get("/jsx", (ctx) => ctx.render(<h1>render JSX!</h1>));

app.listen();
```

--------------------------------

### Respond to GET with multiple middlewares

Source: https://usefresh.dev/docs/concepts/app

Handles a GET request with multiple middlewares before the final handler.

```javascript
app.get("/about", middleware1, middleware2, async (ctx) => {
  return new Response(`GET: ${ctx.url.pathname}`);
});
```

--------------------------------

### Route-to-layout mapping example

Source: https://usefresh.dev/docs/concepts/file-routing

Shows the desired mapping of routes to layouts: /about and /career use layout A, while /archive and /contact use layout B.

```text
/about -> layout A
/career -> layout A
/archive -> layout B
/contact -> layout B
```

--------------------------------

### App

Source: https://usefresh.dev/docs/advanced/api-reference

The main application class for Fresh. It is used to configure and start the server.

```APIDOC
## `App`

### Description
The main application class for Fresh. It is used to configure and start the server.

### Usage
```ts
import { App } from "fresh";
```

### Methods
- `listen(options?: ListenOptions): Promise<void>` - Starts the server with the given options.

### Types
- `FreshConfig` / `ResolvedFreshConfig` - App configuration types.
- `ListenOptions` - Options for `app.listen()`.

```

--------------------------------

### Path alias usage example

Source: https://usefresh.dev/docs/getting-started

Shows how to use the pre-configured `@/` alias for absolute imports versus relative paths. The alias is configured in `deno.json`.

```typescript
// With @/ alias
import { define } from "@/utils.ts";
import { Button } from "@/components/Button.tsx";

// Without alias (relative paths)
import { define } from "../utils.ts";
import { Button } from "../components/Button.tsx";
```

--------------------------------

### app.get()

Source: https://usefresh.dev/docs/concepts/app

Responds to a GET request with the specified middlewares. Can accept multiple middlewares and lazy middlewares.

```APIDOC
## app.get()

### Description
Responds to a `GET` request with the specified middlewares. Can accept multiple middlewares and lazy middlewares.

### Method
GET

### Endpoint
app.get(path, ...middlewares)

### Parameters
#### Path Parameters
- **path** (string) - Required - The URL path to match for GET requests.

#### Middlewares
- **middlewares** (function) - Required - One or more middleware functions. The last middleware typically returns a Response. Can also be a function that returns a promise resolving to a middleware (lazy loading).

### Request Example
```js
// Single middleware
app.get("/about", async (ctx) => {
  return new Response(`GET: ${ctx.url.pathname}`);
});

// Multiple middlewares
app.get("/about", middleware1, middleware2, async (ctx) => {
  return new Response(`GET: ${ctx.url.pathname}`);
});

// Lazy import
app.get("/about", async () => {
  const mod = await import("./middleware-or-handler.ts");
  return mod.default;
});
```

### Response
Returns a Response object from the middleware. The example returns a Response with the pathname.
```

--------------------------------

### app.mountApp()

Source: https://usefresh.dev/docs/concepts/app

Mount an entire other app at the specified path. The example mounts someRoutes at the root path.

```tsx
const someRoutes = new App()
  .get("/sitemap.xml", (ctx) => {/* ... */})
  .get("/robots.txt", (ctx) => {/* ... */});

export const app = new App()
  .use(staticFiles())
  .mountApp("/", someRoutes())
  .fsRoutes();
```

--------------------------------

### Allow list example

Source: https://usefresh.dev/docs/plugins/ip-filter

When an allow list is provided, only matching IPs are permitted. All other addresses are blocked.

```typescript
import { App, ipFilter } from "fresh";

const app = new App()
  .use(ipFilter({
    allowList: ["203.0.113.0/24", "2001:db8::/32"],
  }));
```

--------------------------------

### Configure OTLP endpoint for Deno OpenTelemetry

Source: https://usefresh.dev/docs/advanced/opentelemetry

Starts the Fresh app with Deno's OpenTelemetry enabled and configures the OTLP exporter endpoint. Traces are sent to the specified collector (e.g., Jaeger).

```bash
OTEL_DENO=true \
OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317 \
deno task start
```

--------------------------------

### Global middleware with ctx.next()

Source: https://usefresh.dev/docs/concepts/architecture

Middleware executes in registration order, wrapping the handler. This example logs the request path before calling ctx.next() and logs the response status after, demonstrating the onion-like pattern where middleware can act on both request and response.

```javascript
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;
});
```

--------------------------------

### Create and use a reusable plugin

Source: https://usefresh.dev/docs/plugins

Reusable plugins are functions that return a middleware. This example shows the plugin definition and its registration in the App instance.

```typescript
import type { MiddlewareFn } from "fresh";

export function requestId(): MiddlewareFn<{ requestId: string }> {
  return async (ctx) => {
    ctx.state.requestId = crypto.randomUUID();
    const res = await ctx.next();
    res.headers.set("X-Request-Id", ctx.state.requestId);
    return res;
  };
}
```

```typescript
import { App, staticFiles } from "fresh";
import { requestId } from "./plugins/request-id.ts";

const app = new App()
  .use(staticFiles())
  .use(requestId())
  .fsRoutes();
```

--------------------------------

### Route matching priority example

Source: https://usefresh.dev/docs/concepts/routing

Demonstrates that static routes take precedence over dynamic routes, and registration order matters for dynamic routes.

```typescript
const app = new App()
  // This is checked first since it's registered first
  .get("/posts/featured", () => new Response("Featured posts"))
  // This is checked second - won't match "/posts/featured" because it's
  // already handled above
  .get("/posts/:id", (ctx) => new Response(`Post: ${ctx.params.id}`));
```

--------------------------------

### define.middleware() helper for typings

Source: https://usefresh.dev/docs/concepts/middleware

Use define.middleware() to get type inference for middleware functions. This example logs a message and calls ctx.next().

```ts
import { define } from "../utils.ts";

const middleware = define.middleware(async (ctx) => {
  console.log("my middleware");
  return await ctx.next();
});
```

--------------------------------

### Test client-side island interactivity with buildFreshApp and startTestServer

Source: https://usefresh.dev/docs/testing

Tests client-side island interactivity by building the Fresh app and starting a test server. The first block is the test that fetches the served HTML and checks for island markup. The second block defines the buildFreshApp and startTestServer helpers used by the test.

```typescript
import { expect } from "@std/expect";
import { buildFreshApp, startTestServer } from "./test-utils.ts";

const app = await buildFreshApp();

Deno.test("Counter island renders correctly", async () => {
  const { server, address } = startTestServer(app);

  try {
    // Basic smoke test: verify the island HTML is served
    const response = await fetch(`${address}/`);
    const html = await response.text();

    expect(html).toContain('class="flex gap-8 py-6"');
    expect(html).toContain("3");
  } finally {
    await server.shutdown();
  }
});
```

```typescript
import { createBuilder, type InlineConfig } from "vite";
import * as path from "@std/path";

// Default Fresh build configuration
export const FRESH_BUILD_CONFIG: InlineConfig = {
  logLevel: "error",
  root: "./",
  build: { emptyOutDir: true },
  environments: {
    ssr: { build: { outDir: path.join("_fresh", "server") } },
    client: { build: { outDir: path.join("_fresh", "client") } },
  },
};

// Helper function to create and build the Fresh app
export async function buildFreshApp(config: InlineConfig = FRESH_BUILD_CONFIG) {
  const builder = await createBuilder(config);
  await builder.buildApp();
  return await import("../_fresh/server.js");
}

// Helper function to start a test server
export function startTestServer(app: {
  default: {
    fetch: (req: Request) => Promise<Response>;
  };
}) {
  const server = Deno.serve({
    port: 0,
    handler: app.default.fetch,
  });

  const { port } = server.addr as Deno.NetAddr;
  const address = `http://localhost:${port}`;

  return { server, address };
}
```

--------------------------------

### Sharing a signal between independent islands in Fresh

Source: https://usefresh.dev/docs/examples/sharing-state-between-islands

These three components form a complete example of sharing a signal between independent islands. The AddToCart island adds a product to the cart signal, the Cart island displays and removes items, and the route creates the signal with useSignal and passes it to both islands. The signal is created per-render, not at module level, so each request gets its own independent cart.

```tsx
import { type Signal } from "@preact/signals";
import { Button } from "../components/Button.tsx";

interface AddToCartProps {
  cart: Signal<string[]>;
  product: string;
}

export default function AddToCart(props: AddToCartProps) {
  const { cart, product } = props;
  return (
    <Button
      onClick={() => (cart.value = [...cart.value, product])}
      class="w-full"
    >
      Add{cart.value.includes(product) ? " another" : ""} "{product}" to cart
    </Button>
  );
}
```

```tsx
import { type Signal } from "@preact/signals";
import { Button } from "../components/Button.tsx";
import * as icons from "../components/Icons.tsx";

interface CartProps {
  cart: Signal<string[]>;
}

export default function Cart(props: CartProps) {
  const { cart } = props;
  return (
    <div>
      <h1 class="text-xl flex items-center justify-center">Cart</h1>
      <ul class="w-full bg-gray-50 mt-2 p-2 rounded-sm min-h-[6.5rem]">
        {cart.value.length === 0 && (
          <li class="text-center my-4">
            <div class="text-gray-400">
              <icons.Cart class="w-8 h-8 inline-block" />
              <div>Your cart is empty.</div>
            </div>
          </li>
        )}
        {cart.value.map((product, index) => (
          <CartItem cart={cart} product={product} index={index} />
        ))}
      </ul>
    </div>
  );
}

interface CartItemProps {
  cart: Signal<string[]>;
  product: string;
  index: number;
}

function CartItem(props: CartItemProps) {
  const remove = () => {
    const newCart = [...props.cart.value];
    newCart.splice(props.index, 1);
    props.cart.value = newCart;
  };

  return (
    <li class="flex items-center justify-between gap-1">
      <icons.Lemon class="text-gray-500" />
      <div class="flex-1">{props.product}</div>
      <Button onClick={remove} aria-label="Remove" class="border-none">
        <icons.X class="inline-block w-4 h-4" />
      </Button>
    </li>
  );
}
```

```tsx
import { useSignal } from "@preact/signals";
import AddToCart from "../islands/AddToCart.tsx";
import Cart from "../islands/Cart.tsx";
import { define } from "../utils.ts";

export default define.page(function CartPage() {
  const cart = useSignal<string[]>([]);
  return (
    <div>
      <AddToCart cart={cart} product="Lemon" />
      <AddToCart cart={cart} product="Lime" />
      <Cart cart={cart} />
    </div>
  );
});
```

--------------------------------

### Clone and run initial checks

Source: https://usefresh.dev/docs/contributing

Clone the Fresh repository and run `deno task ok` to execute formatting, linting, type checking, and the full test suite. Run this before submitting any pull request.

```bash
git clone https://github.com/denoland/fresh.git
cd fresh
deno task ok
```

--------------------------------

### new App(options?)

Source: https://usefresh.dev/docs/concepts/app

Constructor for the Fresh App class, accepting an options object for configuration.

```APIDOC
## [CONSTRUCTOR] new App(options?)

### Description
Creates a new Fresh application instance. The constructor accepts an optional options object for configuration.

### Method
Constructor

### Endpoint
`new App(options?)`

### Parameters
#### Options
- **basePath** (string) - Optional - Serve the app from a sub-path instead of root. All routes will be prefixed with this path.
- **trustProxy** (boolean) - Optional - When enabled, Fresh reads `X-Forwarded-Proto` and `X-Forwarded-Host` headers and rewrites `ctx.url` accordingly.

### Request Example
```js
const app = new App({
  basePath: "/my-app",
  trustProxy: true,
});
```

### Response
Returns a new `App` instance.
```

--------------------------------

### GET /api/posts/:id

Source: https://usefresh.dev/docs/examples/api-routes

Method-specific handler for GET requests to retrieve a post.

```APIDOC
## [GET] /api/posts/:id

### Description
Retrieves a single post by its ID. Returns 404 if not found.

### Method
GET

### Endpoint
/api/posts/:id

### Parameters
#### Path Parameters
- **id** (string) - Required - The post ID.

### Response
#### Success Response (200)
- Returns the post object.

#### Error Response (404)
- Returns JSON with an error message.

#### Response Example
```json
{ "error": "Not found" }
```
```

--------------------------------

### .listen()

Source: https://usefresh.dev/docs/concepts/app

Spawns a server and listens for incoming connections. Calls Deno.serve() internally.

```APIDOC
## `.listen()`

### Description
Spawns a server and listens for incoming connections. Calls `Deno.serve()` internally. Only use when running directly with `deno run`.

### Method
Server startup

### Endpoint
N/A

### Parameters
#### Options (optional)
- **port** (number) - Optional - The port to listen on. Defaults to the standard port.

### Request Example
```js
const app = new App()
  .get("/", () => new Response("hello"));

app.listen();
```

### Response
#### Success Response
- **server** (Server) - The spawned server instance.

#### Response Example
```js
app.listen({ port: 4000 });
```
```

--------------------------------

### Basic JSON API route with GET handler

Source: https://usefresh.dev/docs/examples/api-routes

Defines a basic JSON API route that returns a list of users for GET requests. The response shows the exact JSON output for a GET /api/users request.

```typescript
import { define } from "@/utils.ts";

export const handlers = define.handlers({
  GET(ctx) {
    const users = [{ id: 1, name: "Alice" }, { id: 2, name: "Bob" }];
    return Response.json(users);
  },
});
```

```json
[{ "id": 1, "name": "Alice" }, { "id": 2, "name": "Bob" }]
```

--------------------------------

### Create Fresh 2 demo project

Source: https://usefresh.dev/docs/migration-guide

Command to create a new Fresh 2 project for migration reference.

```shell
mkdir fresh2-demo && cd fresh2-demo && deno run -Ar jsr:@fresh/init
```

--------------------------------

### Combined rules example

Source: https://usefresh.dev/docs/plugins/ip-filter

When both lists are provided, deny rules are checked first. An IP that appears in both lists is blocked. In this example, all of 192.168.1.0/24 is allowed except 192.168.1.10.

```typescript
import { App, ipFilter } from "fresh";

const app = new App()
  .use(ipFilter({
    denyList: ["192.168.1.10"],
    allowList: ["192.168.1.0/24"],
  }));
```

--------------------------------

### Run dev task

Source: https://usefresh.dev/docs/getting-started

Launches the Fresh app in development mode. The terminal prints a URL to view the app.

```bash
deno task dev
```

--------------------------------

### Method-specific handlers for GET, PUT, DELETE

Source: https://usefresh.dev/docs/examples/api-routes

Defines separate handlers for GET, PUT, and DELETE methods. Methods not defined automatically return 405 Method Not Allowed.

```typescript
import { define } from "@/utils.ts";

export const handlers = define.handlers({
  async GET(ctx) {
    const post = await db.posts.find(ctx.params.id);
    if (!post) {
      return Response.json({ error: "Not found" }, { status: 404 });
    }
    return Response.json(post);
  },

  async PUT(ctx) {
    const body = await ctx.req.json();
    const post = await db.posts.update(ctx.params.id, body);
    return Response.json(post);
  },

  async DELETE(ctx) {
    await db.posts.delete(ctx.params.id);
    return new Response(null, { status: 204 });
  },
});
```

--------------------------------

### .get()

Source: https://usefresh.dev/docs/concepts/app

Registers a GET route handler.

```APIDOC
## [METHOD] .get()

### Description
Registers a GET route handler.

### Method
Chainable method

### Endpoint
`app.get(path, handler)`

### Parameters
- **path** (string) - Required - The route path.
- **handler** (function) - Required - A function that receives a context object and returns a Response.

### Request Example
```js
const app = new App()
  .get("/", () => new Response("hello"));
```

### Response
Returns the `App` instance for chaining.
```

--------------------------------

### Context.route

Source: https://usefresh.dev/docs/concepts/context

Get the matched route pattern.

```APIDOC
## Context.route

### Description
Contains the matched route pattern as a `string`. Will be `null` if no pattern matched.

### Properties
- **route** (string|null) - The matched route pattern.

### Example
```js
app.get("/foo/:id", (ctx) => {
  console.log(ctx.route); // Logs: "/foo/:id"
  // ...
});
```
```

--------------------------------

### Development server commands for docs and demo

Source: https://usefresh.dev/docs/contributing

Commands to run the docs site and Vite demo development servers and production builds. These use local Fresh packages for integration testing.

```bash
deno task www           # docs site dev server
deno task build-www     # docs site production build

deno task demo          # vite demo dev server
deno task demo:build    # vite demo production build
deno task demo:start    # serve vite demo production build
```

--------------------------------

### GET /api/time

Source: https://usefresh.dev/docs/examples/api-routes

Programmatic API route that returns the current time.

```APIDOC
## [GET] /api/time

### Description
Returns the current time as an ISO string.

### Method
GET

### Endpoint
/api/time

### Response
#### Success Response (200)
- Returns JSON with the current time.

#### Response Example
```json
{ "time": "2025-01-01T00:00:00.000Z" }
```
```

--------------------------------

### Run production-style build for WebSocket testing on older Deno/Fresh

Source: https://usefresh.dev/docs/advanced/websockets

Use this command to test WebSocket endpoints when using older Deno or Fresh versions, as the Vite dev server cannot complete the 101 handshake. This runs deno serve directly, so Deno.upgradeWebSocket() works as expected.

```bash
deno task build && deno task start
```

--------------------------------

### GET /api/users

Source: https://usefresh.dev/docs/examples/api-routes

Basic JSON API route that returns a list of users.

```APIDOC
## [GET] /api/users

### Description
Returns a list of users as JSON.

### Method
GET

### Endpoint
/api/users

### Response
#### Success Response (200)
- Returns a JSON array of user objects.

#### Response Example
```json
[{ "id": 1, "name": "Alice" }, { "id": 2, "name": "Bob" }]
```
```

--------------------------------

### Build and compile Fresh app with deno compile

Source: https://usefresh.dev/docs/deployment/deno-compile

Builds the Fresh app and generates a self-contained executable with deno compile. The --include _fresh flag embeds all built assets (JavaScript bundles, CSS, static files) in the binary.

```bash
# Build your app first
deno task build
# Generate self-contained executable
deno compile --output my-app --include _fresh -A _fresh/compiled-entry.js
```

--------------------------------

### Lazy middleware with app.get()

Source: https://usefresh.dev/docs/concepts/app

Handles a GET request with a lazily loaded middleware or handler.

```javascript
app.get("/about", async () => {
  const mod = await import("./middleware-or-handler.ts");
  return mod.default;
});
```

--------------------------------

### Define routes with App class

Source: https://usefresh.dev/docs/concepts/routing

Shows how to register routes using the App class with .get(), .post(), and dynamic segments like :id and *.

```typescript
import { App } from "fresh";

const app = new App()
  .get("/", () => new Response("hello")) // Responds to: GET /
  .get("/other", () => new Response("other")) // Responds to: GET /other
  .post("/upload", () => new Response("upload")) // Responds to: POST /upload
  .get("/books/:id", (ctx) => {
    // Responds to: GET /books/my-book, /books/cool-book, etc
    const id = ctx.params.id;
    return new Response(`Book id: ${id}`);
  })
  .get("/blog/:post/comments", (ctx) => {
    // Responds to: GET /blog/my-post/comments, /blog/hello/comments, etc
    const post = ctx.params.post;
    return new Response(`Blog post comments for post: ${post}`);
  })
  .get("/foo/*", (ctx) => {
    // Responds to: GET /foo/bar, /foo/bar/baz, etc
    return new Response("foo");
  });
```

--------------------------------

### Build assets with deno task build

Source: https://usefresh.dev/docs/deployment

Runs the build task, which executes vite build under the hood and creates the _fresh folder with optimized assets.

```bash
deno task build
```

--------------------------------

### Basic middleware chaining with data passing and header setting

Source: https://usefresh.dev/docs/concepts/middleware

Shows how to chain middlewares using .use() and .get() on an App instance. The first middleware sets ctx.state.greeting, the second adds a 'server' header, and the handler renders HTML using the state.

```tsx
const app = new App<{ greeting: string }>()
  .use((ctx) => {
    // Middleware to pass data
    ctx.state.greeting = "Hello world";
    return ctx.next();
  })
  .use(async (ctx) => {
    // Middleware to add a HTTP header
    const res = await ctx.next();
    res.headers.set("server", "fresh server");
    return res;
  })
  // A handler is a form of middleware that responds. Here we
  // render HTML and return it.
  .get("/", (ctx) => {
    return ctx.render(<h1>{ctx.state.greeting}</h1>);
  });
```

--------------------------------

### Add multiple middlewares with app.use()

Source: https://usefresh.dev/docs/concepts/app

Adds multiple middlewares at once. They are matched left to right.

```javascript
app.use(middleware1, middleware2, middleware3);
```

--------------------------------

### File-based route handlers with method-specific functions

Source: https://usefresh.dev/docs/concepts/routing

Exports a handlers object with GET and POST functions for file-based routing.

```typescript
import { define } from "@/utils.ts";

export const handlers = define.handlers({
  GET(ctx) {
    return new Response(JSON.stringify({ users: [] }), {
      headers: { "Content-Type": "application/json" },
    });
  },
  POST(ctx) {
    return new Response("Created", { status: 201 });
  },
});
```

--------------------------------

### app.listen()

Source: https://usefresh.dev/docs/concepts/app

Spawns a server and listens for incoming connections. This calls Deno.serve() internally. Only used when running your app directly with deno run -A main.ts.

```tsx
const app = new App()
  .get("/", () => new Response("hello"));

app.listen();
```

--------------------------------

### Deny list example

Source: https://usefresh.dev/docs/plugins/ip-filter

Blocks specific IPs or subnets. Any request from a matching address receives a 403 Forbidden response.

```typescript
import { App, ipFilter } from "fresh";

const app = new App()
  .use(ipFilter({
    denyList: ["192.168.1.10", "2001:db8::1", "10.0.0.0/8"],
  }));
```

--------------------------------

### Import from fresh

Source: https://usefresh.dev/docs/advanced/api-reference

Shows the main imports from the 'fresh' entry point for server-side code.

```typescript
import { App, createDefine, HttpError, page, staticFiles } from "fresh";
```

--------------------------------

### Exporting an array of middlewares

Source: https://usefresh.dev/docs/concepts/middleware

You can export an array of middlewares from a _middleware.ts file. This example defines two middlewares and exports them as an array.

```ts
import { define } from "../utils.ts";

const middleware1 = define.middleware(async (ctx) => {
  console.log("A");
  return await ctx.next();
});

const middleware2 = define.middleware(async (ctx) => {
  console.log("B");
  return await ctx.next();
});

export default [middleware1, middleware2];
```

--------------------------------

### Define a custom middleware

Source: https://usefresh.dev/docs/plugins

Use define.middleware to modify requests or add HTTP headers. This example adds an 'X-Fresh' header to the response.

```typescript
const addXFreshHeader = define.middleware(async (ctx) => {
  const res = await ctx.next();
  res.headers.set("X-Fresh", "served by Fresh");
  return res;
});
```

--------------------------------

### app.all()

Source: https://usefresh.dev/docs/concepts/app

Registers a route that responds to all HTTP verbs with the specified middlewares.

```APIDOC
## `.all()`

### Description
Responds to a request for all HTTP verbs with the specified middlewares.

### Method
ALL

### Endpoint
`/api/foo`

### Parameters
#### Middlewares
- **middlewares** (function) - Required - Middleware functions to execute for all HTTP verbs.

### Request Example
```js
app.all("/api/foo", async (ctx) => {
  return new Response("hehe");
});
```

### Response
#### Success Response (200)
- **body** (string) - The response body.

#### Response Example
```
hehe
```
```

--------------------------------

### Circular references example

Source: https://usefresh.dev/docs/advanced/serialization

Demonstrates that Fresh serializes shared objects once and restores references on the client, so `data.a` and `data.b` reference the same object.

```jsx
const shared = { value: 42 };
const data = { a: shared, b: shared };

// `data.a` and `data.b` will reference the same object on the client
<MyIsland data={data} />;
```

--------------------------------

### Get matched route pattern with ctx.route

Source: https://usefresh.dev/docs/concepts/context

Log the matched route pattern string via ctx.route. Returns null if no pattern matched.

```tsx
app.get("/foo/:id", (ctx) => {
  console.log(ctx.route); // Logs: "/foo/:id"
  // ...
});
```

--------------------------------

### Command diff: Update production server command

Source: https://usefresh.dev/docs/migration-guide

Shows the change from 'deno run -A main.ts' to 'deno serve -A _fresh/server.js' for launching Fresh in production mode.

```diff
- deno run -A main.ts
+ deno serve -A _fresh/server.js
```

--------------------------------

### Fresh project structure

Source: https://usefresh.dev/docs/getting-started

The generated project structure after initialization. It includes directories for components, islands, routes, static assets, and configuration files.

```text
<project root>
├── components/         # Store other components here. Can be named differently
│   └── Button.tsx
├── islands/            # Components that need JS to run client-side
│   └── Counter.tsx
├── routes/             # [File system based routes](/docs/concepts/file-routing)
│   ├── api/
│   │   └── [name].tsx  # API route for /api/:name
│   ├── [_app.tsx](/docs/concepts/app)        # Renders the outer <html> content structure
│   └── index.tsx       # Renders /
├── static/             # Contains static assets like css, logos, etc
│   └── ...
│
├── client.ts       # Client entry file that's loaded on every page.
├── main.ts         # The server entry file of your app
├── deno.json       # Contains dependencies, tasks, etc
└── [vite.config.ts](/docs/advanced/vite)  # Vite configuration file
```

--------------------------------

### Passing functions to islands is not supported (WRONG example)

Source: https://usefresh.dev/docs/concepts/islands

Shows an incorrect attempt to pass a function as a prop to an island. Functions are not serializable and are not supported.

```tsx
export default function () {
  // WRONG
  return <MyIsland onClick={() => console.log("hey")} />;
}
```

--------------------------------

### .use()

Source: https://usefresh.dev/docs/concepts/app

Adds a middleware to the app. Middlewares are applied in order.

```APIDOC
## [METHOD] .use()

### Description
Adds a middleware to the app. Middlewares are applied from top to bottom, meaning a middleware defined after a `.get()` handler will not be included for that handler.

### Method
Chainable method

### Endpoint
`app.use(middleware)`

### Parameters
- **middleware** (function) - Required - A middleware function that receives a context object and returns `ctx.next()` or a Response.

### Request Example
```js
const app = new App()
  .use((ctx) => {
    // Will be called for all middlewares
    return ctx.next();
  });
```

### Response
Returns the `App` instance for chaining.
```

--------------------------------

### Use .all() to respond to any HTTP method

Source: https://usefresh.dev/docs/concepts/routing

Shows how to register a route that responds to any HTTP method using .all().

```typescript
app.all("/api/health", () => new Response("ok"));
```

--------------------------------

### Filesystem-based middleware in _middleware.ts

Source: https://usefresh.dev/docs/concepts/middleware

Define a middleware in a _middleware.ts file inside the routes/ folder or subfolders. This example logs a message and calls ctx.next().

```ts
import { define } from "../utils.ts";

export default define.middleware(async (ctx) => {
  console.log("my middleware");
  return await ctx.next();
});
```

--------------------------------

### Builder

Source: https://usefresh.dev/docs/advanced/api-reference

Pre-Vite build system (legacy). See Builder.

```APIDOC
## `Builder`

### Description
Pre-Vite build system (legacy). See Builder.

### Usage
```ts
import { Builder } from "fresh/dev";
```

```

--------------------------------

### Create Cloudflare Worker entry file

Source: https://usefresh.dev/docs/deployment/cloudflare-workers

Create a server.js file as the Cloudflare Worker entry point. It imports the Fresh server and exports a fetch handler.

```javascript
import server from "./_fresh/server.js";

export default {
  fetch: server.fetch,
};
```

--------------------------------

### .all()

Source: https://usefresh.dev/docs/concepts/app

Registers a route handler for all HTTP methods.

```APIDOC
## [METHOD] .all()

### Description
Registers a route handler for all HTTP methods.

### Method
Chainable method

### Endpoint
`app.all(path, handler)`

### Parameters
- **path** (string) - Required - The route path.
- **handler** (function) - Required - A function that receives a context object and returns a Response.

### Request Example
```js
const app = new App()
  .all("/", () => new Response("All methods"));
```

### Response
Returns the `App` instance for chaining.
```

--------------------------------

### Using the <Head> component in a page

Source: https://usefresh.dev/docs/advanced/head

Use the <Head> component from 'fresh/runtime' to set page metadata in more complex scenarios. This example sets the title to 'About me'.

```tsx
import { Head } from "fresh/runtime";

export default define.page((ctx) => {
  return (
    <div>
      <Head>
        <title>About me</title>
      </Head>
      <h1>About me</h1>
      <p>I like Fresh!</p>
    </div>
  );
});
```

--------------------------------

### ALL /api/*

Source: https://usefresh.dev/docs/examples/api-routes

Catch-all handler that responds to any HTTP method.

```APIDOC
## [ALL] /api/*

### Description
Handles all HTTP methods for any path. Returns the request method in the response.

### Method
ALL

### Endpoint
/api/*

### Response
#### Success Response (200)
- Returns JSON with status and method.

#### Response Example
```json
{ "status": "ok", "method": "GET" }
```
```
Tokens:
Raw