Menu
Use when building an HTTP val — a web endpoint, API route, webhook receiver, or any val that responds to HTTP requests. Covers the handler signature, Hono usage, the endpoint URL, CORS behavior, redirects, and Val Town-specific limitations.
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
Based on SOC occupation classification
Use when the user wants to persist a preference, skill, or knowledge. Use when it would aid future val development to store a memory of how best to build something.
Use when a val needs to ship JavaScript that runs in the browser — React apps, vanilla DOM scripts, canvas/games, htmx/Alpine, or any client-side module beyond a single inline snippet. Explains how Val Town serves transpiled .ts/.tsx/.jsx modules with no build step, how the browser resolves their imports, and how to load third-party deps.
Use when a val needs simple key/value persistence — JSON documents, cached responses, uploaded files, or binary assets. Covers the std/blob API, listing and deleting keys, account-global or val scoping, and storage limits.
Use when a val needs to require login with a Val Town account — gating routes behind authentication, identifying the current user, building user-specific dashboards. Covers std/oauth's `oauthMiddleware` and `getOAuthUserData`, the auto-managed `/auth/*` routes, and session behavior. For third-party OAuth providers (Google, GitHub, etc.) see the `third-party-integrations` skill instead.
Use when a val sends email, receives email, or is triggered by an incoming email. Covers email-type vals (the Email handler shape, attachment limits, the assigned val email address) and sending mail via std/email.
Use when a val needs to store structured or relational data. Covers the std/sqlite API, parameterized queries, transactions, and the val-scoped vs organization-scoped database distinction.
| name | http-endpoints |
| description | Use when building an HTTP val — a web endpoint, API route, webhook receiver, or any val that responds to HTTP requests. Covers the handler signature, Hono usage, the endpoint URL, CORS behavior, redirects, and Val Town-specific limitations. |
| triggers | ["http","endpoint","webhook","api","request","response","hono","web","route","fetch","cors","redirect"] |
HTTP vals (fileType: "http") export a request handler and run on every incoming HTTP request. Each HTTP file is assigned a public live URL — never construct it yourself; read links.endpoint from list_files or create_file responses, or call fetch_val_endpoint.
// Learn more: https://docs.val.town/vals/http/
export default async function (req: Request): Promise<Response> {
return Response.json({ ok: true });
}
The file must have an export — export default for the handler.
When using Hono, export app.fetch (not app):
import { Hono } from "npm:hono";
import { parseVal, serveFile } from "https://esm.town/v/std/utils/index.ts";
const app = new Hono();
app.get("/", (c) => c.text("hello"));
// Serve all frontend files, transpiled, with correct content types
app.get("/frontend/**/*", (c) => serveFile(c.req.path));
// View source redirect
app.get("/source", (c) => c.redirect(parseVal().links.self.val));
// Always add this for full stack traces on errors:
app.onError((err) => Promise.reject(err));
export default app.fetch;
Hono's serveStatic does not work on Val Town. Use serveFile / staticHTTPServer from std/utils for static files. For the full std/utils API (readFile, serveFile, staticHTTPServer, listFiles, listFilesByPath, httpEndpoint, parseVal, …), fetch https://utilities.val.run/docs.md.
Val Town adds permissive CORS headers by default (Access-Control-Allow-Origin: *), so in 99% of cases, you should never need to do anything with CORS. Using Hono's cors middleware is almost always unnecessary.
If you set any CORS header yourself, Val Town stops adding all default headers — so either handle CORS completely yourself or don't touch it at all.
Response.redirect is broken on Val Town. Use one of:
return new Response(null, { status: 302, headers: { Location: "/path" } });
// or, with Hono:
return c.redirect("/path");
std/sqlite or std/blob.For HTML responses, add this script tag to send browser errors back to val logs (visible via get_logs):
<script src="https://esm.town/v/std/catch"></script>
After editing an HTTP val, fetch it to confirm it returns the expected HTTP response. Do not report a change as done without this step.