### Define the start method signature

Source: https://usefresh.dev/docs/1.x/concepts/server-configuration

The primary entry point for starting the server, requiring a manifest and optional configuration.

```typescript
export async function start(manifest: Manifest, config: FreshConfig = {});
```

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

### Start the development server with Deno task

Source: https://usefresh.dev/docs/1.x/getting-started/running-locally

Use the default task runner to start the project with automatic environment variable loading.

```bash
$ deno task start
Watcher Process started.
 🍋 Fresh ready
     Local: http://localhost:8000
```

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

### Initialize Fresh server

Source: https://usefresh.dev/docs/1.x/concepts/ahead-of-time-builds

Start the Fresh application using the shared configuration.

```typescript
import { start } from "$fresh/server.ts";
import manifest from "./fresh.gen.ts";
import config from "./fresh.config.ts";

await start(manifest, config);
```

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

### Updating deno.json start task

Source: https://usefresh.dev/docs/1.x/examples/changing-the-src-dir

Diff showing the necessary changes to the start task in deno.json to point to the new src directory.

```json
 {
   "lock": false,
   "tasks": {
-    "start": "deno run -A --watch=static/,routes/ dev.ts"
+    "start": "deno run -A --watch=src/static/,src/routes/ src/dev.ts"
   },
   "imports": {
     "$fresh/": "file:///Users/reed/code/fresh/",
```

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

### Log route parameters

Source: https://usefresh.dev/docs/1.x/examples/handling-complex-routes

Example output of the params object when matching the simple route override.

```json
{
  module: "bestModule",
  version: "1.33.7",
  path: "asdf"
}
```

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

### Initialize and start a new Fresh project

Source: https://usefresh.dev/docs/1.x/getting-started/create-a-project

Run these commands in your terminal to scaffold a new project, navigate to its directory, and launch the development server.

```bash
deno run -A -r https://usefresh.dev
cd fresh-project
deno task start
```

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

### Full index.ts file reference

Source: https://usefresh.dev/docs/1.x/examples/creating-a-crud-api

Complete implementation for GET and POST handlers for listing and creating users.

```typescript
import { Handlers } from "$fresh/server.ts";

type User = {
  id: string;
  name: string;
};

const kv = await Deno.openKv();

export const handler: Handlers<User | null> = {
  async GET(_req, _ctx) {
    const users = [];
    for await (const res of kv.list({ prefix: ["user"] })) {
      users.push(res.value);
    }
    return new Response(JSON.stringify(users));
  },
  async POST(req, _ctx) {
    const user = (await req.json()) as User;
    const userKey = ["user", user.id];
    const ok = await kv.atomic().set(userKey, user).commit();
    if (!ok) throw new Error("Something went wrong.");
    return new Response(JSON.stringify(user));
  },
};
```

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

### Initialize a Fresh plugin

Source: https://usefresh.dev/docs/1.x/concepts/plugins

Register plugins within the start function in the main.ts file.

```typescript
import { start } from "$fresh/server.ts";
import manifest from "./fresh.gen.ts";

import twindPlugin from "$fresh/plugins/twind.ts";
import twindConfig from "./twind.config.js";

await start(manifest, {
  plugins: [
    // This line configures Fresh to use the first-party twind plugin.
    twindPlugin(twindConfig),
  ],
});
```

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

### Directory Structure for Opting Out of Layouts

Source: https://usefresh.dev/docs/1.x/concepts/layouts

Example directory structure demonstrating where to place files to skip layout inheritance.

```text
└── <root>/routes
    ├── sub
    │   ├── _layout_.tsx
    │   ├── special.tsx  # should not inherit layouts
    │   └── index.tsx
    └── _layout.tsx
```

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

### PUT request body example

Source: https://usefresh.dev/docs/1.x/examples/creating-a-crud-api

Example payload for updating a user via PUT.

```json
{
  "id": "2",
  "name": "New Name"
}
```

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

### Install Github Flavored Markdown module

Source: https://usefresh.dev/docs/1.x/examples/rendering-markdown

Command to add the required GFM dependency to the project.

```bash
deno add jsr:@deno/gfm
```

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

### Define application routes

Source: https://usefresh.dev/docs/1.x/examples/writing-tests

Example of a route handler and a page component for testing.

```typescript
import { Handlers } from "$fresh/server.ts";

export const handler: Handlers = {
  async POST(req) {
    const form = await req.formData();

    // Processing something

    return new Response(null, {
      status: 303,
      headers: { location: "/" },
    });
  },
};

export default function HomePage() {
  return <div>Hello Deno!</div>;
}
```

```typescript
export default function FooPage() {
  return <div>Hello Foo!</div>;
}
```

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

### PUT response example

Source: https://usefresh.dev/docs/1.x/examples/creating-a-crud-api

Expected JSON response after a successful PUT operation.

```json
{ "id": "2", "name": "New Name" }
```

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

### Middleware execution output

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

Example console output showing the destination types for various requests handled by the middleware.

