${escapeXml(catTitle(cat))}

wrapping an\n * with:\n * - h3.card-block__title → name\n * - img.card-block__img-animal → photo (src) + alt\n * - span.card-block__label (×N) → \"Female / Spayed\", breed, age\n * - .card-block__location → adoption location\n */\nexport function parseCats(html: string, baseUrl: string): Cat[] {\n const $ = load(html);\n const cats: Cat[] = [];\n\n $(\"article.card-block__item\").each((_, el) => {\n const card = $(el);\n\n const name = clean(card.find(\".card-block__title\").first().text());\n if (!name) return; // skip non-cat / malformed cards\n\n const img = card.find(\"img.card-block__img-animal\").first();\n const rawImg = img.attr(\"src\") ?? null;\n const rawHref = card.find(\"a.card-block__link\").first().attr(\"href\") ?? null;\n\n // Promo/CTA cards reuse the same class but link to general adopt pages and\n // have no animal photo. Real cats always have a petango.com photo.\n const isAnimalCard = !!rawImg && rawImg.includes(\"petango.com\");\n if (!isAnimalCard) return;\n\n // Adoption-pending cats show a name + photo but none of the detail labels.\n const pending = /adoption pending/i.test(card.text());\n\n // The location lives in its own block; grab it first, then exclude it\n // from the generic label list so we don't double-count it.\n const location = clean(card.find(\".card-block__location .card-block__label\").first().text());\n\n // The labels are nested in the PAWS markup: the breed span wraps the age\n // span, so reading breed's full text() also captures the age. To get each\n // field cleanly we read only a node's *own* direct text (excluding children).\n const ownText = (node: ReturnType): string | null =>\n clean(node.clone().children().remove().end().text());\n\n const labelNodes = card.find(\".card-block__main-info .card-block__label\");\n\n // Node 0 = \"Female / Spayed\". Node with own-text = breed. Deepest = age.\n const sexStatus = ownText(labelNodes.eq(0));\n let sex: string | null = null;\n let spayNeuterStatus: string | null = null;\n if (sexStatus) {\n const [s, status] = sexStatus.split(\"/\").map((x) => x.trim());\n sex = s || null;\n spayNeuterStatus = status || null;\n }\n\n // Breed is the own-text of the first label after the sex/status one.\n let breed: string | null = null;\n labelNodes.slice(1).each((_, l) => {\n if (breed) return;\n const t = ownText($(l));\n if (t) breed = t;\n });\n\n // Age is the deepest label (it has no element children, only text).\n let age: string | null = null;\n labelNodes.each((_, l) => {\n const node = $(l);\n if (node.children().length === 0) {\n const t = clean(node.text());\n if (t && t !== sexStatus) age = t;\n }\n });\n\n cats.push({\n name,\n sex,\n spayNeuterStatus,\n breed,\n age,\n location,\n status: pending ? \"adoption_pending\" : \"available\",\n imageUrl: absoluteUrl(rawImg, baseUrl),\n detailUrl: absoluteUrl(rawHref, baseUrl),\n });\n });\n\n return cats;\n}\n\n/** Resolve a possibly-relative URL against the page it came from. */\nfunction absoluteUrl(href: string | null, baseUrl: string): string | null {\n if (!href) return null;\n try {\n return new URL(href, baseUrl).toString();\n } catch {\n return href;\n }\n}\n",[],[180],"cfd02830-5b2c-11f1-84eb-ee650bb23af1","main.ts","10cd18e6-5b2a-11f1-929f-ee650bb23af1",28,["D",1780038344826],7,"http","import { type Cat, LISTING_URL, scrapeCats } from \"./scraper.ts\";\n\n// In-memory cache so repeated requests don't re-scrape the source on every hit.\nconst CACHE_TTL_MS = 5 * 60 * 1000; // 5 minutes\nlet cache: { at: number; cats: Cat[] } | null = null;\n\n/** Response headers that tell feed readers (and any proxies) not to cache. */\nfunction noCacheHeaders(cacheStatus: \"HIT\" | \"MISS\"): HeadersInit {\n return {\n \"Content-Type\": \"application/rss+xml; charset=utf-8\",\n \"Cache-Control\": \"no-store, no-cache, must-revalidate, max-age=0\",\n Pragma: \"no-cache\",\n Expires: \"0\",\n \"X-Cache\": cacheStatus,\n };\n}\n\n/** Path the feed is served from. */\nconst FEED_PATH = \"/feed.xml\";\n\nexport default async function (req: Request): Promise {\n const url = new URL(req.url);\n\n // Only /feed.xml serves the feed; redirect the root for convenience and\n // 404 anything else so the URL space stays predictable.\n if (url.pathname !== FEED_PATH) {\n if (url.pathname === \"/\" || url.pathname === \"\") {\n return new Response(null, {\n status: 302,\n headers: { Location: FEED_PATH + url.search },\n });\n }\n return new Response(\"Not found\", { status: 404 });\n }\n\n // Allow overriding the target URL via ?url=… and bypassing cache via ?fresh=1\n const target = url.searchParams.get(\"url\") ?? LISTING_URL;\n const fresh = url.searchParams.get(\"fresh\") === \"1\";\n const usingCustomUrl = url.searchParams.has(\"url\");\n const sexFilter = parseSexFilter(url.searchParams.get(\"sex\"));\n const kittenOnly = parseBoolFlag(url.searchParams.get(\"kitten\"));\n const filters: Filters = { sex: sexFilter, kittenOnly };\n\n if (url.searchParams.has(\"sex\") && !sexFilter) {\n return Response.json(\n { error: `Invalid sex filter; expected \"male\" or \"female\".` },\n { status: 400 },\n );\n }\n\n // We discourage feed-reader caching (see headers below) but still keep a\n // small server-side cache so we don't hammer paws.org on every poll.\n // Always rebuild the XML with a fresh timestamp so each response looks new.\n if (\n !fresh &&\n !usingCustomUrl &&\n cache &&\n Date.now() - cache.at < CACHE_TTL_MS\n ) {\n const xml = buildRssFeed(\n applyFilters(cache.cats, filters),\n target,\n new Date(),\n );\n return new Response(xml, { headers: noCacheHeaders(\"HIT\") });\n }\n\n try {\n const cats = await scrapeCats(target);\n if (!usingCustomUrl) cache = { at: Date.now(), cats };\n\n const xml = buildRssFeed(applyFilters(cats, filters), target, new Date());\n return new Response(xml, { headers: noCacheHeaders(\"MISS\") });\n } catch (err) {\n return Response.json(\n { error: (err as Error).message, source: target },\n { status: 502 },\n );\n }\n}\n\n/** Normalize a `?sex=` query value to a canonical \"male\" | \"female\", or null. */\nfunction parseSexFilter(raw: string | null): \"male\" | \"female\" | null {\n if (!raw) return null;\n const v = raw.trim().toLowerCase();\n if (v === \"m\" || v === \"male\") return \"male\";\n if (v === \"f\" || v === \"female\") return \"female\";\n return null;\n}\n\n/** Interpret common truthy query-string values: `1`, `true`, `yes`, `on`. */\nfunction parseBoolFlag(raw: string | null): boolean {\n if (!raw) return false;\n const v = raw.trim().toLowerCase();\n return v === \"1\" || v === \"true\" || v === \"yes\" || v === \"on\";\n}\n\ninterface Filters {\n sex: \"male\" | \"female\" | null;\n /** When true, drop any cat whose age mentions \"year\" (i.e. keep only kittens). */\n kittenOnly: boolean;\n}\n\n/** Apply optional query-param filters to a list of cats. */\nfunction applyFilters(cats: Cat[], filters: Filters): Cat[] {\n let result = cats;\n if (filters.sex) {\n result = result.filter((c) => c.sex?.toLowerCase() === filters.sex);\n }\n if (filters.kittenOnly) {\n // Cats whose age contains \"year\" are not kittens. Cats with a null age\n // (typically adoption-pending) are kept since we can't rule them out.\n result = result.filter((c) => !/year/i.test(c.age ?? \"\"));\n }\n return result;\n}\n\n/** Escape a string for safe inclusion in an XML text node or attribute. */\nfunction escapeXml(s: string): string {\n return s\n .replace(/&/g, \"&\")\n .replace(//g, \">\")\n .replace(/\"/g, \""\")\n .replace(/'/g, \"'\");\n}\n\n/** Escape a string for safe inclusion in HTML text. */\nfunction escapeHtml(s: string): string {\n return s\n .replace(/&/g, \"&\")\n .replace(//g, \">\")\n .replace(/\"/g, \""\");\n}\n\n/** Stable per-cat identifier; falls back to name when no detail URL exists. */\nfunction catGuid(cat: Cat): string {\n return cat.detailUrl ?? `paws-cat:${cat.name ?? \"unknown\"}`;\n}\n\n/** Pretty label used for the item title, e.g. \"Whiskers — Female, 2 years\". */\nfunction catTitle(cat: Cat): string {\n const name = cat.name ?? \"Unnamed cat\";\n const facts = [cat.sex, cat.age].filter((v): v is string => !!v).join(\", \");\n const base = facts ? `${name} \\u2014 ${facts}` : name;\n return cat.status === \"adoption_pending\"\n ? `${base} (adoption pending)`\n : base;\n}\n\n/**\n * Build a plain-text, one-line summary of a cat.\n * Example: \"James is a 5 year, 3 month old female Domestic Shorthair cat\n * available for adoption at Cat City.\"\n */\nfunction catSummaryText(cat: Cat): string {\n const name = cat.name ?? \"This cat\";\n const sex = cat.sex?.toLowerCase() ?? null;\n const breed = cat.breed ?? null;\n const age = cat.age ?? null;\n\n // Compose the noun phrase: \" old cat\"\n const descriptor = [age ? `${age} old` : null, sex, breed, \"cat\"]\n .filter((v): v is string => !!v)\n .join(\" \");\n\n const article = /^[aeiou]/i.test(descriptor) ? \"an\" : \"a\";\n\n let sentence = `${name} is ${article} ${descriptor}`;\n\n const availability =\n cat.status === \"adoption_pending\"\n ? \"with an adoption pending\"\n : \"available for adoption\";\n sentence += cat.location\n ? ` ${availability} at ${cat.location}`\n : ` ${availability}`;\n\n return sentence + \".\";\n}\n\n/** Render a single cat as a small, self-contained HTML card. */\nfunction renderCatHtml(cat: Cat): string {\n const rows: Array<[string, string | null]> = [\n [\"Sex\", cat.sex],\n [\"Spay/neuter\", cat.spayNeuterStatus],\n [\"Breed\", cat.breed],\n [\"Age\", cat.age],\n [\"Location\", cat.location],\n [\n \"Status\",\n cat.status === \"adoption_pending\" ? \"Adoption pending\" : \"Available\",\n ],\n ];\n\n const detailRows = rows\n .filter(([, v]) => v)\n .map(\n ([k, v]) =>\n `${escapeHtml(\n k,\n )}${escapeHtml(v!)}`,\n )\n .join(\"\");\n\n const img = cat.imageUrl\n ? ` $\"${escapeHtml(\n$ `\n : \"\";\n\n const link = cat.detailUrl\n ? `

