client-side-js

Client-side JavaScript

Val Town has no build step and no bundler. A client-side module is just a file in your val that you serve over HTTP; Val Town transpiles it per request. You point a <script type="module"> at a route that returns the file, and the browser runs it. There is nothing to configure (no webpack/vite/esbuild).

Serving a module

serveFile from std/utils reads a file and serves it with the correct Content-Type. For .ts, .tsx, and .jsx it transpiles to JavaScript — strips types, compiles JSX — and serves text/javascript. You serve the source file; the browser receives runnable JS.

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

// in any HTTP handler — serve a client module at some URL path
app.get("/app.tsx", (c) => serveFile("/app.tsx"));

Then load it from your HTML:

<script type="module" src="/app.tsx"></script>

The path you serve at and the file's location are up to you. A common shortcut is a wildcard that serves a whole directory of modules and assets:

app.get("/client/**/*", (c) => serveFile(c.req.path));

serveFile defaults to the current val. If you call it from a non-entrypoint file and paths don't resolve, pass import.meta.url as the second argument.

Default: versioned, immutably cached modules

serveImmutableFile makes your val's frontend faster by letting browsers cache files immutably; publishing bumps the val's version, which invalidates automatically. Measured: repeat visits 665ms → 157ms with zero asset requests.

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

app.get("/__immutable/*", (c) => serveImmutableFile(c.req.path));

In the never-cached HTML shell, stamp the entry module: immutableFileUrl("/frontend/index.tsx") → /__immutable/42/frontend/index.tsx (42 = the val's current version). Relative imports resolve under the same prefix, so only the entry needs stamping — one route and one stamped URL cover the whole client graph.