```text
Task start deno run -A --watch=static/,routes/ dev.ts
Watcher Process started.
The manifest has been generated for 4 routes and 1 islands.

 🍋 Fresh ready
    Local: http://localhost:8000/

route
http://localhost:8000/
internal
http://localhost:8000/_frsh/js/3c7400558fc00915df88cb181036c0dbf73ab7f5/deserializer.js
internal
http://localhost:8000/_frsh/js/3c7400558fc00915df88cb181036c0dbf73ab7f5/signals.js
internal
http://localhost:8000/_frsh/js/3c7400558fc00915df88cb181036c0dbf73ab7f5/plugin-twind-main.js
internal
http://localhost:8000/_frsh/js/3c7400558fc00915df88cb181036c0dbf73ab7f5/main.js
internal
http://localhost:8000/_frsh/js/3c7400558fc00915df88cb181036c0dbf73ab7f5/island-counter.js
internal
http://localhost:8000/_frsh/refresh.js
static
http://localhost:8000/logo.svg?__frsh_c=3c7400558fc00915df88cb181036c0dbf73ab7f5
internal
http://localhost:8000/_frsh/alive
internal
http://localhost:8000/_frsh/js/3c7400558fc00915df88cb181036c0dbf73ab7f5/chunk-PDMKJVJ5.js
internal
http://localhost:8000/_frsh/js/3c7400558fc00915df88cb181036c0dbf73ab7f5/chunk-UGFDDSOV.js
internal
http://localhost:8000/_frsh/js/3c7400558fc00915df88cb181036c0dbf73ab7f5/chunk-RCK7U3UF.js
```

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

### Example DELETE response

Source: https://usefresh.dev/docs/1.x/examples/creating-a-crud-api

The expected response body after a successful DELETE request.

```text
user 2 deleted
```

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

### Example user creation payload

Source: https://usefresh.dev/docs/1.x/examples/creating-a-crud-api

JSON structure required for the POST request body when creating a new user.

```json
{
  "id": "2",
  "name": "TestUserName"
}
```

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

### Example stylesheet definition

Source: https://usefresh.dev/docs/1.x/examples/using-csp

A basic CSS snippet used to demonstrate CSP style directive configuration.

```css
h1 {
  font-size: 25px;
  font-weight: normal;
  margin-top: 5px;
  margin-left: 25px;
}
```

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

### PATCH request body example

Source: https://usefresh.dev/docs/1.x/examples/creating-a-crud-api

Example payload for updating only specific properties via PATCH.

```json
{
  "name": "New Name"
}
```

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

### Define a custom GET handler with page rendering

Source: https://usefresh.dev/docs/1.x/getting-started/custom-handlers

Demonstrates a GET handler that renders the page component and adds a custom header to the response.

```typescript
import { Handlers } from "$fresh/server.ts";

export const handler: Handlers = {
  async GET(_req, ctx) {
    const resp = await ctx.render();
    resp.headers.set("X-Custom-Header", "Hello");
    return resp;
  },
};

export default function AboutPage() {
  return (
    <main>
      <h1>About</h1>
      <p>This is the about page.</p>
    </main>
  );
}
```

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

### Example API response

Source: https://usefresh.dev/docs/1.x/examples/creating-a-crud-api

The expected JSON response returned by the server after a successful POST request.

```json
{ "id": "2", "name": "TestUserName" }
```

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

### Ambiguous Route Group Example

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

Illustrates an invalid configuration where multiple groups map to the same URL, causing ambiguity.

```text
└── <root>/routes
    ├── (group-1)
    │   └── about.tsx  # Bad: Maps to same `/about` url
    └── (group-2)
        └── about.tsx  # Bad: Maps to same `/about` url
```

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

### Error output for client-only APIs

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

Example of the ReferenceError encountered when accessing browser APIs during server-side rendering.

```text
An error occurred during route handling or page rendering. ReferenceError: EventSource is not defined
    at Object.MyIsland (file:///Users/someuser/fresh-project/islandsmy-island.tsx:6:18)
    at m (https://esm.sh/v129/preact-render-to-string@6.2.0/X-ZS8q/denonext/preact-render-to-string.mjs:2:2602)
    at m (https://esm.sh/v129/preact-render-to-string@6.2.0/X-ZS8q/denonext/preact-render-to-string.mjs:2:2113)
    ....
```

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

### Define local markdown file content

Source: https://usefresh.dev/docs/1.x/examples/rendering-markdown

Example content for a local markdown file that includes front matter and markdown syntax.

```markdown
---
description: testFromText
---

# Really Big Text

**bold**
```

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

### View server-side rendered island HTML annotations

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

Example of the HTML comments Fresh uses to identify island placement and slots during server-side rendering.

```html
<!--frsh-myisland_default:default:0-->
<div>
  Counter is at 0.
  <button>+</button>
  <!--frsh-slot-myisland_default:children-->
  <p>This text is rendered on the server</p>
  <!--/frsh-slot-myisland_default:children-->
</div>
<!--/frsh-myisland_default:default:0-->
```

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

### Example CSP Violation Report

Source: https://usefresh.dev/docs/1.x/examples/using-csp

A sample JSON structure of a CSP violation report received by the report handler.

```json
{
  "csp-report": {
    "document-uri": "http://localhost:8000/incorrectCSPwithReport",
    "referrer": "http://localhost:8000/incorrectCSPwithReport",
    "violated-directive": "style-src-elem",
    "effective-directive": "style-src-elem",
    "original-policy": "default-src 'none'; style-src 'unsafe-inline' http://www.example.com; report-uri http://localhost:8000/reportHandler; script-src 'nonce-0f2d8259315d40479e8c21979128ac0d'; connect-src 'self'",
    "disposition": "report",
    "blocked-uri": "http://localhost:8000/example.css",
    "line-number": 37,
    "source-file": "http://localhost:8000/incorrectCSPwithReport",
    "status-code": 200,
    "script-sample": ""
  }
}
```

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

### Full [id].ts file reference

Source: https://usefresh.dev/docs/1.x/examples/creating-a-crud-api

Complete implementation for GET, DELETE, and PUT handlers for a specific user ID.

