Val Town Utilities

A comprehensive collection of utilities for building and testing applications in Val Town Projects.

• readFile - Read files from Val Town vals
• listFiles - List all files in a val
• listFilesByPath - List files in a specific directory path
• httpEndpoint - Get HTTP endpoint URL for a file
• fetchTranspiledJavaScript - Fetch and transpile TypeScript/JavaScript
• parseVal - Extract metadata from Val Town URLs
• parseProject - Legacy function for parsing Val metadata (deprecated)
• serveFile - Serve files with proper content types
• getContentType - Determine MIME types for files
• staticHTTPServer - Create a static file server
• testServer - Create a test runner with HTML/SVG output

Utilities for reading and managing files in Val Town Projects.

Reads the contents of a file from the current val.

Signature:

Create val
readFile(path: string, metaImportUrl?: string): Promise<string>

Parameters:

• path - The file path to read (with or without leading slash)
• metaImportUrl - Optional. The import.meta.url to determine which val to read from. Defaults to Deno.env.get("VALTOWN_ENTRYPOINT")

Example:

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

// Most common usage - reads from current val
const content = await readFile("/README.md");
console.log(content);

// Explicit val specification
const content2 = await readFile("/README.md", import.meta.url);
console.log(content2);

Lists all files in the current val with their metadata.

Signature:

Create val
listFiles(metaImportUrl?: string): Promise<File[]>

Parameters:

• metaImportUrl - Optional. The import.meta.url to determine which val to list files from. Defaults to Deno.env.get("VALTOWN_ENTRYPOINT")

Example:

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

// Most common usage - lists files from current val
const files = await listFiles();
files.forEach((file) => console.log(file.path));

// Explicit val specification
const files2 = await listFiles(import.meta.url);
files2.forEach((file) => console.log(file.path));

Lists files in a specific directory path within the current val.

Signature:

Create val
listFilesByPath(path: string, metaImportUrl?: string): Promise<File[]>

Parameters:

• path - The directory path to list files from
• metaImportUrl - Optional. The import.meta.url to determine which val to list files from. Defaults to Deno.env.get("VALTOWN_ENTRYPOINT")

Example:

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

// List files in a specific directory
const frontendFiles = await listFilesByPath("frontend/");
frontendFiles.forEach((file) => console.log(file.path));

Gets the HTTP endpoint URL for a specific file in the val.

Signature:

Create val
httpEndpoint(path: string, metaImportUrl?: string): Promise<string>

Parameters:

• path - The file path to get the endpoint for
• metaImportUrl - Optional. The import.meta.url to determine which val the file belongs to. Defaults to Deno.env.get("VALTOWN_ENTRYPOINT")

Example:

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

// Get the HTTP endpoint for a specific file
const endpoint = await httpEndpoint("/api/users.ts");
console.log(endpoint); // Returns the full HTTP URL for the endpoint

Fetches and transpiles TypeScript/JavaScript code from esm.town URLs.

Signature:

Create val
fetchTranspiledJavaScript(url: string): Promise<string>

Example:

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

const code = await fetchTranspiledJavaScript(
  "https://esm.town/v/std/utils@85-main/index.ts",
);
console.log(code);

Notes:

• Paths can be specified with or without leading slashes
• TypeScript files are automatically transpiled to JavaScript
• Most functions now have optional metaImportUrl parameters that default to Deno.env.get("VALTOWN_ENTRYPOINT"), making them easier to use in most cases

Extract metadata about the currently running Val.

Parses Val Town metadata from an import.meta.url.

Signature:

Create val
parseVal(importMetaUrl: string): ValMetadata

Example:

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

const val = parseVal(import.meta.url);
console.log(val);
// Output: { owner: "username", name: "valname", ... }

Prior Art:

• @pomdtr/extractValInfo
• @easrng/whoami

⚠️ Deprecated: This function is provided for backwards compatibility only. Use parseVal instead.

Legacy function for parsing Val Town metadata from an import.meta.url. This function has been superseded by parseVal which provides better functionality and more consistent results.

Signature:

Create val
parseProject(importMetaUrl: string): ProjectMetadata

Example:

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

// ⚠️ Deprecated - use parseVal instead
const project = parseProject(import.meta.url);

// ✅ Recommended approach
import { parseVal } from "https://esm.town/v/std/utils/index.ts";
const val = parseVal(import.meta.url);

HTTP utilities for serving val files with proper content types.

Serves a file from the val as an HTTP Response with the correct Content-Type header.

Signature:

Create val
serveFile(path: string, metaImportUrl?: string): Promise<Response>

Parameters:

• path - The file path to serve
• metaImportUrl - Optional. The import.meta.url to determine which val to serve from. Defaults to Deno.env.get("VALTOWN_ENTRYPOINT")

Example:

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

// In a Hono app - most common usage
app.get("/assets/*", async (c) => {
  return await serveFile(c.req.path);
});

// Explicit val specification
app.get("/assets/*", async (c) => {
  return await serveFile(c.req.path, import.meta.url);
});

Determines the appropriate MIME type for a file based on its extension.

Signature:

Create val
getContentType(path: string): string

Example:

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

console.log(getContentType("index.html")); // "text/html; charset=utf-8"
console.log(getContentType("script.ts")); // "text/javascript"
console.log(getContentType("data.json")); // "application/json; charset=utf-8"

Features:

• TypeScript/TSX/JSX files are served as text/javascript