CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

This is a Val Town project - a full-stack web application combining React frontend with Hono backend, designed for Val Town's Deno-based serverless platform.

├── backend/
│   └── server.ts         # Hono HTTP server with API routes
├── frontend/
│   ├── index.html        # HTML entry point
│   └── app.tsx           # React application component
├── deno.json            # Deno configuration
└── .cursorrules         # Val Town development guidelines

• Runtime: Deno (not Node.js)
• Backend: Hono web framework serving HTTP requests
• Frontend: React 18.2.0 from ESM.sh CDN
• Modules: ESM imports from esm.sh and esm.town
• Platform: Val Town serverless environment

Uses Val Town's serveFile utility for proper content-type handling:

Create val
import { serveFile } from "https://esm.town/v/std/utils@85-main/index.ts";
app.get("/frontend/**/*", c => serveFile(c.req.path, import.meta.url));

All React files must include JSX pragma and use pinned versions:

Create val
/** @jsxImportSource https://esm.sh/react@18.2.0 */
import React from "https://esm.sh/react@18";

Include error unwrapping for proper debugging:

Create val
app.onError((err, c) => {
  throw err;
});

HTTP vals must export the fetch handler:

Create val
export default app.fetch;

No traditional build commands - code runs directly on Val Town's platform. Files are served and executed as-is.

• Lint code: deno lint - Check for code quality issues
• Type check: deno check backend/server.ts - Verify TypeScript types

• No binary files - text-only file system
• ESM modules only - no Node.js compatibility required
• CDN dependencies - external module loading from esm.sh
• Serverless limitations - stateless request handling only

Key utilities available:

• Blob storage: import { blob } from "https://esm.town/v/std/blob"
• SQLite: import { sqlite } from "https://esm.town/v/stevekrouse/sqlite"
• OpenAI: import { OpenAI } from "https://esm.town/v/std/openai"
• Email: import { email } from "https://esm.town/v/std/email"

1. Always pin React to 18.2.0 across all dependencies
2. Use npm: prefix for npm imports in server-side code only
3. Use esm.sh URLs for client-side imports
4. Include JSX pragma in all TSX files
5. Change SQLite table names instead of altering schemas
6. Use environment variables for secrets via Deno.env.get()
7. Avoid Node.js APIs - stick to Deno and web standards

Simple React counter app demonstrating:

• Hono server with static file serving
• React state management
• API endpoints (/api/health)
• Proper file separation between frontend/backend