```typescript
import { Handlers } from "$fresh/server.ts";

type User = {
  id: string;
  name: string;
};

const kv = await Deno.openKv();

export const handler: Handlers<User | null> = {
  async GET(_req, ctx) {
    const id = ctx.params.id;
    const key = ["user", id];
    const user = (await kv.get<User>(key)).value!;
    return new Response(JSON.stringify(user));
  },
  async DELETE(_req, ctx) {
    const id = ctx.params.id;
    const userKey = ["user", id];
    const userRes = await kv.get(userKey);
    if (!userRes.value) return new Response(`no user with id ${id} found`);
    const ok = await kv.atomic().check(userRes).delete(userKey).commit();
    if (!ok) throw new Error("Something went wrong.");
    return new Response(`user ${id} deleted`);
  },
  async PUT(req, ctx) {
    const id = ctx.params.id;
    const user = (await req.json()) as User;
    const userKey = ["user", id];
    const userRes = await kv.get(userKey);
    if (!userRes.value) return new Response(`no user with id ${id} found`);
    const ok = await kv.atomic().check(userRes).set(userKey, user).commit();
    if (!ok) throw new Error("Something went wrong.");
    return new Response(JSON.stringify(user));
  },
};
```

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

### Configure server port in main.ts

Source: https://usefresh.dev/docs/1.x/getting-started/running-locally

Modify the start function configuration in main.ts to set a custom port.

```typescript
await start(manifest, { server: { port: 3000 } });
```

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

### Implement a server-side search form

Source: https://usefresh.dev/docs/1.x/getting-started/form-submissions

Uses a GET handler to process search queries from URL parameters and filter data before rendering the page.

```typescript
import { Handlers, PageProps } from "$fresh/server.ts";

const NAMES = ["Alice", "Bob", "Charlie", "Dave", "Eve", "Frank"];

interface Data {
  results: string[];
  query: string;
}

export const handler: Handlers<Data> = {
  GET(req, ctx) {
    const url = new URL(req.url);
    const query = url.searchParams.get("q") || "";
    const results = NAMES.filter((name) => name.includes(query));
    return ctx.render({ results, query });
  },
};

export default function Page({ data }: PageProps<Data>) {
  const { results, query } = data;
  return (
    <div>
      <form>
        <input type="text" name="q" value={query} class="border p-1" />
        <button type="submit" class="ml-1 px-2 py-1 bg-gray-100 border">
          Search
        </button>
      </form>
      <ul>
        {results.map((name) => <li key={name}>{name}</li>)}
      </ul>
    </div>
  );
}
```

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

### Initialize project from local source

Source: https://usefresh.dev/docs/1.x/examples/using-fresh-canary-version

Run the initialization script directly from a local Fresh source directory.

```bash
deno run -A -r ./init/src/init.ts
```

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

### Initialize project with JSR

Source: https://usefresh.dev/docs/1.x/examples/using-fresh-canary-version

Create a new Fresh project using a specific alpha version from JSR.

```bash
deno run -A -r jsr:@fresh/init@2.0.0-alpha.35
```

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

### Run server manually with Deno

Source: https://usefresh.dev/docs/1.x/getting-started/running-locally

Execute the main entry point with necessary permissions and watch flags for development.

```bash
$ deno run --allow-net --allow-read --allow-env --allow-run --watch=static/,routes/ main.ts
Watcher Process started.
 🍋 Fresh ready
     Local: http://localhost:3000
```

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

### Default Fresh project structure

Source: https://usefresh.dev/docs/1.x/examples/changing-the-src-dir

The standard file layout generated when initializing a new Fresh project.

```text
<project root>
├── README.md
├── components
│   └── Button.tsx
├── deno.json
├── dev.ts
├── fresh.gen.ts
├── islands
│   └── Counter.tsx
├── main.ts
├── routes
│   ├── greet
│   │   ├── [name].tsx
│   ├── api
│   │   └── joke.ts
│   ├── _404.tsx
│   └── index.tsx
└── static
    ├── favicon.ico
    └── logo.svg
```

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

### Use shared cart islands

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

Example of placing the shared cart islands in a page.

```tsx
<AddToCart product="Lemon" />
<AddToCart product="Lime" />
<Cart />
```

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

### Register plugins

Source: https://usefresh.dev/docs/1.x/concepts/server-configuration

Loads plugins into the Fresh application during startup.

```typescript
await start(manifest, { plugins: [twindPlugin(twindConfig)] });
```

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

### Create a Dockerfile for Fresh

Source: https://usefresh.dev/docs/1.x/concepts/deployment

A standard Dockerfile configuration for a Fresh project, requiring the GIT_REVISION build argument to set the deployment ID.

```dockerfile
FROM denoland/deno:1.38.3

ARG GIT_REVISION
ENV DENO_DEPLOYMENT_ID=${GIT_REVISION}

WORKDIR /app

COPY . .
RUN deno cache main.ts

EXPOSE 8000

CMD ["run", "-A", "main.ts"]
```

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

### Implement GET handler

Source: https://usefresh.dev/docs/1.x/examples/creating-a-crud-api

Retrieves a user resource from the KV store based on the ID parameter.

```typescript
export const handler: Handlers<User | null> = {
  async GET(_req, ctx) {
    const id = ctx.params.id;
    const key = ["user", id];
    const user = (await kv.get<User>(key)).value!;
    return new Response(JSON.stringify(user));
  },
};
```

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

### Run optimized build commands

Source: https://usefresh.dev/docs/1.x/concepts/ahead-of-time-builds

Commands to trigger the Fresh build process for asset optimization.

```bash
# As a task in newer Fresh projects
deno task build
# or invoke it manually
deno run -A dev.ts build
```

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

### Configure development entry point

Source: https://usefresh.dev/docs/1.x/concepts/ahead-of-time-builds

Use the shared configuration within the development script.

```typescript
import dev from "$fresh/dev.ts";
import config from "./fresh.config.ts";

await dev(import.meta.url, "./main.ts", config);
```

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

### Create Self-Contained Executable

