Standard utility library for Val Town. Provides helpers for reading files, serving static content, parsing val metadata, and testing.

📖 Full API documentation

import { readFile, serveFile, parseVal, listFiles } from "https://esm.town/v/std/utils/index.ts";

staticHTTPServer is the fastest way to ship HTML/CSS/JS from a val. Drop an index.html (plus any assets) into your val and:

import { staticHTTPServer } from "https://esm.town/v/std/utils/index.ts";

// Serves index.html at "/", every other file by path, and a /source redirect.
export default staticHTTPServer();

This automatically:

• serves /index.html at /
• serves any other path as a static file with the correct Content-Type
• exposes /source, which 302-redirects to the val's source code on Val Town — so visitors can always click through to see how a page was built.

Need an API route or a redirect alongside your static files? Pass a fetch handler as the second argument — it's just the web standard (request) => Response. It's tried first on every request: return a Response to handle it yourself, or return null/undefined to fall through to static serving (and /source):

import { staticHTTPServer } from "https://esm.town/v/std/utils/index.ts";

export default staticHTTPServer(import.meta.url, (req) => {
  const { pathname } = new URL(req.url);
  if (pathname === "/api/hello") return Response.json({ hello: "world" });
  return null; // defer to the static server (index.html / assets / /source)
});

Since it's the fetch standard, any framework's handler works too — e.g. pass Hono's app.fetch (have its notFound return null so unmatched routes fall through):

import { Hono } from "npm:hono@4.11.9";
import { staticHTTPServer } from "https://esm.town/v/std/utils/index.ts";

const app = new Hono();
app.get("/api/hello", (c) => c.json({ hello: "world" }));
app.notFound(() => null as any);

export default staticHTTPServer(import.meta.url, app.fetch);

// Read a file from your val
const content = await readFile("/README.md");

// Serve static files in a Hono app
app.get("/assets/*", (c) => serveFile(c.req.path));

// Get the current val's metadata
const val = parseVal(import.meta.url);
console.log(val.username, val.name);

Function	Description
staticHTTPServer	Deploy a static site in one line. Serves /index.html at root, assets by path with automatic immutable caching, and a /source redirect. Optionally pass a fetch handler for custom routing.
readFile	Read raw file contents from your val
readFileTranspiled	Read transpiled JS (types stripped) for browser use
listFiles	List all files in the current val with metadata
listFilesByPath	List files in a specific directory
httpEndpoint	Get the live HTTP URL for a file
emailAddress	Get the email address for an email-trigger file
getValId	Get the current val's UUID
fetchTranspiledJavaScript	Fetch transpiled JS from any esm.town URL
serveFile	Serve a file as an HTTP Response with correct Content-Type
serveImmutableFile	Serve /__immutable/<version>/<path> URLs with immutable browser caching; bare paths 302 into the current version, other versions 404
immutableFileUrl	Version-address a file path for immutable caching (/frontend/index.tsx → /__immutable/45/frontend/index.tsx)
getContentType	Get MIME type for a file path
parseVal	Parse val metadata (username, name, version, branch, links) from import.meta.url
isMain	Check if the current file is the entrypoint
testServer	Create an HTML test runner with pass/fail badges

File	Type	Purpose
index.ts	script	Public entry point — re-exports all utilities
file.ts	script	File I/O: read, list, transpile, endpoints, email addresses
serve-file.ts	script	HTTP file serving with MIME type detection
serve-immutable-file.ts	script	Version-addressed file serving with immutable caching (serveImmutableFile, immutableFileUrl)
parseImportMeta.ts	script	Parse import.meta.url into val metadata
is-main.ts	script	Entrypoint detection (import.meta.main replacement)
test.tsx	script	Test runner with HTML output and SVG badges
static.tsx	script	Static file server (fetch-standard, no framework dependency)
_docs.tsx	http	Auto-generated documentation site at utilities.val.run
_tests.ts	http	Test suite endpoint
*.test.ts	http	Per-module test files

Tests run as HTTP endpoints. Each source file has a corresponding .test.ts file. The _tests.ts file aggregates all tests and serves a badge at /badge.svg.

The _docs.tsx file uses the TypeScript compiler API to extract JSDoc from source files and render them as an HTML documentation site. Return type overrides for SDK types that can't be resolved by the in-memory compiler are hardcoded in RETURN_TYPE_OVERRIDES — these may need updating if the @valtown/sdk types change.