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";

// 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
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
getContentType	Get MIME type for a file path
staticHTTPServer	Create a static file server (serves /index.html at root)
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

Rendering mermaid diagram...

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
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	Hono-based static file server
_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.