Source: https://usefresh.dev/docs/1.x/concepts/deployment

Commands to build the project and compile it into a standalone executable including static assets and configuration files.

```bash
$ deno task build
$ deno compile --include static --include _fresh --include deno.json -A main.ts
```

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

### Configure Fresh server options

Source: https://usefresh.dev/docs/1.x/concepts/server-configuration

Defines the available parameters for the server configuration object, including TLS certificates, network settings, and lifecycle hooks.

```typescript
server: {
  /** Server private key in PEM format */
  cert: string;

  /** Cert chain in PEM format */
  key: string;

  /** The port to listen on.
   *
   * @default {8000} */
  port?: number;

  /** A literal IP address or host name that can be resolved to an IP address.
   *
   * __Note about `0.0.0.0`__ While listening `0.0.0.0` works on all platforms,
   * the browsers on Windows don't work with the address `0.0.0.0`.
   * You should show the message like `server running on localhost:8080` instead of
   * `server running on 0.0.0.0:8080` if your program supports Windows.
   *
   * @default {"0.0.0.0"} */
  hostname?: string;

  /** An {@linkcode AbortSignal} to close the server and all connections. */
  signal?: AbortSignal;

  /** Sets `SO_REUSEPORT` on POSIX systems. */
  reusePort?: boolean;

  /** The handler to invoke when route handlers throw an error. */
  onError?: (error: unknown) => Response | Promise<Response>;

  /** The callback which is called when the server starts listening. */
  onListen?: (params: { hostname: string; port: number }) => void;
}
```

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

### Run tests command

Source: https://usefresh.dev/docs/1.x/examples/writing-tests

Execute tests using the Deno CLI with necessary permissions.

```bash
$ deno test --allow-read --allow-env --allow-net
running 1 test from ./tests/main_test.ts
HTTP assert test. ...
  #1 GET / ... ok (31ms)
  #2 POST / ... ok (35ms)
  #3 GET /foo ... ok (12ms)
HTTP assert test. ... ok (118ms)

ok | 1 passed (3 steps) | 0 failed (236ms)
```

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

### Default Fresh main.ts

Source: https://usefresh.dev/docs/1.x/examples/using-twind-v1

The standard entry point generated when initializing a new Fresh project.

```typescript
/// <reference no-default-lib="true" />
/// <reference lib="dom" />
/// <reference lib="dom.iterable" />
/// <reference lib="dom.asynciterable" />
/// <reference lib="deno.ns" />

import "$std/dotenv/load.ts";

import { start } from "$fresh/server.ts";
import manifest from "./fresh.gen.ts";
import config from "./fresh.config.ts";

await start(manifest, config);
```

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

### Run the Fresh auto updater

Source: https://usefresh.dev/docs/1.x/concepts/updating

Execute this command from the project root to automatically update dependencies and apply recommended code mods.

```bash
$ deno run -A -r https://usefresh.dev/update
```

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

### Define a plugin with routes and middlewares

Source: https://usefresh.dev/docs/1.x/concepts/plugins

Demonstrates how to structure a plugin that registers custom routes and multiple middleware handlers using the Plugin interface.

```typescript
import { MiddlewareHandlerContext, Plugin } from "$fresh/server.ts";
import { handler as testMiddleware } from "./sample_routes/_middleware.ts";
import { SimpleRoute } from "./sample_routes/simple-route.tsx";
export type { Options };

interface Options {
  title: string;
}
export type PluginMiddlewareState = {
  num: number;
  test: string;
};

const twoPointlessMiddlewares = [
  async (
    _req: Request,
    ctx: MiddlewareHandlerContext<PluginMiddlewareState>,
  ) => {
    ctx.state.num = ctx.state.num === undefined ? 1 : ctx.state.num + 1;
    return await ctx.next();
  },
  async (
    _req: Request,
    ctx: MiddlewareHandlerContext<PluginMiddlewareState>,
  ) => {
    ctx.state.num = ctx.state.num === undefined ? 1 : ctx.state.num + 1;
    return await ctx.next();
  },
];

export default function routePlugin(
  options: Options,
): Plugin<PluginMiddlewareState> {
  return {
    name: "routePlugin",
    middlewares: [{
      middleware: { handler: testMiddleware },
      path: "/",
    }, {
      middleware: {
        handler: twoPointlessMiddlewares,
      },
      path: "lots-of-middleware",
    }],
    routes: [
      { path: "no-leading-slash-here", component: SimpleRoute },
    ],
  };
}
```

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

### Define a basic handler route

Source: https://usefresh.dev/docs/1.x/concepts/routes

Exports a handler object to manage GET requests by returning a plain text response.

```typescript
import { FreshContext, Handlers } from "$fresh/server.ts";

export const handler: Handlers = {
  GET(_req: Request, _ctx: FreshContext) {
    return new Response("Hello World");
  },
};
```

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

### Server lifecycle output logs

Source: https://usefresh.dev/docs/1.x/examples/init-the-server

Expected console output during development, build, and preview stages to verify initialization.

```text
Task start deno run -A --watch=static/,routes/ dev.ts
Watcher Process started.
i'm logged during initialization, and not during handling!
The manifest has been generated for 6 routes and 1 islands.

 🍋 Fresh ready
    Local: http://localhost:8000/
```

```text
i'm logged during a request!
Context { complicatedStartupValue: 42 }
```

```text
Task build deno run -A dev.ts build
i'm logged during initialization, and not during handling!
The manifest has been generated for 6 routes and 1 islands.
Assets written to: /path/to/my/project/_fresh
```

```text
Task preview deno run -A main.ts
i'm logged during initialization, and not during handling!
Using snapshot found at /Users/reed/code/temp/1763/_fresh

 🍋 Fresh ready
    Local: http://localhost:8000/
```

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

