Skip to content

What Ships to the Browser

Three rules decide what the browser downloads, and none of them is a guess. Each is a fact about where you put the code, so you can read it off the file tree.

  • Pages, layouts, loading templates and boundaries never ship. They run only on the server.
  • Every component in an ordinary file always ships and hydrates, exactly as a Lit component does.
  • Server-only markup ships nothing. Write it as a component in a *.server.ts file, or as a function returning html.

So a route costs the browser exactly the components it renders. A route that renders no interactive component ships zero application JavaScript and is pure server-rendered HTML, which still navigates and submits forms through native browser behaviour.

Pages, layouts and boundaries never ship

A page, layout, loading template or boundary (error, not-found, forbidden, unauthorized) runs only on the server, the way a Next.js server component does. Its module is never sent to the browser: the client boot imports the components it renders instead. That is why a page can import a .server.ts utility, a database client or a node: module without any of it reaching the browser, and why requesting a page's source URL returns 404.

The consequence is the one Next.js has for server components: anything that needs a browser belongs in a component. A component class defined inside a page, an @click binding on a page's template, a 'use client' directive on a page, a component importing a page file, and a Node builtin reached from a component are each refused by webjs check with the fix. For app-wide browser code that belongs to no component (analytics, a polyfill, the client router on a page with no component), use instrumentation-client.ts, which loads on every page.

Every component ships

A WebComponent in an ordinary file is browser code, as in Lit: its module ships and the element hydrates, whether or not it has state, events or lifecycle hooks. There is nothing to annotate and nothing to forget. A 'use client' directive at the top of a component file is accepted and changes nothing, so the Next.js habit is harmless here.

A component reaches the server through a 'use server' action: importing one from a component gives the browser an RPC stub whose exports call the server, and an action called during server rendering is seeded into the page, so an async render() does not fetch the same data again on hydration.

Server-only markup

Markup that only the server should render is written one of two ways, the same split Next.js draws between client and server components. Neither ships.

  • A component in a *.server.ts file. It renders on the server and is never defined in the browser, so it may import server code and have an async render() that reads the database. The file must not start with 'use server': that directive turns a file's function exports into actions, and a class is a function (webjs check refuses it as no-component-in-use-server-file).
  • A function returning html, called from a page or layout. It may be async, like a Next.js server component.

The Next.js rules between the two kinds carry over. A page may render either. A client component may not import a server-only one or render its tag in its own template, because the tag is never defined in the browser and comes back empty after a client re-render. Pass it in as a child from the page instead, and it lands in the client component's <slot>. webjs check refuses interactivity inside a .server component (no-interactivity-in-server-component) and a server-only tag in a client template (no-server-component-in-client-template). See Server-only components for an example.

A component the scanner cannot see

The boot finds the components a route renders by their registration, which must name a literal tag:

// Broken: the scanner requires a literal tag.
const TAG = buildTag();
Badge.register(TAG);          // invisible

// Correct:
Badge.register('my-badge');

A class with a computed tag, or with no registration call at all, is an orphan. The boot never loads it in place of the page that imports it, so the element never upgrades. webjs dev warns about it and webjs doctor reports it (ORPHAN_COMPONENTS). Registering the class from a sibling module is fine, since the check is app-wide.

Seeing what a route loads

Open the network tab: a route loads the components it renders and instrumentation-client.ts, and never a page.ts or layout.ts. Two tools point out code that will not run where it looks like it should:

  • webjs status, the command to run after each edit, prints a warning for code in a page, layout or boundary that looks meant for the browser (a window access, a client-router or signal import, a side-effect import that sets something up), since it runs only on the server.
  • webjs doctor reports the same as ROUTE_BROWSER_CODE, and orphan components as ORPHAN_COMPONENTS.

For a tool, analyzeRouteModules(appDir) from @webjsdev/server returns every route module with its kind, the components the boot loads in its place, and those hints.