View ${escapeHtml(\n cat.name ?? \"this cat\",\n )} on PAWS →

`\n : \"\";\n\n return [\n `

`,\n `

${escapeHtml(catTitle(cat))}

`,\n img,\n `${detailRows}

`,\n link,\n `

`,\n ].join(\"\");\n}\n\n/** Format a Date as RFC 822 (the format required by RSS 2.0). */\nfunction rfc822(d: Date): string {\n return d.toUTCString();\n}\n\nfunction buildRssFeed(\n cats: Cat[],\n sourceUrl: string,\n generatedAt: Date,\n): string {\n const channelTitle = \"PAWS Adoptable Cats\";\n const channelDescription =\n \"Cats currently listed for adoption at PAWS, updated from paws.org.\";\n const pubDate = rfc822(generatedAt);\n\n const items = cats.map((cat) => {\n const summary = catSummaryText(cat);\n const html = renderCatHtml(cat);\n const guid = catGuid(cat);\n const link = cat.detailUrl ?? sourceUrl;\n\n return [\n ` `,\n ` ${escapeXml(catTitle(cat))}`,\n ` ${escapeXml(link)}`,\n ` ${escapeXml(\n guid,\n )}`,\n ` ${pubDate}`,\n cat.imageUrl\n ? ` `\n : \"\",\n // Plain-text summary for list previews.\n ` ${escapeXml(summary)}`,\n // Rich HTML body for the expanded view.\n ` `,\n ` `,\n ]\n .filter(Boolean)\n .join(\"\\n\");\n });\n\n return [\n ``,\n ``,\n ` `,\n ` ${escapeXml(channelTitle)}`,\n ` ${escapeXml(sourceUrl)}`,\n ` ${escapeXml(channelDescription)}`,\n ` en-us`,\n ` ${pubDate}`,\n ` ${pubDate}`,\n ` cat-adoption-scraper`,\n // Hint to feed readers: poll as often as possible.\n ` 1`,\n ` hourly`,\n ` 1`,\n ...items,\n ` `,\n ``,\n ].join(\"\\n\");\n}\n",[],[189],"12bf639c-5b2b-11f1-8141-ee650bb23af1","deno.json","12bf6432-5b2b-11f1-8141-ee650bb23af1",19,["D",1780037598090],"{\n \"$schema\": \"https://raw.githubusercontent.com/denoland/deno/98f62cee78e85bfc47c62ed703777c6bc8794f1c/cli/schemas/config-file.v1.json\",\n \"lock\": false,\n \"compilerOptions\": {\n \"noImplicitAny\": false,\n \"strict\": true,\n \"types\": [\"https://www.val.town/types/valtown.d.ts\"],\n \"lib\": [\n \"dom\",\n \"dom.iterable\",\n \"dom.asynciterable\",\n \"deno.ns\",\n \"deno.unstable\"\n ]\n },\n \"lint\": {\n \"include\": [\"deno:/https/esm.town/**/*\"],\n \"rules\": {\n \"exclude\": [\"no-explicit-any\"]\n }\n },\n \"node_modules_dir\": false,\n \"experimental\": {\n \"unstable-node-globals\": true,\n \"unstable-temporal\": true,\n \"unstable-worker-options\": true,\n \"unstable-sloppy-imports\": true\n }\n}",[],[199],"fdadf61a-5b2c-11f1-8b8b-ee650bb23af1","README.md","35b6db10-5b2a-11f1-894a-ee650bb23af1",["D",1780038421779],4,"# 🐱 PAWS Cat Adoption RSS Feed\n\nScrapes the [PAWS adoptable cats page](https://www.paws.org/adopt/cats/) and\nrepublishes the listing as an RSS 2.0 feed — one item per cat, with a\nplain-text summary and a rich HTML card (photo + details + link back to PAWS).\n\n## Endpoint\n\n| Path | Behavior |\n| ----------- | ----------------------------------------------------- |\n| `/feed.xml` | The RSS feed (`Content-Type: application/rss+xml`). |\n| `/` | `302` redirect to `/feed.xml` (preserves query string).|\n| anything else | `404 Not found`. |\n\n### Query params\n\n| Param | Effect |\n| ---------- | --------------------------------------------------------------- |\n| `?sex=…` | Filter to `male` / `female` (also accepts `m` / `f`). Invalid values return `400`. |\n| `?kitten=1` | Kittens only — drop any cat whose `age` mentions `year`. Cats with no listed age (typically adoption-pending) are kept. Also accepts `true` / `yes` / `on`. |\n| `?fresh=1` | Bypass the 5-minute server cache and re-scrape immediately. |\n| `?url=…` | Scrape a different listing URL (always uncached). |\n\n## Feed shape\n\nEach `` includes:\n\n- **``** — `Name — Sex, Age` (with `(adoption pending)` suffix when applicable). Example: `Bahama — Female, 5 years 2 months`.\n- **`<link>`** — the cat's PAWS detail page (or the listing URL when none exists).\n- **`<guid>`** — the detail URL (permalink) when available, otherwise a stable `paws-cat:<name>` token.\n- **`<enclosure>`** — the cat's photo URL.\n- **`<description>`** — a plain-text one-liner for list previews. Example: _\"Bahama is a 5 years 2 months old female Domestic Shorthair cat available for adoption at PAWS - Lynnwood.\"_\n- **`<content:encoded>`** — a self-contained HTML card with photo, a labeled details table, and a \"View on PAWS →\" link. Styles are inlined so most readers render it correctly.\n\n> Adoption-pending cats show a name and photo but PAWS hides their details, so\n> the other fields come back `null` and the title is suffixed with\n> `(adoption pending)`.\n\n## Refetch behavior\n\nThe feed asks readers to poll as often as they're willing to:\n\n- HTTP: `Cache-Control: no-store, no-cache, must-revalidate, max-age=0` (plus `Pragma`/`Expires` for older clients).\n- RSS: `<ttl>1</ttl>` and the `sy:` syndication module's `updatePeriod=hourly` / `updateFrequency=1`.\n- `lastBuildDate` and `pubDate` are regenerated on every response so the feed always looks new.\n\nA 5-minute server-side cache of the parsed cat list keeps us from hammering\npaws.org on every poll; it can be bypassed with `?fresh=1`.\n\n## How it works\n\n```mermaid\nflowchart TD\n A[GET /feed.xml] --> B{path matches?}\n B -- \"/\" --> R[302 → /feed.xml]\n B -- \"/feed.xml\" --> P[parse query params]\n P --> S{sex valid?}\n S -- no --> E400[400 error]\n S -- yes --> C{cache hit?}\n C -- yes --> F[apply sex filter]\n C -- no --> D[fetch paws.org HTML]\n D --> X[cheerio parse cards]\n X --> Y[map to Cat objects]\n Y --> Z[store in cache]\n Z --> F\n F --> G[build RSS XML with fresh timestamp]\n G --> H[return with no-cache headers]\n```\n\n## Files\n\n- `main.ts` — HTTP routing, caching, query params, RSS XML generation.\n- `scraper.ts` — `fetch` + `cheerio` parsing of the PAWS markup into `Cat` objects.\n- `test.ts` — runs the scraper against the live site and prints a summary.\n\n## Notes\n\n- PAWS serves server-rendered HTML, so a plain `fetch` + `cheerio` works well —\n no headless browser needed.\n- The parser keys off PAWS's `card-block__*` CSS classes. If PAWS redesigns\n their site, update the selectors in `scraper.ts`.\n- Photos are hosted on Petango (PAWS's adoption management system); promo\n cards are filtered out by requiring the image URL to be on `petango.com`.\n",[],[207],"db1810c2-5b2c-11f1-a8f4-ee650bb23af1","AGENTS.md","12b805de-5b2b-11f1-a919-ee650bb23af1",30,["D",1780038363754],"You are an advanced assistant specialized in generating Val Town code.\n\n## Project context: PAWS Cat Adoption RSS Feed\n\nThis val scrapes <https://www.paws.org/adopt/cats/> and republishes the\nadoptable cats as an RSS 2.0 feed.\n\n### Files\n\n- `main.ts` — HTTP trigger. Routes `/feed.xml` to the feed, redirects `/` to it,\n 404s anything else. Owns: query-param parsing, the 5-minute in-memory cache,\n no-cache response headers, and RSS XML generation (channel + items, with\n plain-text `<description>` and rich `<content:encoded>` HTML).\n- `scraper.ts` — `fetch` + `cheerio` parsing of the PAWS listing markup into\n the `Cat` interface. Exports `scrapeCats(url?)`, `parseCats(html, baseUrl)`,\n and `LISTING_URL`. The selectors key off PAWS's `card-block__*` classes.\n- `test.ts` — hits the live PAWS site via `scrapeCats()` and prints a summary;\n useful for sanity-checking the parser after PAWS markup changes.\n\n### Endpoint contract\n\n- `GET /feed.xml` → `application/rss+xml`.\n- Query params: `?sex=male|female` (also `m`/`f`), `?kitten=1` for kittens\n only (filters out any cat whose `age` contains `year`; accepts standard\n truthy values), `?fresh=1` to bypass cache, `?url=…` to scrape a different\n listing (always uncached).\n- Invalid `sex` returns `400`. Scrape failures return `502` with JSON.\n- Responses always set `Cache-Control: no-store, no-cache, must-revalidate,\n max-age=0` so feed readers refetch aggressively. The channel also advertises\n `<ttl>1</ttl>` and the `sy:` syndication hints.\n- `lastBuildDate` / `pubDate` are regenerated on every response (even on cache\n hits) so the feed always looks new.\n\n### Conventions for changes here\n\n- Keep `scraper.ts` pure: input HTML → `Cat[]`. Don't add HTTP or RSS concerns\n to it.\n- Keep `main.ts` responsible for transport (routing, headers, caching) and\n presentation (RSS XML, HTML rendering, text summaries).\n- Adoption-pending cats have `name` + `imageUrl` but most other fields are\n `null`. Any new rendering code must handle nulls gracefully.\n- When emitting XML/HTML from user-influenced strings, route through\n `escapeXml` / `escapeHtml`. Wrap HTML bodies in `<![CDATA[…]]>`.\n- If you change the cached value's shape, update both the cache-hit and\n cache-miss branches in `main.ts`.\n- Run `deno check --allow-import main.ts` after edits to type-check.\n\n## Core Guidelines\n\n- Ask clarifying questions when requirements are ambiguous\n- Provide complete, functional solutions rather than skeleton implementations\n- Test your logic against edge cases before presenting the final solution\n- Ensure all code follows Val Town's specific platform requirements\n- If a section of code that you're working on is getting too complex, consider refactoring it into subcomponents\n\n## Code Standards\n\n- Generate code in TypeScript or TSX\n- Add appropriate TypeScript types and interfaces for all data structures\n- Prefer official SDKs or libraries than writing API calls directly\n- Ask the user to supply API or library documentation if you are at all unsure about it\n- **Never bake in secrets into the code** - always use environment variables\n- Include comments explaining complex logic (avoid commenting obvious operations)\n- Follow modern ES6+ conventions and functional programming practices if possible\n\n## Types of triggers\n\n### 1. HTTP Trigger\n\n- Create web APIs and endpoints\n- Handle HTTP requests and responses\n- Example structure:\n\n```ts\nexport default async function (req: Request) {\n return new Response(\"Hello World\");\n}\n```\n\nFiles that are HTTP triggers have http in their name like `foobar.http.tsx`\n\n### 2. Cron Triggers\n\n- Run on a schedule\n- Use cron expressions for timing\n- Example structure:\n\n```ts\nexport default async function () {\n // Scheduled task code\n}\n```\n\nFiles that are Cron triggers have cron in their name like `foobar.cron.tsx`\n\n### 3. Email Triggers\n\n- Process incoming emails\n- Handle email-based workflows\n- Example structure:\n\n```ts\nexport default async function (email: Email) {\n // Process email\n}\n```\n\nFiles that are Email triggers have email in their name like `foobar.email.tsx`\n\n\n## Val Town Standard Libraries\n\nVal Town provides several hosted services and utility functions.\n\n### Blob Storage\n\n```ts\nimport { blob } from \"https://esm.town/v/std/blob\";\nawait blob.setJSON(\"myKey\", { hello: \"world\" });\nlet blobDemo = await blob.getJSON(\"myKey\");\nlet appKeys = await blob.list(\"app_\");\nawait blob.delete(\"myKey\");\n```\n\n### SQLite\n\n```ts\nimport { sqlite } from \"https://esm.town/v/stevekrouse/sqlite\";\nconst TABLE_NAME = 'todo_app_users_2';\n// Create table - do this before usage and change table name when modifying schema\nawait sqlite.execute(`CREATE TABLE IF NOT EXISTS ${TABLE_NAME} (\n id INTEGER PRIMARY KEY AUTOINCREMENT,\n name TEXT NOT NULL\n)`);\n// Query data\nconst result = await sqlite.execute(`SELECT * FROM ${TABLE_NAME} WHERE id = ?`, [1]);\n```\n\nNote: When changing a SQLite table's schema, change the table's name (e.g., add _2 or _3) to create a fresh table.\n\n### OpenAI\n\n```ts\nimport { OpenAI } from \"https://esm.town/v/std/openai\";\nconst openai = new OpenAI();\nconst completion = await openai.chat.completions.create({\n messages: [\n { role: \"user\", content: \"Say hello in a creative way\" },\n ],\n model: \"gpt-4o-mini\",\n max_tokens: 30,\n});\n```\n\n### Email\n\n```ts\nimport { email } from \"https://esm.town/v/std/email\";\n// By default emails the owner of the val\nawait email({ \n subject: \"Hi\", \n text: \"Hi\", \n html: \"<h1>Hi</h1>\"\n});\n```\n\n## Val Town Utility Functions\n\nVal Town provides several utility functions to help with common project tasks.\n\n### Importing Utilities\n\nAlways import utilities with version pins to avoid breaking changes:\n\n```ts\nimport { parseProject, readFile, serveFile } from \"https://esm.town/v/std/utils@85-main/index.ts\";\n```\n\n### Available Utilities\n\n\n#### **serveFile** - Serve project files with proper content types\n\nFor example, in Hono:\n\n```ts\n// serve all files in frontend/ and shared/\napp.get(\"/frontend/*\", c => serveFile(c.req.path, import.meta.url));\napp.get(\"/shared/*\", c => serveFile(c.req.path, import.meta.url));\n```\n\n#### **readFile** - Read files from within the project:\n\n```ts\n// Read a file from the project\nconst fileContent = await readFile(\"/frontend/index.html\", import.meta.url);\n```\n\n#### **listFiles** - List all files in the project\n\n```ts\nconst files = await listFiles(import.meta.url);\n```\n\n#### **parseProject** - Extract information about the current project from import.meta.url\n\nThis is useful for including info for linking back to a val, ie in \"view source\" urls:\n\n```ts\nconst projectVal = parseProject(import.meta.url);\nconsole.log(projectVal.username); // Owner of the project\nconsole.log(projectVal.name); // Project name\nconsole.log(projectVal.version); // Version number\nconsole.log(projectVal.branch); // Branch name\nconsole.log(projectVal.links.self.project); // URL to the project page\n```\n\nHowever, it's *extremely importing* to note that `parseProject` and other Standard Library utilities ONLY RUN ON THE SERVER.\nIf you need access to this data on the client, run it in the server and pass it to the client by splicing it into the HTML page\nor by making an API request for it.\n\n## Val Town Platform Specifics\n\n- **Redirects:** Use `return new Response(null, { status: 302, headers: { Location: \"/place/to/redirect\" }})` instead of `Response.redirect` which is broken\n- **Images:** Avoid external images or base64 images. Use emojis, unicode symbols, or icon fonts/libraries instead\n- **AI Image:** To inline generate an AI image use: `<img src=\"https://maxm-imggenurl.web.val.run/the-description-of-your-image\" />`\n- **Storage:** DO NOT use the Deno KV module for storage\n- **Browser APIs:** DO NOT use the `alert()`, `prompt()`, or `confirm()` methods\n- **Weather Data:** Use open-meteo for weather data (doesn't require API keys) unless otherwise specified\n- **View Source:** Add a view source link by importing & using `import.meta.url.replace(\"ems.sh\", \"val.town)\"` (or passing this data to the client) and include `target=\"_top\"` attribute\n- **Error Debugging:** Add `<script src=\"https://esm.town/v/std/catch\"></script>` to HTML to capture client-side errors\n- **Error Handling:** Only use try...catch when there's a clear local resolution; Avoid catches that merely log or return 500s. Let errors bubble up with full context\n- **Environment Variables:** Use `Deno.env.get('keyname')` when you need to, but generally prefer APIs that don't require keys\n- **Imports:** Use `https://esm.sh` for npm and Deno dependencies to ensure compatibility on server and browser\n- **Storage Strategy:** Only use backend storage if explicitly required; prefer simple static client-side sites\n- **React Configuration:** When using React libraries, pin versions with `?deps=react@18.2.0,react-dom@18.2.0` and start the file with `/** @jsxImportSource https://esm.sh/react@18.2.0 */`\n- Ensure all React dependencies and sub-dependencies are pinned to the same version\n- **Styling:** Default to using TailwindCSS via `<script src=\"https://cdn.twind.style\" crossorigin></script>` unless otherwise specified\n\n## Project Structure and Design Patterns\n\n### Recommended Directory Structure\n```\n├── backend/\n│ ├── database/\n│ │ ├── migrations.ts # Schema definitions\n│ │ ├── queries.ts # DB query functions\n│ │ └── README.md\n│ └── routes/ # Route modules\n│ ├── [route].ts\n│ └── static.ts # Static file serving\n│ ├── index.ts # Main entry point\n│ └── README.md\n├── frontend/\n│ ├── components/\n│ │ ├── App.tsx\n│ │ └── [Component].tsx\n│ ├── favicon.svg\n│ ├── index.html # Main HTML template\n│ ├── index.tsx # Frontend JS entry point\n│ ├── README.md\n│ └── style.css\n├── README.md\n└── shared/\n ├── README.md\n └── utils.ts # Shared types and functions\n```\n\n### Backend (Hono) Best Practices\n\n- Hono is the recommended API framework\n- Main entry point should be `backend/index.ts`\n- **Static asset serving:** Use the utility functions to read and serve project files:\n ```ts\n import { readFile, serveFile } from \"https://esm.town/v/std/utils@85-main/index.ts\";\n \n // serve all files in frontend/ and shared/\n app.get(\"/frontend/*\", c => serveFile(c.req.path, import.meta.url));\n app.get(\"/shared/*\", c => serveFile(c.req.path, import.meta.url));\n \n // For index.html, often you'll want to bootstrap with initial data\n app.get(\"/\", async c => {\n let html = await readFile(\"/frontend/index.html\", import.meta.url);\n \n // Inject data to avoid extra round-trips\n const initialData = await fetchInitialData();\n const dataScript = `<script>\n window.__INITIAL_DATA__ = ${JSON.stringify(initialData)};\n </script>`;\n \n html = html.replace(\"</head>\", `${dataScript}</head>`);\n return c.html(html);\n });\n ```\n- Create RESTful API routes for CRUD operations\n- Always include this snippet at the top-level Hono app to re-throwing errors to see full stack traces:\n ```ts\n // Unwrap Hono errors to see original error details\n app.onError((err, c) => {\n throw err;\n });\n ```\n\n### Database Patterns\n- Run migrations on startup or comment out for performance\n- Change table names when modifying schemas rather than altering\n- Export clear query functions with proper TypeScript typing\n\n## Common Gotchas and Solutions\n\n1. **Environment Limitations:** \n - Val Town runs on Deno in a serverless context, not Node.js\n - Code in `shared/` must work in both frontend and backend environments\n - Cannot use `Deno` keyword in shared code\n - Use `https://esm.sh` for imports that work in both environments\n\n2. **SQLite Peculiarities:**\n - Limited support for ALTER TABLE operations\n - Create new tables with updated schemas and copy data when needed\n - Always run table creation before querying\n\n3. **React Configuration:**\n - All React dependencies must be pinned to 18.2.0\n - Always include `@jsxImportSource https://esm.sh/react@18.2.0` at the top of React files\n - Rendering issues often come from mismatched React versions\n\n4. **File Handling:**\n - Val Town only supports text files, not binary\n - Use the provided utilities to read files across branches and forks\n - For files in the project, use `readFile` helpers\n\n5. **API Design:**\n - `fetch` handler is the entry point for HTTP vals\n - Run the Hono app with `export default app.fetch // This is the entry point for HTTP vals`\n\n",[],[215],["D",1780037598144],[],[18],["D",1780037165359],["D",1789524079207],{"_11":12,"_119":67},{"_11":12,"_115":-5,"_66":67,"_30":65,"_116":117,"_118":24},{"_38":106,"_13":16,"_32":35,"_107":69,"_108":-5,"_109":-5,"_110":-5,"_111":-5,"_112":-5,"_113":14,"_114":12},"ctx",{"_51":-5,"_139":263,"_264":265,"_266":267,"_268":24,"_269":24,"_270":24,"_271":137,"_272":-5,"_273":-7,"_274":-7,"_275":26,"_276":24,"_277":24,"_278":-5,"_279":24,"_280":24,"_281":24,"_282":-5},"ENV",{"_234":235,"_236":237,"_238":16,"_239":240,"_241":242,"_243":244,"_245":246,"_247":248,"_249":250,"_251":252,"_253":254,"_255":256,"_257":258,"_259":260,"_261":262},"REACT_APP_SENTRY_DSN","https://586020d86f05489db63a554690acf1e9@o1398359.ingest.sentry.io/6724499","RENDER_GIT_COMMIT","e87eb04e707cf64e7e532c8e8ec395f209e17f15","RENDER_GIT_BRANCH","POSTHOG_API_TOKEN","phc_nmoyuAkStEZuUp69rYlg1DZgrIt19Gx0Y4Hwf8tGgJP","POSTHOG_API_HOST","https://wart.val.town","WEB_API_TEMPLATE","https://{val}.web.val.run","APP_URL","https://www.val.town","MODULE_URL","https://esm.town","VANITY_WEB_API_TEMPLATE","https://{label}.val.run/","DENOLS_URL","https://lsp.val.town","NODE_ENV","production","CLOUDFLARE_TURNSTILE_SITE_KEY","0x4AAAAAACtaIZJH7s9rBMZ6","GOOGLE_CLIENT_ID","875989696899-jtsqkhlbdv5jrlsk8631p7ipjg3c6o62.apps.googleusercontent.com","STRIPE_PUBLISHABLE_KEY","pk_live_51N2zvWEpZTTLipIkVEwXrUG9AT0yeOOEYxszarZT1jpsZV58Ly6wlg3SltZpHN26CUalOBmUSY7adQRQiSkCZz2500qSXNkf8Y","API_URL","https://api.val.town",[],"preferencesKeybindings","default","preferencesTheme","light","preferencesFixers","preferencesCopilot","preferencesSelectionAi","preferencesCloseBrackets","preferencesChatPanelState","preferencesDprint","preferencesDenofmt","notificationCount","flagDenols","isBusinessOrgMember","businessOrgHandle","isBusinessOrgAdmin","isHigherTownieTier","navCollapsed","currentOrgId"] </article></body></html>

History · .vtignore