### Define Fresh configuration

Source: https://usefresh.dev/docs/1.x/concepts/ahead-of-time-builds

Extract plugins into a central configuration file for consistent access across scripts.

```typescript
import { defineConfig } from "$fresh/server.ts";
import twindPlugin from "$fresh/plugins/twind.ts";
import twindConfig from "./twind.config.ts";

export default defineConfig({
  plugins: [twindPlugin(twindConfig)],
});
```

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

### Modify fresh.config.ts for initialization

Source: https://usefresh.dev/docs/1.x/examples/init-the-server

Shows the necessary imports and the await call to initialize the context within the configuration file.

```typescript
 import twindConfig from "./twind.config.ts";
+import { Context } from "./routes/_middleware.ts";
+
+await Context.init();

 export default defineConfig({
   plugins: [twindPlugin(twindConfig)],
```

```typescript
import { defineConfig } from "$fresh/server.ts";
import twindPlugin from "$fresh/plugins/twind.ts";
import twindConfig from "./twind.config.ts";
import { Context } from "./routes/_middleware.ts";

await Context.init();

export default defineConfig({
  plugins: [twindPlugin(twindConfig)],
});
```

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

### Asynchronous route data fetching

Source: https://usefresh.dev/docs/1.x/concepts/data-fetching

A shortcut for simple GET requests where the route function itself is defined as async, returning the rendered component directly.

```typescript
interface Project {
  name: string;
  stars: number;
}

export default async function ProjectPage(_req, ctx: FreshContext) {
  const project: Project | null = await db.projects.findOne({
    id: ctx.params.id,
  });

  if (!project) {
    return <h1>Project not found</h1>;
  }

  return (
    <div>
      <h1>{project.name}</h1>
      <p>{project.stars} stars</p>
    </div>
  );
}
```

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

### Route Group Layout Structure

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

Demonstrates the directory structure for applying different layouts to grouped routes using parentheses.

```text
└── <root>/routes
    ├── (marketing)
    │   ├── _layout.tsx  # only applies to about.tsx and career.tsx
    │   ├── about.tsx
    │   └── career.tsx
    └── (info)
        ├── _layout.tsx  # only applies to archive.tsx and contact.tsx
        ├── archive.tsx
        └── contact.tsx
```

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

### Build and Run Docker Container

Source: https://usefresh.dev/docs/1.x/concepts/deployment

Commands to build a Docker image with a Git revision tag and execute the container mapping port 80 to 8000.

```bash
$ docker build --build-arg GIT_REVISION=$(git rev-parse HEAD) -t my-fresh-app .
```

```bash
$ docker run -t -i -p 80:8000 my-fresh-app
```

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

### Building a syntax highlighter component

Source: https://usefresh.dev/docs/1.x/examples/rendering-raw-html

Demonstrates using dangerouslySetInnerHTML to render HTML generated by a syntax highlighter library like PrismJS.

```tsx
import Prism from "https://esm.sh/prismjs@1.29.0";

interface Props {
  code: string;
  lang: string;
}

export default function Code({ code, lang }: Props) {
  const parsed = Prism.highlight(code, Prism.languages[lang], lang);

  return (
    <pre data-lang={lang} className={`language-${lang}`}>
      <code
        dangerouslySetInnerHTML={{
          __html: parsed,
        }}
      />
    </pre>
  );
}
```

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

### Create styles.css

Source: https://usefresh.dev/docs/1.x/examples/migrating-to-tailwind

Define the base CSS file with Tailwind directives.

```css
@tailwind base;
@tailwind components;
@tailwind utilities;
```

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

### Define the FreshConfig interface

Source: https://usefresh.dev/docs/1.x/concepts/server-configuration

The main configuration object for customizing build, rendering, plugins, static directories, routing, and server options.

```typescript
export interface FreshConfig {
  build?: {
    /**
     * The directory to write generated files to when `dev.ts build` is run.
     * This can be an absolute path, a file URL or a relative path.
     */
    outDir?: string;
    /**
     * This sets the target environment for the generated code. Newer
     * language constructs will be transformed to match the specified
     * support range. See https://esbuild.github.io/api/#target
     * @default {"es2022"}
     */
    target?: string | string[];
  };
  render?: RenderFunction;
  plugins?: Plugin[];
  staticDir?: string;
  router?: RouterOptions;
  server?: Partial<Deno.ServeTlsOptions>;
}
```

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

### Update to latest alpha version

Source: https://usefresh.dev/docs/1.x/examples/using-fresh-canary-version

Use the update command to automatically set the project to the latest Fresh 2 alpha version.

```bash
deno run -A -r jsr:@fresh/update@2.0.0-alpha.35 .
```

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

### Implement dynamic markdown rendering in a Fresh route

Source: https://usefresh.dev/docs/1.x/examples/rendering-markdown

Uses a dynamic route handler to fetch or read markdown content and render it using the @deno/gfm library.

```typescript
import { Handlers, PageProps } from "$fresh/server.ts";
import { extract } from "$std/front_matter/yaml.ts";
import { CSS, render } from "$gfm";
import { Head } from "$fresh/runtime.ts";

interface Page {
  markdown: string;
  data: Record<string, unknown>;
}

export const handler: Handlers<Page> = {
  async GET(_req, ctx) {
    let rawMarkdown = "";
    if (ctx.params.slug === "remote") {
      const resp = await fetch(
        `https://raw.githubusercontent.com/denoland/fresh/main/docs/latest/introduction/index.md`,
      );
      if (resp.status !== 200) {
        return ctx.render(undefined);
      }
      rawMarkdown = await resp.text();
    } else if (ctx.params.slug === "string") {
      rawMarkdown = `---
description: test
---

## big text

Look, it's working. _This is in italics._
      
      `;
    } else if (ctx.params.slug === "file") {
      rawMarkdown = await Deno.readTextFile("text.md");
    } else {
      return ctx.render(undefined);
    }
    const { attrs, body } = extract(rawMarkdown);
    return ctx.render({ markdown: body, data: attrs });
  },
};

