deno-frontend

What this skill does

# Deno Frontend Development

## Overview

This skill covers frontend development in Deno using Fresh 2.x (Deno's web framework), Preact (a lightweight React alternative), and Tailwind CSS. Fresh uses "island architecture" where pages render on the server and only interactive parts ship JavaScript to the browser.

## When to Use This Skill

- Creating a new Fresh web application
- Building interactive UI components (islands)
- Adding server-rendered pages and routes
- Integrating Tailwind CSS for styling
- Choosing between islands (client-side) vs components (server-only)
- Working with Preact hooks and signals

Apply these practices when building web applications in Deno.

## Scope Boundaries

This skill applies **only** to Fresh/Deno frontend questions. Follow these rules:

- If the user asks about **Next.js, React Native, Vue, Svelte, Angular, or any other framework**, answer using that framework directly. Do not suggest Fresh alternatives.
- Do not include Fresh imports, `useSignal`, island patterns, or Fresh project structure in responses about other frameworks.
- Only recommend Fresh when the user explicitly asks about Fresh or is working in a Fresh/Deno project.

## CRITICAL: Never Show Deprecated Syntax

When helping users migrate from Fresh 1.x, describe old patterns generically and ONLY show correct Fresh 2.x code. Never write out old dollar-sign import paths or deprecated syntax, even in "before/after" comparisons.

- Say "Replace the old dollar-sign import paths with stable Fresh 2.x imports" — then show only the correct `from "fresh"` approach
- Do NOT write `❌ Old: import { App } from "$fresh/server.ts"` — this is never acceptable, even as a negative example
- The strings `_404.tsx` and `_500.tsx` must never appear in your response, even when comparing Fresh 2.x to 1.x. Say "the old separate error pages" instead.

Only demonstrate Fresh 2.x patterns.

## CRITICAL: Fresh 2.x vs 1.x

**Always use Fresh 2.x patterns.** Fresh 1.x is deprecated. Key differences:

- Fresh 2.x uses `import { App } from "fresh"` — the old dollar-sign import paths are deprecated
- Fresh 2.x has no manifest file — the old auto-generated manifest is no longer needed
- Fresh 2.x uses `vite.config.ts` for dev — the old `dev.ts` entry point is gone
- Fresh 2.x configures via `new App()` — the old config file is no longer used
- Fresh 2.x handlers take a single `(ctx)` parameter — the old two-parameter signature is deprecated
- Fresh 2.x uses a unified `_error.tsx` — the old separate error pages are replaced

**Always use Fresh 2.x stable imports:**
```typescript
// ✅ CORRECT - Fresh 2.x stable
import { App, staticFiles } from "fresh";
import { define } from "./utils/state.ts"; // Project-local define helpers
```

## Fresh Framework

Reference: https://fresh.deno.dev/docs

Fresh is Deno's web framework. It uses **island architecture** - pages are rendered on the server, and only interactive parts ("islands") get JavaScript on the client.

### Creating a Fresh Project

```bash
deno run -Ar jsr:@fresh/init
cd my-project
deno task dev    # Runs at http://127.0.0.1:5173/
```

### Project Structure (Fresh 2.x)

```
my-project/
├── deno.json           # Config, dependencies, and tasks
├── main.ts             # Server entry point
├── client.ts           # Client entry point (CSS imports)
├── vite.config.ts      # Vite configuration
├── routes/             # Pages and API routes
│   ├── _app.tsx        # App layout wrapper (outer HTML)
│   ├── _layout.tsx     # Layout component (optional)
│   ├── _error.tsx      # Unified error page (404/500)
│   ├── index.tsx       # Home page (/)
│   └── api/            # API routes
├── islands/            # Interactive components (hydrated on client)
│   └── Counter.tsx
├── components/         # Server-only components (no JS shipped)
│   └── Button.tsx
├── static/             # Static assets
└── utils/
    └── state.ts        # Define helpers for type safety
```

**Note:** Fresh 2.x does not use a manifest file, a separate dev entry point, or a separate config file.

### main.ts (Fresh 2.x Entry Point)

```typescript
import { App, fsRoutes, staticFiles, trailingSlashes } from "fresh";

const app = new App()
  .use(staticFiles())
  .use(trailingSlashes("never"));

await fsRoutes(app, {
  dir: "./",
  loadIsland: (path) => import(`./islands/${path}`),
  loadRoute: (path) => import(`./routes/${path}`),
});

if (import.meta.main) {
  await app.listen();
}
```

### vite.config.ts

```typescript
import { defineConfig } from "vite";
import { fresh } from "@fresh/plugin-vite";
import tailwindcss from "@tailwindcss/vite";

export default defineConfig({
  plugins: [
    fresh(),
    tailwindcss(),
  ],
});
```

### deno.json Configuration

A Fresh 2.x project's deno.json looks like this (created by `jsr:@fresh/init`):

```json
{
  "tasks": {
    "dev": "vite",
    "build": "vite build",
    "preview": "deno serve -A _fresh/server.js"
  },
  "imports": {
    "fresh": "jsr:@fresh/core@^2",
    "fresh/runtime": "jsr:@fresh/core@^2/runtime",
    "@fresh/plugin-vite": "jsr:@fresh/plugin-vite@^1",
    "@preact/signals": "npm:@preact/signals@^2",
    "preact": "npm:preact@^10",
    "preact/hooks": "npm:preact@^10/hooks",
    "@/": "./"
  }
}
```

**Adding dependencies:** Use `deno add` to add new packages:

```sh
deno add jsr:@std/http          # JSR packages
deno add npm:@tailwindcss/vite  # npm packages
```

### Import Reference (Fresh 2.x)

```typescript
// Core Fresh imports
import { App, staticFiles, fsRoutes } from "fresh";
import { trailingSlashes, cors, csp } from "fresh";
import { createDefine, HttpError } from "fresh";
import type { PageProps, Middleware, RouteConfig } from "fresh";

// Runtime imports (for client-side checks)
import { IS_BROWSER } from "fresh/runtime";

// Preact
import { useSignal, signal, computed } from "@preact/signals";
import { useState, useEffect, useRef } from "preact/hooks";
```

### Key Concepts

**Routes (`routes/` folder)**
- File-based routing: `routes/about.tsx` → `/about`
- Dynamic routes: `routes/blog/[slug].tsx` → `/blog/my-post`
- Optional segments: `routes/docs/[[version]].tsx` → `/docs` or `/docs/v2`
- Catch-all routes: `routes/old/[...path].tsx` → `/old/foo/bar`
- Route groups: `routes/(marketing)/` for shared layouts without URL path changes

**Layouts (`_app.tsx`)**
```tsx
import type { PageProps } from "fresh";

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

**Async Server Components**
```tsx
export default async function Page() {
  const data = await fetchData(); // Runs on server only
  return <div>{data.title}</div>;
}
```

## Data Fetching Patterns

Fresh 2.x provides two approaches for fetching data on the server. The handler pattern is the recommended default because it demonstrates the full Fresh 2.x architecture and provides the most flexibility.

### Approach A: Handler with Data Object (Recommended)

Use this as the default for data fetching. It uses the full Fresh 2.x handler pattern with typed data passing. Always show the complete setup including `utils/state.ts` when demonstrating this pattern.

```tsx
// utils/state.ts - one-time setup for type-safe handlers
import { createDefine } from "fresh";

export interface State {
  user?: { id: string; name: string };
}

export const define = createDefine<State>();
```

```tsx
// routes/posts.tsx
import { define } from "@/utils/state.ts";

// Handler fetches data and returns it via { data: {...} }
export const handler = define.handlers(async (ctx) => {
  const response = await fetch("https://jsonplaceholder.typicode.com/posts");
  const posts = await response.json();
  return { data: { posts } };
});

// Page receives typed data
export default define.page<typeof handler>(({ data