export default function MarkdownPage({ data }: PageProps<Page | null>) {
  if (!data) {
    return <h1>File not found.</h1>;
  }

  return (
    <>
      <Head>
        <style dangerouslySetInnerHTML={{ __html: CSS }} />
      </Head>
      <main>
        <div>{JSON.stringify(data.data)}</div>
        <div
          class="markdown-body"
          dangerouslySetInnerHTML={{ __html: render(data?.markdown) }}
        />
      </main>
    </>
  );
}
```

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

### Co-location Directory Structure

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

Shows how to use underscore-prefixed folders to store private components and islands within route groups.

```text
└── <root>/routes
    ├── (marketing)
    │   ├── _layout.tsx
    │   ├── about.tsx
    │   ├── career.tsx
    │   ├── (_components)
    │   │   └── newsletter-cta.tsx
    │   └── (_islands)
    │       └── interactive-stats.tsx # Fresh treats this as an island
    └── shop
        ├── (_components)
        │   └── product-card.tsx
        └── (_islands)
            └── cart.tsx # Fresh treats this as an island
```

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

### Write HTTP tests

Source: https://usefresh.dev/docs/1.x/examples/writing-tests

Use createHandler to instantiate the application and perform assertions on HTTP responses.

```typescript
import { createHandler, ServeHandlerInfo } from "$fresh/server.ts";
import manifest from "../fresh.gen.ts";
import config from "../fresh.config.ts";
import { assert, assertEquals } from "$std/testing/asserts.ts";

const CONN_INFO: ServeHandlerInfo = {
  remoteAddr: { hostname: "127.0.0.1", port: 53496, transport: "tcp" },
};

Deno.test("HTTP assert test.", async (t) => {
  const handler = await createHandler(manifest, config);

  await t.step("#1 GET /", async () => {
    const resp = await handler(new Request("http://127.0.0.1/"), CONN_INFO);
    assertEquals(resp.status, 200);
  });

  await t.step("#2 POST /", async () => {
    const formData = new FormData();
    formData.append("text", "Deno!");
    const req = new Request("http://127.0.0.1/", {
      method: "POST",
      body: formData,
    });
    const resp = await handler(req, CONN_INFO);
    assertEquals(resp.status, 303);
  });

  await t.step("#3 GET /foo", async () => {
    const resp = await handler(new Request("http://127.0.0.1/foo"), CONN_INFO);
    const text = await resp.text();
    assert(text.includes("<div>Hello Foo!</div>"));
  });
});
```

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

### Base path link transformation

Source: https://usefresh.dev/docs/1.x/concepts/server-configuration

Demonstrates how absolute links are automatically prefixed with the configured basePath.

```html
<a href="/about">About</a>;
```

```html
<a href="/foo/bar/about">About</a>
```

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

### Project Directory Structure for Layouts

Source: https://usefresh.dev/docs/1.x/concepts/layouts

Visual representation of how _layout.tsx files are organized within the routes directory.

```text
<project root>
└── routes
    ├── sub
    │   ├── page.tsx
    │   └── index.tsx
    ├── other
    │   ├── _layout.tsx  # will be applied on top of `routes/_layout.tsx`
    │   └── page.tsx
    ├── _layout.tsx  # will be applied to all routes
    └── _app.tsx
```

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

### Enable Partials in _app.tsx

Source: https://usefresh.dev/docs/1.x/concepts/partials

Add the f-client-nav attribute to the body and wrap content with the Partial component to enable partial navigation globally.

```tsx
  import { PageProps } from "$fresh/server.ts";
+ import { Partial } from "$fresh/runtime.ts";

  export default function App({ Component }: PageProps) {
    return (
      <html>
        <head>
          <meta charset="utf-8" />
          <meta name="viewport" content="width=device-width, initial-scale=1.0" />
          <title>My Fresh app</title>
        </head>
-       <body>
+       <body f-client-nav>
+         <Partial name="body">
            <Component />
+         </Partial>
        </body>
      </html>
    );
  }
```

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

### Define a basic component route

Source: https://usefresh.dev/docs/1.x/concepts/routes

Uses a default export component to render HTML. If no handler is defined, Fresh uses a default handler to render the component.

```typescript
import { PageProps } from "$fresh/server.ts";

export default function Page(props: PageProps) {
  return <div>You are on the page '{props.url.href}'.</div>;
}
```

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

### Async Layout with defineLayout Helper

Source: https://usefresh.dev/docs/1.x/concepts/layouts

Simplified async layout definition using the defineLayout helper for automatic type inference.

```typescript
import { defineLayout } from "$fresh/server.ts";

export default defineLayout(async (req, ctx) => {
  const data = await loadData();

  return (
    <div class="layout">
      <p>{data.greeting}</p>
      <ctx.Component />
    </div>
  );
});
```

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

### Use an Island in a Page

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

Import and use an island component like a standard Preact component; Fresh handles client-side hydration automatically.

```typescript
import MyIsland from "../islands/my-island.tsx";

export default function Home() {
  return <MyIsland />;
}
```

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

### Update deno.json

Source: https://usefresh.dev/docs/1.x/examples/migrating-to-tailwind

Configure imports and nodeModulesDir for Tailwind CSS support.

```json
  {
+   "nodeModulesDir": "manual",
    "imports": {
      "$fresh/": "https://deno.land/x/fresh@1.5.2/",
      "preact": "https://esm.sh/preact@10.22.0",
      "preact/": "https://esm.sh/preact@10.22.0/",
-     "twind": "https://esm.sh/twind@0.16.19",
-     "twind/": "https://esm.sh/twind@0.16.19/"
+     "tailwindcss": "npm:tailwindcss@3.4.1"
    }
  }
```

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

### Configure build output directory

Source: https://usefresh.dev/docs/1.x/concepts/server-configuration

Sets the output directory for generated files using the dev configuration.

```typescript
await dev(import.meta.url, "./main.ts", {
  build: {
    outDir: Deno.env.get("FRESH_TEST_OUTDIR") ?? undefined,
  },
});
```

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

### Implement a middleware handler

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

A basic middleware implementation that logs the destination and URL of incoming requests.

```typescript
import { FreshContext } from "$fresh/server.ts";

export async function handler(req: Request, ctx: FreshContext) {
  console.log(ctx.destination);
  console.log(req.url);
  const resp = await ctx.next();
  return resp;
}
```

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

### Register plugin islands

Source: https://usefresh.dev/docs/1.x/concepts/plugins

Shows how to expose island components from a plugin by specifying their file paths relative to the plugin location.

```typescript
import { Plugin } from "$fresh/server.ts";

export default function myIslandPlugin(): Plugin {
  return {
    name: "my-island-plugin",
    islands: {
      baseLocation: import.meta.url,
      paths: [
        "./plugin/MyPluginIsland.tsx",
        "./plugin/OtherPluginIsland.tsx",
      ],
    },
  };
}
```

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

### Configure forked Fresh in deno.json

Source: https://usefresh.dev/docs/1.x/examples/using-fresh-canary-version

Update the imports map to point to a custom branch of a forked Fresh repository.

```json
   "tasks": {
     "update": "deno run -A -r jsr:@fresh/update ."
   },
   "imports": {
-    "$fresh/": "https://deno.land/x/fresh@1.7.3/",
+    "$fresh/": "https://raw.githubusercontent.com/your-username/fresh/your-branch/",
     "preact": "https://esm.sh/preact@10.26.9",
     "preact/": "https://esm.sh/preact@10.22.0/",
   }
```

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

### Define an async app wrapper with defineApp

Source: https://usefresh.dev/docs/1.x/concepts/app-wrapper

Use the defineApp helper to automatically infer types for the async app wrapper function.

```typescript
import { defineApp } from "$fresh/server.ts";

export default defineApp(async (req, ctx) => {
  const data = await loadData();

  return (
    <html>
      <head>
        <meta charset="utf-8" />
        <meta name="viewport" content="width=device-width, initial-scale=1.0" />
        <title>My Fresh app</title>
      </head>
      <body>
        <h1>Hello {data.name}</h1>
        <ctx.Component />
      </body>
    </html>
  );
});
```

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

### Integrate Leaflet with Fresh using Context

Source: https://usefresh.dev/docs/1.x/examples/client-side-components-and-libraries

Uses a provider component to load Leaflet CSS and JS on the client, exposing the library instance through a context for child components.

```typescript
import * as Leaflet from "https://esm.sh/v135/@types/leaflet@1.9.4/index.d.ts";
import { IS_BROWSER } from "$fresh/runtime.ts";
import { useContext, useEffect } from "preact/hooks";
import { ComponentChildren, createContext } from "preact";
import { useSignal } from "@preact/signals";

// Create a context to hold Leaflet data/functions
const LeafletContext = createContext<typeof Leaflet | null>(null);

// LeafletProvider component manages Leaflet loading and context
function LeafletProvider(props: { children: ComponentChildren }) {
  if (!IS_BROWSER) {
    return <p>Leaflet must be loaded on the client. No children will render</p>;
  }
  const value = useSignal<typeof Leaflet | null>(null);
  return (
    <>
      {/* Load Leaflet CSS */}
      <link
        rel="stylesheet"
        href="https://unpkg.com/leaflet@1.9.4/dist/leaflet.css"
        integrity="sha256-p4NxAoJBhIIN+hmNHrzRCf9tD/miZyoHS5obTRR9BMY="
        crossorigin=""
      />
      {/* Load Leaflet JS */}
      <script
        onLoad={() => value.value = window.L}
        src="https://unpkg.com/leaflet@1.9.4/dist/leaflet.js"
        integrity="sha256-20nQCchB9co0qIjJZRGuk2/Z9VM+kNiyxNV1lvTlZBo="
        crossorigin=""
      />
      {/* Provide Leaflet context to children */}
      <LeafletContext.Provider value={value}>
        {props.children}
      </LeafletContext.Provider>
    </>
  );
}

// MapComponent utilizes Leaflet context for rendering the map
function MapComponent() {
  const leaf = useContext(LeafletContext);
  if (!leaf) return <div>Component placeholder</div>;
  useEffect(() => {
    const map = leaf.map("map").setView(leaf.latLng(0, 0), 2);
    leaf.tileLayer("https://tile.openstreetmap.org/{z}/{x}/{y}.png", {
      attribution:
        '&copy; <a href="https://www.openstreetmap.org/copyright">OpenStreetMap</a> contributors',
    }).addTo(map);
  });
  return <div id="map" class="relative w-[80vw] h-[50vh]" />;
}

// MapIsland is the parent component integrating LeafletProvider and MapComponent
export default function MapIsland() {
  return (
    <LeafletProvider>
      <MapComponent />
    </LeafletProvider>
  );
}
```

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

### Create an API route handler

Source: https://usefresh.dev/docs/1.x/getting-started/custom-handlers

Shows how to return a JSON response without rendering a page component, useful for API endpoints.

```typescript
import { Handlers } from "$fresh/server.ts";

export const handler: Handlers = {
  GET(_req) {
    const uuid = crypto.randomUUID();
    return new Response(JSON.stringify(uuid), {
      headers: { "Content-Type": "application/json" },
    });
  },
};
```

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

### Update Fresh configuration for Twind v1

Source: https://usefresh.dev/docs/1.x/examples/using-twind-v1

Diff showing the change required in fresh.config.ts to use the twindv1 plugin.

```diff
 import { defineConfig } from "$fresh/server.ts";
-import twindPlugin from "$fresh/plugins/twind.ts";
+import twindPlugin from "$fresh/plugins/twindv1.ts";
 import twindConfig from "./twind.config.ts";

 export default defineConfig({
```

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

### Define a basic Fresh plugin

Source: https://usefresh.dev/docs/1.x/concepts/plugins

Create a plugin object conforming to the Plugin interface with a required name property.

```typescript
import { Plugin } from "$fresh/server.ts";

const plugin: Plugin = {
  name: "my_plugin",
};
```

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

### Configure .gitignore for build artifacts

Source: https://usefresh.dev/docs/1.x/concepts/ahead-of-time-builds

Exclude the generated _fresh directory from version control.

```text
# Ignore fresh build directory
_fresh/
```

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

### Apply f-partial to Sidebar Links

Source: https://usefresh.dev/docs/1.x/concepts/partials

Update sidebar links to use the optimized partial route for content fetching.

```tsx
  <aside>
-   <a href="/docs/page1">Page 1</a>
-   <a href="/docs/page2">Page 2</a>
+   <a href="/docs/page1" f-partial="/partials/docs/page1">Page 1</a>
+   <a href="/docs/page2" f-partial="/partials/docs/page2">Page 2</a>
  </aside>
```

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

### Use defineRoute helper

Source: https://usefresh.dev/docs/1.x/concepts/routes

Simplifies async route definition by automatically inferring types for function arguments.

```typescript
import { defineRoute } from "$fresh/server.ts";

export default defineRoute(async (req, ctx) => {
  const data = await loadData();

  return (
    <div class="page">
      <h1>Hello {data.name}</h1>
    </div>
  );
});
```

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

### Define multiple middlewares in one file

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

Export an array of handler functions to execute multiple middlewares sequentially for the same route.

```typescript
export const handler = [
  async function middleware1(req, ctx) {
    // do something
    return ctx.next();
  },
  async function middleware2(req, ctx) {
    // do something
    return ctx.next();
  },
];
```

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

### Create a custom 404 page

Source: https://usefresh.dev/docs/1.x/concepts/error-pages

Define a default export component in _404.tsx to handle unmatched routes.

```typescript
import { PageProps } from "$fresh/server.ts";

export default function NotFoundPage({ url }: PageProps) {
  return <p>404 not found: {url.pathname}</p>;
}
```

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

### Define an about page route

Source: https://usefresh.dev/docs/1.x/getting-started/create-a-route

Create a new file at routes/about.tsx to handle requests to the /about path by exporting a default Preact component.

```tsx
export default function AboutPage() {
  return (
    <main>
      <h1>About</h1>
      <p>This is the about page.</p>
    </main>
  );
}
```

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

### Define a synchronous app wrapper

Source: https://usefresh.dev/docs/1.x/concepts/app-wrapper

Create a default export component in _app.tsx to serve as the outer HTML structure. State set by middleware is accessible via props.

```typescript
import { PageProps } from "$fresh/server.ts";

export default function App({ Component, state }: PageProps) {
  // do something with state here
  return (
    <html>
      <head>
        <meta charset="utf-8" />
        <meta name="viewport" content="width=device-width, initial-scale=1.0" />
        <title>My Fresh app</title>
      </head>
      <body>
        <Component />
      </body>
    </html>
  );
}
```

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

### createHandler and FreshConfig definitions

Source: https://usefresh.dev/docs/1.x/examples/writing-tests

Type definitions for the createHandler function and the FreshConfig interface.

```typescript
export async function createHandler(
  manifest: Manifest,
  config: FreshConfig = {},
): Promise<
  (req: Request, connInfo?: ServeHandlerInfo) => Promise<Response>
```

```typescript
export interface FreshConfig {
  build?: {
    outDir?: string;
    target?: string | string[];
  };
  render?: RenderFunction;
  plugins?: Plugin[];
  staticDir?: string;
  router?: RouterOptions;
  server?: Partial<Deno.ServeTlsOptions>;
}
```

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

### Define a basic middleware handler

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

Use the FreshContext to set state and modify response headers before calling the next handler.

```typescript
import { FreshContext } from "$fresh/server.ts";

interface State {
  data: string;
}

export async function handler(
  req: Request,
  ctx: FreshContext<State>,
) {
  ctx.state.data = "myData";
  const resp = await ctx.next();
  resp.headers.set("server", "fresh server");
  return resp;
}
```

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

### Restructured project with src directory

Source: https://usefresh.dev/docs/1.x/examples/changing-the-src-dir

The resulting file structure after moving project files into the src directory.

```text
<project root>
├── README.md
├── deno.json
└── src
    ├── components
    │   └── Button.tsx
    ├── dev.ts
    ├── fresh.gen.ts
    ├── islands
    │   └── Counter.tsx
    ├── main.ts
    ├── routes
    │   ├── greet
    │   │   ├── [name].tsx
    │   ├── api
    │   │   └── joke.ts
    │   ├── _404.tsx
    │   └── index.tsx
    └── static
        ├── favicon.ico
        └── logo.svg
```

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

### Set static directory

Source: https://usefresh.dev/docs/1.x/concepts/server-configuration

Defines the directory where static assets are stored.

```typescript
await start(manifest, { staticDir: "./custom_static" });
```