DEV Community: Danny Holloran

Svelte Error Boundaries: Contain the Crash Instead of Losing the Page

Danny Holloran — Fri, 16 Oct 2026 10:10:37 +0000

Every app has that one component. The chart that chokes on a null in the data, the third-party embed that throws when its script loads late, the dashboard card that assumes an API field will always exist. In a lot of Svelte apps, one of those throwing during render takes the whole page down with it, and your users get a blank screen instead of a page that's 95% fine.

Svelte 5 has had a fix for this since 5.3: <svelte:boundary>. It has quietly grown into one of the more useful special elements in the framework, and as of 5.51 it can even handle errors during server-side rendering. If you haven't reached for it yet, here's what it does and where it fits.

Walling Off a Component

A boundary wraps part of your tree. If anything inside throws while rendering or while running an effect, the boundary catches it, removes the broken content, and renders a failed snippet in its place. The snippet receives the error and a reset function that rebuilds the contents from scratch.

<script>
  import RevenueChart from './RevenueChart.svelte';
</script>

<svelte:boundary>
  <RevenueChart />

  {#snippet failed(error, reset)}
    <div class="card card--error">
      <p>The revenue chart couldn't load.</p>
      <button onclick={reset}>Try again</button>
    </div>
  {/snippet}
</svelte:boundary>

The rest of the page keeps rendering normally. Only the chart's slot shows the fallback, and reset gives the user a way to retry without a full reload.

If you'd rather report the error than (or as well as) render something, pass an onerror handler. It gets the same error and reset arguments:

<script>
  import * as Sentry from '@sentry/svelte';
  import ActivityFeed from './ActivityFeed.svelte';
</script>

<svelte:boundary onerror={(error) => Sentry.captureException(error)}>
  <ActivityFeed />

  {#snippet failed()}
    <p>Activity is unavailable right now.</p>
  {/snippet}
</svelte:boundary>

If onerror itself throws, or you rethrow, the error bubbles to the nearest parent boundary. That lets you build layers: a tight boundary around each risky widget, and a coarse one near the root as the last line of defense.

What Boundaries Don't Catch

This is the part that trips people up. Boundaries catch errors that happen during rendering and inside effects. They do not catch errors in event handlers, inside a setTimeout, or in other async work that runs outside the render cycle.

<svelte:boundary>
  <!-- This throw is NOT caught by the boundary -->
  <button onclick={() => { throw new Error('nope'); }}>Click</button>

  {#snippet failed()}<p>Never shown for the click error</p>{/snippet}
</svelte:boundary>

That's the same split React draws, and for the same reason: an event handler failing doesn't leave the UI in a half-rendered state, so there's nothing for a boundary to replace. Handle those errors where they happen, with try/catch and some local state.

Pending UI for `await`

Boundaries also handle the other side of async rendering. With Svelte's await expressions, you can put an await directly in your markup, and a boundary's pending snippet shows while those expressions first resolve:

<script>
  let { userId } = $props();
</script>

<svelte:boundary>
  <h2>{(await getUser(userId)).name}</h2>
  <p>{(await getStats(userId)).posts} posts</p>

  {#snippet pending()}
    <div class="skeleton" aria-busy="true"></div>
  {/snippet}

  {#snippet failed(error, reset)}
    <button onclick={reset}>Couldn't load profile. Retry?</button>
  {/snippet}
</svelte:boundary>

Two caveats. First, pending only shows on the initial load. Later updates keep the old content on screen, and you use $effect.pending() if you want a spinner for those. Second, during server-side rendering, a boundary with a pending snippet renders only that snippet and skips its content, so put boundaries around the slow, non-critical parts of the page and not around the content you need indexed.

Boundaries on the Server

Until recently, boundaries did nothing during SSR. An error in any component failed the whole render() call. Svelte 5.51 changed that with a transformError option on render from svelte/server:

import { render } from "svelte/server";
import App from "./App.svelte";

const { head, body } = await render(App, {
  transformError: (error) => {
    // Log the real error, with its stack, on the server...
    console.error(error);
    // ...and send only a safe, serializable shape to the browser
    return { message: "Something went wrong loading this section." };
  },
});

When a component inside a boundary with a failed snippet throws during SSR, transformError decides what the snippet receives. The return value has to be JSON-serializable because it gets serialized into the page and used to hydrate the failed snippet in the browser. If the boundary also has onerror, it fires on hydration with that deserialized object. If transformError throws, the whole render fails as before.

The redaction step matters. Server errors can carry database messages, file paths, and stack traces, and the Svelte docs explicitly recommend sanitizing them rather than shipping them to the client.

If you're on SvelteKit, you don't call render yourself, so the framework has to wire transformError up for you. The Svelte docs say that support is coming via SvelteKit's handleError hook. Check the SvelteKit changelog for your version before you count on server-side boundaries working there. Until then, handleError and +error.svelte remain the SvelteKit way to deal with errors in load and on the server.

Where to Put Them

A good rule: wrap anything whose failure shouldn't cost the user the rest of the page. Third-party embeds, data visualizations, user-generated content renderers, and any widget fed by a flaky API are all prime candidates. Keep boundaries out of trivial components, because a fallback for every button is noise. Start with one root-level boundary plus a few around your riskiest widgets, wire onerror into whatever error tracking you already use, and read the <svelte:boundary> docs for the full API.

Dependency Cooldowns: Make Your Package Manager Wait Before It Trusts New Code

Danny Holloran — Tue, 13 Oct 2026 10:11:07 +0000

Most npm supply-chain attacks follow the same script. Someone phishes a maintainer or steals a publish token, pushes a poisoned patch release, and then waits for every ^1.2.3 range on the planet to pick it up on the next install. The malicious version usually gets spotted and pulled within hours. The damage is done in those hours, by machines that installed it before anyone noticed.

A dependency cooldown attacks that window directly. Instead of installing whatever was published thirty seconds ago, your package manager only accepts versions that have existed for a while. It's a boring idea, and that's why it works: you let the rest of the ecosystem be the canary. Every major package manager now supports it, but each one picked its own config key and, annoyingly, its own unit of time.

One idea, four spellings

Here's the same "wait at least a day" policy in each tool.

pnpm uses minutes, configured in pnpm-workspace.yaml. Since pnpm 11 this is on by default at 1440 minutes, so if you're on a current pnpm you already have it:

# pnpm-workspace.yaml
minimumReleaseAge: 1440 # minutes
minimumReleaseAgeExclude:
  - "@myorg/*"

npm added min-release-age in CLI 11.10, measured in days and off by default:

# .npmrc
min-release-age=1

Bun uses seconds, under the [install] table:

# bunfig.toml
[install]
minimumReleaseAge = 86400 # seconds
minimumReleaseAgeExcludes = ["@types/node", "typescript"]

Yarn Berry (4.10+) calls it npmMinimalAgeGate, in minutes:

# .yarnrc.yml
npmMinimalAgeGate: 1440

Minutes, days, seconds, minutes. If you maintain a repo that switches package managers, or you copy a snippet from a blog post written for a different tool, it's very easy to set a 1440-day cooldown in npm or a 24-second one in Bun. Leave a comment with the unit next to the number every time.

The details that actually matter

The headline setting is simple. The edge cases are where teams get surprised.

It applies to transitive dependencies too. That's the point: the attack rarely lands in a package you depend on directly. pnpm's docs are explicit that the gate covers the whole tree, which also means a deep dependency like caniuse-lite (which publishes constantly) can be the thing that trips it.

Strict vs. fallback. In pnpm, if nothing in your requested range is old enough, there are two possible behaviors: fail, or fall back to the too-new version. pnpm's built-in default of 1440 is non-strict for backward compatibility, so it quietly falls back. The moment you set minimumReleaseAge yourself, minimumReleaseAgeStrict flips to true and the install fails instead. That's the behavior you want for security, but be ready for it.

Lockfiles behave differently per tool. Bun only applies the gate during new resolution, so entries already in bun.lock are left alone. pnpm goes further: by default it re-checks every lockfile entry against the policy on install, which catches a lockfile someone generated under a weaker setting. You can turn that off with trustLockfile: true, but only do it if every commit comes from people you trust.

Missing timestamps pass by default. The gate relies on the registry's time metadata. Some private registries and mirrors don't serve it, and both pnpm and Bun treat an undated version as passing. If you run an internal proxy, pnpm lets you tighten this:

minimumReleaseAgeIgnoreMissingTime: false

npm's config output can lie to you. There's an open npm CLI issue where npm config ls --long reports min-release-age = null even though npm install is honoring the setting, because npm converts it to a --before date internally. Test the behavior with an install, not by reading the config dump.

Where it bites, and how to live with it

The most common complaint after pnpm 11 shipped wasn't about attacks. It was Dependabot. A bot opens a PR the moment a new version appears, CI runs a frozen install, and the brand-new version is younger than the cooldown, so CI goes red. The PR isn't wrong, it's just early. Your options are to delay the bot (Dependabot and Renovate both support a minimum age or cooldown on their side), or add a narrow, version-pinned exclusion:

minimumReleaseAgeExclude:
  - nx@21.6.5
  - webpack@4.47.0 || 5.102.1

Pinning to a specific version beats excluding a whole package name. A name-level exclusion means every future release of that package skips the gate, which is exactly the hole an attacker wants. pnpm can even clean up stale exclusions for you with minimumReleaseAgeExcludePrune: true.

The other real cost is urgent security patches. When a CVE fix lands and you need it now, the cooldown is in your way. npm lets you override per command:

npm i --min-release-age 0 some-package@1.4.2

Use that deliberately, for the one package, and don't bake it into scripts.

Finally, be honest about what this protects you from. A cooldown only helps against compromises that get caught quickly. A patient attacker who ships something that sits undetected for weeks walks right through it. It's one layer, alongside lockfiles, allowBuilds / install-script controls, and provenance checks like pnpm's trustPolicy: no-downgrade.

If you're on pnpm 11 or newer, you've already got a soft version of this. Set minimumReleaseAge explicitly so it becomes strict, add a cooldown to your update bot so it stops racing your own policy, and if you're on npm, add min-release-age=1 to your .npmrc today. It's one line, and it turns "we installed the bad version" into "we read about the bad version."

CSS Container Style Queries: Let the Parent Set the Theme

Danny Holloran — Mon, 12 Oct 2026 10:10:57 +0000

Every design system eventually grows a modifier class problem. The card needs a dark version for the footer, a compact version for the sidebar, and a "highlighted" version for the pricing page. So you add .card--dark, .card--compact, .card--featured, and then you need a dark compact card, and then the button inside the card also needs to know it's on a dark background. Now the class has to be threaded through three components, or you're writing selectors like .card--dark .button.

Container size queries solved half of this in 2023: components could finally react to the space they're given instead of the viewport. The other half, reacting to the context they're placed in, became Baseline Newly available in May 2026 when Firefox 151 shipped support for container style queries. Chrome and Edge have had them since 111, and Safari since 18, so this is ready for production with a sensible fallback.

How Style Queries Work

A style query asks a question about the computed value of a custom property on an ancestor. If the answer is yes, the nested rules apply to descendants:

.panel {
  --theme: dark;
}

@container style(--theme: dark) {
  .card {
    background: oklch(0.22 0.02 260);
    color: oklch(0.95 0 0);
  }

  .button {
    border-color: currentColor;
  }
}

Two things are different from size queries. First, you don't need container-type. Every element is a style container by default, so @container style(...) checks the nearest ancestor with no setup at all. Second, only custom properties work today. The spec allows style(font-weight: bold) on regular properties, but no browser implements that yet, so stick to --anything.

If you have nested contexts (a light card inside a dark panel inside a light page), name the level you care about:

.site-footer {
  container-name: footer;
  --theme: dark;
}

@container footer style(--theme: dark) {
  .newsletter-form input {
    background: transparent;
    color: inherit;
  }
}

Without a name, the query targets the nearest ancestor. With one, it targets the nearest ancestor with that container-name, which is what you want when themes nest.

The Gotcha: You Can't Query Yourself

This is the mistake almost everyone makes on day one:

/* Does not work the way you'd expect */
.card[data-variant="featured"] {
  --variant: featured;
}

@container style(--variant: featured) {
  .card {
    border: 2px solid gold;
  }
}

The query is evaluated against the card's ancestor, not the card. The card's parent never set --variant, so the query fails. Custom properties inherit downward, not upward. The fix is to style a child of the element that holds the value, which in practice means having a wrapper:

<article class="card" style="--variant: featured">
  <div class="card__inner">
    <h3>Pro plan</h3>
    <a class="button" href="/signup">Start trial</a>
  </div>
</article>

@container style(--variant: featured) {
  .card__inner {
    border: 2px solid gold;
  }

  .button {
    background: gold;
    color: black;
  }
}

If you only need a single property on the element itself to change, that's what the if() function is for. A useful rule of thumb: if() produces a conditional value for one element, while a style query sets context for a whole subtree.

It's also worth registering the property with @property. A registered property has a known type and an initial value, so a container that never sets --variant resolves to something predictable instead of the guaranteed-invalid value:

@property --variant {
  syntax: "<custom-ident>";
  initial-value: default;
  inherits: true;
}

Range Queries and a Fallback Plan

Exact matching covers themes and variants, but numbers are where it gets interesting. Chrome 142 added range syntax, so you can compare values instead of matching strings:

.meter {
  --fill: 72%;
}

@container style(--fill > 90%) {
  .meter__bar {
    background: oklch(0.6 0.2 25);
  }
}

@container style(--fill > 50%) and style(--fill <= 90%) {
  .meter__bar {
    background: oklch(0.75 0.15 85);
  }
}

Both sides of a comparison must resolve to the same numeric type (length, number, percentage, angle, time, frequency, or resolution). Note the split here: plain equality style queries are Baseline, but range syntax is Chromium-only for now. Treat range queries as a progressive enhancement.

The fallback story is simple because style queries are additive. Write your default component styles outside any query, then layer the contextual variants inside @container style() blocks. A browser that doesn't understand the at-rule skips it entirely and renders the default card. Nothing breaks; the footer card is just light instead of dark. If that's not acceptable for a given component, keep the old modifier class as a fallback alongside the style query and delete it once your analytics say the stragglers are gone.

Where to Start

Pick the one place in your codebase where a theme or variant class gets passed down through props or descendant selectors, and replace it with a single custom property on the wrapper and a style query for the children. You'll likely find that the components inside stop needing to know anything about where they live. The MDN guide to container size and style queries covers the full syntax, and Una Kravets' range style queries write-up is worth bookmarking for when the range syntax lands everywhere.

Map.getOrInsert: Stop Writing the has/get/set Dance

Danny Holloran — Fri, 09 Oct 2026 10:12:48 +0000

Every JavaScript codebase has this pattern somewhere. Usually in a dozen places. You want to group things by a key, so you reach for a Map, and then you write the same three lines you always write: check if the key exists, create an empty bucket if it doesn't, then fetch the bucket and push into it.

const byAuthor = new Map();

for (const post of posts) {
  if (!byAuthor.has(post.author)) {
    byAuthor.set(post.author, []);
  }
  byAuthor.get(post.author).push(post);
}

It works. It's also three hash lookups for one logical operation, and in TypeScript the get() call still returns T | undefined, so you end up sprinkling a non-null assertion on a value you just guaranteed exists. The upsert proposal fixes this with two small methods, and as of 2026 they ship in every major browser engine.

getOrInsert and getOrInsertComputed

The proposal reached Stage 4 at TC39 in January 2026 and adds two methods to both Map and WeakMap:

map.getOrInsert(key, defaultValue) returns the existing value for key. If there isn't one, it stores defaultValue and returns that.
map.getOrInsertComputed(key, callback) does the same thing, but only calls callback(key) to build the default when the key is actually missing.

The grouping loop above collapses to one line per item:

const byAuthor = new Map();

for (const post of posts) {
  byAuthor.getOrInsert(post.author, []).push(post);
}

Counting works the same way. Because the method returns the stored value, you can read and write in one expression:

const wordCounts = new Map();

for (const word of text.toLowerCase().match(/\w+/g) ?? []) {
  wordCounts.set(word, wordCounts.getOrInsert(word, 0) + 1);
}

For simple grouping you could also reach for Map.groupBy(), which landed in 2024. The difference is that groupBy builds a new map in one shot from an iterable, while getOrInsert works on a map you're mutating over time: an event stream, a cache, or a registry that's filled lazily as requests come in.

When to use the Computed variant

The catch with getOrInsert is that its default is an ordinary argument, so it's evaluated every time, even when the key already exists. Passing [] or 0 costs essentially nothing. Passing new Set() allocates on every call. Passing await fetchConfig(id) or expensiveParse(source) is a real bug.

MDN's own example shows it plainly: calling map.getOrInsert("bar", defaultCreator("bar")) runs defaultCreator even though "bar" is already in the map, while getOrInsertComputed("bar", defaultCreator) doesn't run it at all.

So the rule of thumb is simple: use getOrInsert for cheap literals, and getOrInsertComputed whenever building the default allocates or does work. A memoization helper is the classic case:

const cache = new Map();

function getHighlighter(language) {
  return cache.getOrInsertComputed(language, (lang) =>
    createHighlighter({ lang, theme: "github-dark" }),
  );
}

The callback receives the key, so you can pass a named function instead of an inline closure. It must be callable: anything else throws a TypeError.

WeakMap is where it really shines

The same two methods exist on WeakMap, which makes per-object side data much cleaner. Say you need to attach state to DOM elements without putting properties on the nodes themselves:

const elementState = new WeakMap();

function stateFor(el) {
  return elementState.getOrInsertComputed(el, () => ({
    clicks: 0,
    lastSeen: performance.now(),
  }));
}

document.addEventListener("click", (event) => {
  const state = stateFor(event.target);
  state.clicks += 1;
});

When the element is removed and garbage collected, its entry goes with it. No cleanup code, no leaks, and no "is this initialized yet" branch anywhere in your handlers.

Can you ship it today?

Support is recent but broad. According to caniuse, getOrInsertComputed is available in Chrome and Edge 145+, Firefox 144+, and Safari 26.2+ on both macOS and iOS, and MDN marks it Baseline 2026 (newly available). That still leaves a tail of users on older Safari and Samsung Internet, so for public sites you'll want a fallback for now. Both core-js and es-shims provide polyfills, and the hand-rolled version is tiny if you'd rather avoid a dependency:

if (!Map.prototype.getOrInsertComputed) {
  Map.prototype.getOrInsertComputed = function (key, callback) {
    if (typeof callback !== "function")
      throw new TypeError("callback must be callable");
    if (this.has(key)) return this.get(key);
    const value = callback(key);
    this.set(key, value);
    return value;
  };
}

For server code, check your runtime before relying on it: node -p "typeof Map.prototype.getOrInsert" prints function when it's there. If your TypeScript lib setting doesn't know about the methods yet, a small declaration file bridges the gap:

interface Map<K, V> {
  getOrInsert(key: K, defaultValue: V): V;
  getOrInsertComputed(key: K, callback: (key: K) => V): V;
}

Note that both return V, not V | undefined, which is the other quiet win here: the non-null assertions go away along with the boilerplate.

The upsert methods aren't flashy, but they're the kind of feature you end up using every day once you know it exists. Next time you type if (!map.has(key)), stop and reach for getOrInsert instead. The MDN reference for getOrInsertComputed is a good place to start.

Astro Live Content Collections: Fresh CMS Data Without a Rebuild

Danny Holloran — Tue, 06 Oct 2026 10:12:45 +0000

Every Jamstack site eventually hits the same wall. The marketing team fixes a typo in the CMS, hits publish, and then asks why the site still shows the old copy. The honest answer is "because the site is a pile of HTML that was generated twenty minutes ago, and the rebuild is still in the queue." Webhooks, incremental builds, and on-demand revalidation all exist to paper over that gap, and each one adds another moving part you have to babysit.

Astro's answer is live content collections. They shipped as stable in Astro 6 and picked up first-class caching in Astro 7. The pitch is simple: keep the content collection API you already know, but fetch the data when the page is requested instead of when the site is built. No rebuild, no webhook, and the same typed entry.data you get from build-time collections.

Build-time vs. live: two configs, one mental model

Build-time collections live in src/content.config.ts, run their loaders during astro build, and persist the results in Astro's data store. That is still the right default. It is fast, works with MDX, and lets Astro optimize images.

Live collections live in a separate file, src/live.config.ts, and use defineLiveCollection(). They require an adapter for on-demand rendering, because the whole point is that the data is fetched per request. There are no built-in live loaders, so you write one or install a community loader.

A live loader is an object with a name and two methods: loadCollection() for lists and loadEntry() for a single item. Each returns data or an Error, never throws.

// src/loaders/changelog.ts
import type { LiveLoader } from "astro/loaders";

interface Release {
  id: string;
  title: string;
  html: string;
  updatedAt: string;
}

export function changelogLoader(opts: {
  apiUrl: string;
  token: string;
}): LiveLoader<Release, { id: string }, { tag?: string }> {
  const headers = { Authorization: `Bearer ${opts.token}` };

  return {
    name: "changelog-loader",
    loadCollection: async ({ filter }) => {
      try {
        const qs = filter?.tag ? `?tag=${encodeURIComponent(filter.tag)}` : "";
        const res = await fetch(`${opts.apiUrl}/releases${qs}`, { headers });
        const releases: Release[] = await res.json();
        return {
          entries: releases.map((r) => ({ id: r.id, data: r })),
          cacheHint: { tags: ["releases"] },
        };
      } catch (error) {
        return {
          error: new Error("Failed to load releases", { cause: error }),
        };
      }
    },
    loadEntry: async ({ filter }) => {
      try {
        const res = await fetch(`${opts.apiUrl}/releases/${filter.id}`, {
          headers,
        });
        if (res.status === 404)
          return { error: new Error("Release not found") };
        const r: Release = await res.json();
        return {
          id: r.id,
          data: r,
          rendered: { html: r.html },
          cacheHint: {
            tags: [`release-${r.id}`],
            lastModified: new Date(r.updatedAt),
          },
        };
      } catch (error) {
        return { error: new Error("Failed to load release", { cause: error }) };
      }
    },
  };
}

Then register it. The Zod schema is optional, but if you provide one it wins over the loader's generic types and validation errors come back as a typed error instead of a crash:

// src/live.config.ts
import { defineLiveCollection } from "astro:content";
import { z } from "astro/zod";
import { changelogLoader } from "./loaders/changelog";

const releases = defineLiveCollection({
  loader: changelogLoader({
    apiUrl: import.meta.env.CMS_URL,
    token: import.meta.env.CMS_TOKEN,
  }),
  schema: z.object({
    id: z.string(),
    title: z.string(),
    html: z.string(),
    updatedAt: z.coerce.date(),
  }),
});

export const collections = { releases };

Querying live data with explicit errors

On the page side you swap getEntry() for getLiveEntry() and getCollection() for getLiveCollection(). The difference that matters is the return shape: you get { entry, error } back rather than an exception, which forces you to decide what a CMS outage looks like for your users.

---
// src/pages/changelog/[id].astro
export const prerender = false;
import { getLiveEntry, render } from 'astro:content';
import { LiveEntryNotFoundError } from 'astro/content/runtime';

const { entry, error } = await getLiveEntry('releases', Astro.params.id);

if (error) {
  if (error instanceof LiveEntryNotFoundError) return Astro.rewrite('/404');
  return new Response('Changelog temporarily unavailable', { status: 503 });
}

Astro.cache.set(entry);
Astro.cache.set({ maxAge: 300, swr: 60 });

const { Content } = await render(entry);
---
<h1>{entry.data.title}</h1>
<Content />

The error union is narrow: LiveEntryNotFoundError, LiveCollectionValidationError, LiveCollectionCacheHintError, or a generic LiveCollectionError. Because the loader returned a rendered.html property, render() and <Content /> work exactly like they do for Markdown collections.

Caching is what makes this not-a-regression

Fetching from a CMS on every request is slower than serving static HTML, and the Astro docs say so plainly. That is where Astro 7's route caching comes in. Configure a provider once (the in-memory one for Node, or the experimental CDN providers for Netlify, Vercel, and Cloudflare) and pass the live entry to Astro.cache.set(). Astro pulls the loader's cache hint off it, tagging the response and setting Last-Modified for you. Multiple set() calls merge: tags accumulate, lastModified takes the newest date, and maxAge is last-write-wins.

Invalidation then becomes a tiny endpoint your CMS webhook can hit:

// src/pages/api/revalidate.ts
export async function POST({ request, cache }) {
  const { id } = await request.json();
  await cache.invalidate({ tags: [`release-${id}`] });
  return Response.json({ purged: id });
}

Notice the inversion. In the classic Jamstack setup, the webhook triggers a full rebuild. Here it purges one cache tag, and the next request fetches fresh data.

When to stay on build-time collections

Live collections give up a few things: no MDX rendering at runtime, no image optimization, and no persistence in the content layer data store. If your content changes a few times a week, build-time collections plus a deploy hook are still simpler and faster. Reach for live collections when freshness is the feature: inventory, pricing, changelogs, CMS draft previews, or filters driven by request parameters.

The nice part is you don't have to pick one for the whole site. Both kinds coexist, so your docs can stay static while the one page that always goes stale finally doesn't. Start with the content collections guide and the route caching docs, and try converting your most-complained-about page first.

Nuxt createUseFetch: One Typed API Client Without the Wrapper Boilerplate

Danny Holloran — Mon, 05 Oct 2026 10:12:38 +0000

Every Nuxt app that talks to a real backend ends up with the same problem. You call useFetch('/users') in one page, then useFetch('/orders') in another, and before long every call site is repeating the same baseURL, the same Authorization header, and the same "redirect to login on 401" logic. So you write a wrapper. Then you discover the wrapper loses some of useFetch's typing, or its generics get ugly, or you are not sure it still plays nicely with SSR deduplication.

Nuxt 4.4 shipped a first-party answer: createUseFetch and createUseAsyncData. They are factories that return a composable with the exact same signature as useFetch (or useAsyncData), just with your defaults baked in. No hand-rolled generics, no guessing about keys.

The basic factory

The factory lives in your composables/ directory like any other composable. Here is an API client for an external backend, adapted from the recipe in the Nuxt docs:

// app/composables/useAPI.ts
export const useAPI = createUseFetch({
  baseURL: "https://api.example.com",
  onRequest({ options }) {
    const { session } = useUserSession();
    if (session.value?.token) {
      options.headers.set("Authorization", `Bearer ${session.value.token}`);
    }
  },
  async onResponseError({ response }) {
    if (response.status === 401) {
      await navigateTo("/login");
    }
  },
});

Now pages just ask for data:

<script setup lang="ts">
const { data: profile } = await useAPI("/me");
const { data: orders, status } = await useAPI("/orders", { lazy: true });
</script>

useAPI returns the same data, status, error, and refresh you already know, with the same typing. Every option useFetch accepts (query, transform, pick, server, getCachedData, and so on) is still available at the call site.

One rule to remember: createUseFetch is a compiler macro. It has to be an exported declaration in composables/ (or another directory Nuxt scans). That is how Nuxt finds it at build time and injects the de-duplication keys that make SSR hydration reuse the server payload instead of fetching twice. Define it inside a component or a random utility file and you lose that.

Defaults vs. overrides

The factory has two modes, and picking the right one matters.

Pass a plain object and your options are defaults. The caller wins on any conflict:

export const useAPI = createUseFetch({
  baseURL: "https://api.example.com",
  lazy: true,
});

// Caller overrides baseURL for this one call
const { data } = await useAPI("/status", {
  baseURL: "https://status.example.com",
});

Pass a function and your options override the caller's. The function receives what the caller passed, so you decide how to merge:

// The base URL is enforced; callers cannot point this client elsewhere
export const useBillingAPI = createUseFetch((callerOptions) => ({
  ...callerOptions,
  baseURL: useRuntimeConfig().public.billingApiUrl,
}));

The function form is also the one to reach for whenever your defaults need something from the Nuxt context, like useRuntimeConfig() or useNuxtApp(). The function runs at the call site, inside setup, where a Nuxt instance exists. A plain object is evaluated once at module scope, where it does not.

A practical way to think about it: object mode for convenience ("most calls want this"), function mode for policy ("every call must have this").

Plugging in a custom `$fetch`

If you already have a configured ofetch instance from a plugin, perhaps with retry logic or logging, you can hand it to the factory:

// app/plugins/api.ts
export default defineNuxtPlugin(() => {
  const api = $fetch.create({
    baseURL: "https://api.example.com",
    retry: 2,
    retryStatusCodes: [502, 503, 504],
  });
  return { provide: { api } };
});

// app/composables/useAPI.ts
export const useAPI = createUseFetch((callerOptions) => ({
  $fetch: useNuxtApp().$api as typeof $fetch,
  ...callerOptions,
}));

Note the function form again: useNuxtApp() has to run in setup, so it cannot sit in a plain object at the top of the file.

createUseAsyncData follows the same pattern for cases where the "fetch" is not an HTTP call at all, such as a GraphQL client, an SDK, or a Supabase query, but you still want shared defaults like lazy, deep, or getCachedData.

When not to bother

If your app hits one same-origin /api route and needs no headers, plain useFetch is fine; a factory adds a file and a name for no gain. And remember that useFetch-style composables are for loading data during render. For a form submit or a button click, call $fetch (or your plugin's $api) directly. Wrapping event handlers in useAPI will not give you SSR benefits and can cause confusing caching.

Wrapping up

createUseFetch turns a pattern almost every Nuxt team reinvented into one line that keeps full typing and SSR key handling intact. If you are on Nuxt 4.4 or later, look for your existing useFetch wrappers, move them into composables/ as factories, and choose object or function mode deliberately. The createUseFetch docs and the custom useFetch recipe cover the remaining options.

Your tsconfig Is Still Written for TypeScript 5. Here's the Cleanup TS 7 Forces

Danny Holloran — Sun, 04 Oct 2026 10:12:42 +0000

Most tsconfig.json files are archaeology. Somebody copied one from a starter repo in 2021, somebody else added baseUrl so the @/ imports would work, and a third person set moduleResolution: "node" because a Stack Overflow answer said so. Nobody has touched it since, because it worked.

That stops being true this year. TypeScript 6.0 (March 2026) was a deliberate bridge release: it changed a batch of defaults and deprecated a list of legacy options. TypeScript 7.0, the Go-native compiler that went GA in July, keeps the new defaults and removes the deprecated options outright. If you upgraded to 6.0 and silenced the warnings with "ignoreDeprecations": "6.0", you didn't fix anything. You scheduled the breakage for your TS 7 upgrade.

Here's the audit, in the order it will actually bite you.

The two changes with confusing error messages

The TypeScript team called these out up front because the errors they produce don't point at the cause.

types now defaults to []. Previously, TypeScript loaded every package under node_modules/@types into the global scope. That's how process, describe, and it showed up without an import. In 6.0 and later, nothing is loaded unless you list it. The symptom is a flood of Cannot find name 'process' or Cannot find name 'describe' errors that look like a broken install.

{
  "compilerOptions": {
    "types": ["node", "vitest/globals"]
  }
}

You can restore the old behavior with "types": ["*"], but don't. The team reports that many projects saw 20 to 50 percent faster builds just from listing the types they actually use, because a typical monorepo transitively drags in hundreds of @types packages nobody imports.

rootDir now defaults to the tsconfig's directory. It used to be inferred from the common ancestor of your source files. If your sources live in src/ and you never set rootDir, your output silently moves from dist/index.js to dist/src/index.js. Nothing errors. Your package.json main field just points at a file that no longer exists.

{
  "compilerOptions": {
    "rootDir": "./src",
    "outDir": "./dist"
  },
  "include": ["./src"]
}

If you use a bundler and noEmit, this one won't affect you. If you publish a library with tsc, check it first.

The defaults that flipped quietly

These changed in 6.0 and are the baseline in 7.0:

strict is now true. If you were relying on the old false default, you'll suddenly get every strictNullChecks and noImplicitAny error at once.
module defaults to esnext, and target floats to the newest supported spec (currently es2025).
noUncheckedSideEffectImports is true, so a typo in import './polyfil' is now an error instead of a silent no-op.

The honest move with strict is to set it explicitly either way. If your codebase isn't ready, write "strict": false so the decision is visible in the file rather than inherited from a default that changed under you. Then turn on the individual checks one at a time.

The options that are gone in 7.0

These were deprecated in 6.0 and do not exist in 7.0:

Option	Replace with
`moduleResolution: "node"` / `"node10"`	`"nodenext"` for Node, `"bundler"` for Vite/webpack/Bun
`moduleResolution: "classic"`	`"bundler"` or `"nodenext"`
`baseUrl`	explicit prefixes in `paths`
`target: "es5"`, `downlevelIteration`	`es2015` or later; let your bundler handle older targets
`module: "amd"`, `"umd"`, `"system"`, `outFile`	a bundler
`esModuleInterop: false`, `allowSyntheticDefaultImports: false`	delete them; both are always on

baseUrl is the one most frontend projects hit. Almost everyone used it as a prefix for paths, but it was also a lookup root, which meant TypeScript would happily resolve import x from "utils" to src/utils.ts even though no bundler would. The fix is mechanical:

  {
    "compilerOptions": {
-     "baseUrl": "./src",
      "paths": {
-       "@/*": ["*"]
+       "@/*": ["./src/*"]
      }
    }
  }

One related improvement: 6.0 now allows moduleResolution: "bundler" together with module: "commonjs", which is the cleanest landing spot for older projects that still emit CommonJS but used node10 resolution.

Doing the migration without guessing

Run your current version with the deprecation warnings visible first. Remove ignoreDeprecations if you added it, run tsc --noEmit, and treat every warning as a ticket. For baseUrl and rootDir, the TypeScript team's experimental ts5to6 codemod will rewrite the config across a monorepo for you.

Once 6.0 is clean, 7.0 should be uneventful for the config side. If you still see odd inference differences, 6.0's --stableTypeOrdering flag makes the JS compiler order types the way the Go compiler does, so you can shake those out before switching binaries.

A tsconfig is supposed to describe what your project actually does. After this cleanup, it finally will: explicit types, explicit rootDir, a moduleResolution that matches your real runtime, and no lookup roots that resolve imports your bundler never could. The full list of changes is in the TypeScript 6.0 release notes, and it's worth one careful read before you bump the version in package.json.

Node.js Type Stripping: Run TypeScript Without a Build Step

Danny Holloran — Thu, 01 Oct 2026 10:12:31 +0000

Every Node project written in TypeScript used to carry the same small tax. You wanted to run a one-off script, so you reached for ts-node, then fought its ESM loader, then switched to tsx, then added a build step so production wouldn't depend on either. None of that was hard. It was just friction, repeated in every repo.

That tax is mostly gone. Type stripping has been on by default since Node 23.6 and 22.18, and as of Node 25.2 and 24.12 the docs mark it Stable. You can type node script.ts and it runs. The catch is that "Node runs TypeScript" is a slightly misleading headline. Node doesn't compile TypeScript. It erases it, and knowing the difference is what keeps you from hitting confusing runtime errors.

Erasing, not compiling

When Node loads a .ts, .mts, or .cts file, it hands the source to a small SWC-based module called amaro. Amaro finds the type annotations, interfaces, and type aliases and replaces them with whitespace. What's left is plain JavaScript with the exact same line and column positions, so stack traces point at the right place without source maps.

// greet.ts
interface User {
  name: string;
  visits: number;
}

export function greet(user: User): string {
  return `Welcome back, ${user.name} (${user.visits} visits)`;
}

node greet.ts

Two things this does not do. It doesn't type check: a file full of type errors runs fine as long as the JavaScript underneath is valid. And it doesn't read tsconfig.json at all, so paths, target downleveling, and every other compiler setting are ignored. Your editor and tsc --noEmit in CI are still where type safety lives. Node just stopped making you transpile before you can execute.

The syntax that breaks

Because Node only deletes code, anything in TypeScript that generates JavaScript can't work. The big four are enum declarations, namespace blocks with runtime values, constructor parameter properties, and import aliases like import Alias = Some.Namespace. Hit one and Node throws ERR_UNSUPPORTED_TYPESCRIPT_SYNTAX.

// Fails: parameter properties generate assignments
class Repo {
  constructor(private db: Database) {}
}

// Works: the same thing, written as erasable syntax
class Repo {
  private db: Database;
  constructor(db: Database) {
    this.db = db;
  }
}

Enums are the one most teams trip over. A const object with as const gives you the same autocomplete and a real runtime value:

export const Status = {
  Draft: "draft",
  Published: "published",
} as const;

export type Status = (typeof Status)[keyof typeof Status];

There used to be an escape hatch, --experimental-transform-types, that handled enums and friends. Node 26 removed it. If you need full TypeScript semantics at runtime, the docs now point you to a third-party loader like tsx. For everything else, write erasable TypeScript.

Decorators and .tsx files are also out. Decorators wait on native JavaScript support, and JSX needs a real transform.

Let the compiler enforce it for you

You don't have to memorize that list. TypeScript 5.8 added erasableSyntaxOnly, which turns every non-erasable construct into a compile error. The Node docs recommend this setup:

{
  "compilerOptions": {
    "noEmit": true,
    "target": "esnext",
    "module": "nodenext",
    "rewriteRelativeImportExtensions": true,
    "erasableSyntaxOnly": true,
    "verbatimModuleSyntax": true
  }
}

verbatimModuleSyntax matters more than it looks. Node can only strip a type import it can recognize, so you must write import type { User } from './user.ts' or import { greet, type User } from './greet.ts'. A plain import { User } is treated as a value import and fails at runtime because nothing named User exists in the emitted JavaScript. This flag makes tsc catch that before Node does.

Two more habits follow from "Node treats .ts like .js." Import specifiers need the real extension (./db.ts, not ./db), and module format follows the nearest package.json "type" field, just like JavaScript. rewriteRelativeImportExtensions lets you keep writing .ts specifiers and still emit working .js if you later publish compiled output.

If you relied on tsconfig paths for aliases like @/lib/db, switch to Node's own subpath imports. They're defined in package.json and must start with #:

{
  "type": "module",
  "imports": {
    "#lib/*": "./src/lib/*"
  }
}

import { connect } from "#lib/db.ts";

Where it fits, and where it doesn't

Type stripping shines for scripts, CLIs, internal services, and test files. Pair it with the built-in test runner and a small project can drop ts-node, tsx, and a build step entirely.

It's not for publishing libraries. Node deliberately refuses to strip types from anything under node_modules, so packages still need to ship compiled JavaScript and .d.ts files. And if your codebase leans on enums, decorators, or JSX on the server, a full transpiler remains the right tool.

The practical move this week: add erasableSyntaxOnly to an existing project and see what lights up. If the list is short, you're a few small refactors away from deleting a dependency and a build step. The Node.js TypeScript docs cover the remaining edge cases.

Compression Dictionaries: Ship Only the Diff When Your Bundle Changes

Danny Holloran — Mon, 28 Sep 2026 10:12:46 +0000

You ship a one-line bug fix. Your bundler dutifully produces app.8f3c1a.js, a brand new filename, and every returning visitor downloads the whole 270 KB file again. The browser already has 99% of those bytes sitting in its cache under the old hash, but HTTP compression has no way to say "you already know most of this." Gzip and Brotli compress each response in isolation, so a tiny code change costs a full re-download.

Compression Dictionary Transport fixes exactly that. It became a real standard as RFC 9842 in September 2025, it ships in Chrome and Edge 130+, and Cloudflare opened a beta for it in April 2026. The idea is simple: let the browser tell the server which previous response it has cached, and let the server compress the new response against it. For versioned JavaScript, the result is often a delta measured in single-digit kilobytes.

How the handshake works

There are three moving parts: a response that volunteers to be a dictionary, a request that advertises which dictionary is available, and a response compressed with it.

First, the server marks a resource as reusable with the Use-As-Dictionary header. The match value is a URL pattern describing which future requests this file can help with:

HTTP/1.1 200 OK
Content-Type: text/javascript
Cache-Control: public, max-age=31536000
Use-As-Dictionary: match="/js/app.*.js", id="app-v1"

The browser stores that response as a dictionary. The next time it requests something matching /js/app.*.js, say after you deploy app.2d9e44.js, it adds two things to the request: new encodings in Accept-Encoding, and the SHA-256 hash of the dictionary it holds.

GET /js/app.2d9e44.js HTTP/1.1
Accept-Encoding: gzip, br, zstd, dcb, dcz
Available-Dictionary: :pZGm1Av0IEBKARczz7exkNYsZb8LzaMrV7J32a2fFG4=:
Dictionary-ID: "app-v1"

dcb is dictionary-compressed Brotli and dcz is dictionary-compressed Zstandard. If the server has a delta prepared for that exact hash, it responds with one of them:

HTTP/1.1 200 OK
Content-Encoding: dcz
Vary: accept-encoding, available-dictionary

The Vary header is not optional. Without it, a CDN could happily serve a dictionary-compressed body to a client that never had the dictionary, and that client gets garbage. Also note that Dictionary-ID is a convenience label; the server must still verify the Available-Dictionary hash before trusting that the client has the bytes it thinks it has.

Building the deltas at deploy time

The practical pattern for static assets is to precompress at build time. For every new bundle, compress it against the previous release's version of the same file and store the result next to it. The Zstandard and Brotli CLIs both accept a dictionary:

# previous release is the dictionary, new build is the payload
zstd -19 --patch-from=dist-prev/app.8f3c1a.js dist/app.2d9e44.js -o dist/app.2d9e44.js.dcz-raw

# the hash the browser will send in Available-Dictionary
openssl dgst -sha256 -binary dist-prev/app.8f3c1a.js | base64

The dcz and dcb formats wrap the compressed stream with a short header that embeds the dictionary hash, so the browser can confirm it decoded against the right file. Tooling like Cloudflare's implementation handles that framing for you; if you roll your own, follow the RFC's format section rather than guessing.

On the server, the logic is a lookup: does a delta exist for this path and this dictionary hash? If yes, serve it. If no, fall back to normal Brotli.

import { createReadStream, existsSync } from "node:fs";

app.get("/js/:file", (req, res, next) => {
  const hash = req.get("available-dictionary")?.slice(1, -1); // strip the colons
  const accepts = req.get("accept-encoding") ?? "";
  const delta = hash && deltaIndex.get(`${req.params.file}:${hash}`);

  res.vary("Accept-Encoding").vary("Available-Dictionary");
  res.set("Use-As-Dictionary", 'match="/js/app.*.js", id="app"');

  if (delta && accepts.includes("dcz") && existsSync(delta)) {
    res.set({ "Content-Encoding": "dcz", "Content-Type": "text/javascript" });
    return createReadStream(delta).pipe(res);
  }
  next(); // regular static handler serves br/gzip
});

Notice the new file also sends Use-As-Dictionary. Each release becomes the dictionary for the next one, so a returning visitor keeps getting deltas across deploys instead of just one.

How big is the win? In Cloudflare's lab test, a 272 KB JavaScript asset was 92.2 KB with gzip. Compressed against its previous version with dcz, it came out at 2.6 KB. Your numbers depend entirely on how much actually changed between builds, but for frequent small deploys that ratio is the whole point.

Shared dictionaries for first visits

Deltas only help returning visitors. For first loads, you can ship a separate dictionary built from content common across your pages, like your HTML boilerplate or shared component markup, and hint it to the browser at idle priority:

<link rel="compression-dictionary" href="/dictionary.dat" />

Or with a response header: Link: </dictionary.dat>; rel="compression-dictionary". The browser downloads it in the background, and later page navigations can be compressed against it.

The fine print

A few rules will bite you if you skip them. Dictionaries must be same-origin with the resources they compress, and dictionary-compressed responses must be same-origin with the document or served with proper CORS. If you use <link rel="compression-dictionary"> with a Content Security Policy, connect-src has to allow the dictionary URL. Only secure contexts participate.

Browser support is the bigger caveat. Chromium browsers support it today, Firefox has an active implementation bug, and Safari has not announced support. That is fine, because the design degrades gracefully: browsers that don't send dcb or dcz in Accept-Encoding never see a dictionary response and just get your normal Brotli. You are adding a fast path, not a dependency.

If you deploy often and your users come back often, this is one of the rare performance wins that gets bigger the more you ship. Start with your largest versioned JavaScript bundle, precompress one delta per release, and measure transfer size in DevTools on a repeat visit. The MDN guide to compression dictionary transport and the Chrome team's write-up cover the remaining details.

Uint8Array toBase64 and toHex: Stop Round-Tripping Bytes Through btoa

Danny Holloran — Fri, 25 Sep 2026 10:13:48 +0000

Every codebase that touches binary data has the same little helper buried in a utils folder. It takes a Uint8Array, spreads it into String.fromCharCode, hands the result to btoa, and hopes for the best. Its sibling goes the other way with atob and a charCodeAt loop. And somewhere nearby there's a third helper that maps each byte to toString(16).padStart(2, '0') so you can print a hash.

None of those helpers are wrong, exactly. They're just working around the fact that btoa and atob were designed for strings, not bytes. That gap is now closed: Uint8Array has native methods for base64 and hex, in both directions, and they've been Baseline across current Chrome, Firefox, and Safari since September 2025.

The new methods at a glance

There are six of them, split into three pairs:

bytes.toBase64(options) and Uint8Array.fromBase64(string, options)
bytes.toHex() and Uint8Array.fromHex(string)
target.setFromBase64(string, options) and target.setFromHex(string) for writing into an existing buffer

Here's the old helper next to its replacement:

// Before: works, but only by pretending bytes are Latin-1 characters
function bytesToBase64(bytes) {
  return btoa(String.fromCharCode(...bytes));
}

function base64ToBytes(b64) {
  return Uint8Array.from(atob(b64), (c) => c.charCodeAt(0));
}

// After
const b64 = bytes.toBase64();
const decoded = Uint8Array.fromBase64(b64);

The "after" version isn't just shorter. The spread in String.fromCharCode(...bytes) passes every byte as a separate function argument, so a large file can blow past the engine's argument limit and throw a RangeError. The native methods don't have that ceiling, and they skip the intermediate "binary string" entirely.

Hex gets the same treatment, which makes Web Crypto output a one-liner:

async function sha256Hex(text) {
  const data = new TextEncoder().encode(text);
  const digest = await crypto.subtle.digest("SHA-256", data);
  return new Uint8Array(digest).toHex();
}

await sha256Hex("hello");
// '2cf24dba5fb0a30e26e83b2ac5b9e29e1b161e5c1fa7425e73043362938b9824'

Uint8Array.fromHex() goes the other direction and throws a SyntaxError on odd-length strings or non-hex characters, so you get validation for free instead of silently producing NaN bytes.

base64url and padding without string surgery

Standard base64 uses + and /, which break in URLs and filenames. The usual fix is a chain of .replace() calls to swap in - and _ and strip the trailing =. Now it's an option:

const id = crypto.getRandomValues(new Uint8Array(16));

const token = id.toBase64({ alphabet: "base64url", omitPadding: true });
// e.g. 'q3N8y0Zp1VbX-7k2_JmR4g'

Decoding takes the same alphabet option. That makes peeking inside a JWT payload pleasantly boring, since JWT segments are base64url with the padding removed:

function readJwtPayload(jwt) {
  const [, payload] = jwt.split(".");
  const bytes = Uint8Array.fromBase64(payload, { alphabet: "base64url" });
  return JSON.parse(new TextDecoder().decode(bytes));
}

That works because the default lastChunkHandling mode, "loose", accepts a final chunk of two or three characters without padding. If you're validating input you don't control and want to reject anything non-canonical, pass lastChunkHandling: 'strict': the last chunk must then be padded to four characters, and any leftover "overflow bits" must be zero. Decoding also ignores ASCII whitespace, so base64 that was wrapped across lines in a PEM file or an email decodes without a cleanup pass.

One more quiet win: because you're decoding to bytes, not to a string, there's no more InvalidCharacterError from feeding btoa a string with an emoji in it. Encode text with TextEncoder first, then call toBase64(), and UTF-8 just works.

Decoding into memory you already have

The setFrom* methods write into an existing Uint8Array and return { read, written } so you know how much input was consumed and how many bytes landed. That's handy when you're reusing a buffer or decoding base64 that arrives in pieces:

const buffer = new Uint8Array(1024);
let offset = 0;
let pending = "";

function onChunk(text) {
  pending += text;
  const { read, written } = buffer
    .subarray(offset)
    .setFromBase64(pending, { lastChunkHandling: "stop-before-partial" });
  offset += written;
  pending = pending.slice(read);
}

With "stop-before-partial", an incomplete trailing chunk is left alone instead of being decoded early or throwing, so the next network chunk can finish it. The read count tells you exactly where to resume.

When to reach for them (and when not yet)

If your app targets current evergreen browsers, you can use these today and delete the helpers. On the server, check your runtime version before you rip out Buffer.from(x, 'base64'). Node's Buffer still works fine, but these methods give you one API that runs the same in the browser, Deno, Bun, and edge runtimes.

For older targets, feature-detect and fall back:

const toBase64 =
  typeof Uint8Array.prototype.toBase64 === "function"
    ? (bytes) => bytes.toBase64()
    : (bytes) =>
        btoa(Array.from(bytes, (b) => String.fromCharCode(b)).join(""));

Or pull in a polyfill: core-js covers the full set, and the es-arraybuffer-base64 shim does too.

The takeaway is small but satisfying: bytes can finally stay bytes. The next time you reach for btoa, check whether what you actually have is a Uint8Array. If it is, toBase64() is almost certainly the better call. The MDN reference for Uint8Array.fromBase64() covers every option in detail, including the edge cases around padding and overflow bits.

import defer: Lazy Modules Without Going Async

Danny Holloran — Tue, 22 Sep 2026 10:12:03 +0000

Every codebase has that one import. A syntax highlighter, a PDF renderer, a date-formatting library with a locale table the size of a small novel. It sits at the top of a file, it gets evaluated the moment the module graph runs, and it is needed on exactly one code path that most users never hit.

The usual fix is await import(). It works, but it charges rent: the function that needed the module becomes async, and so does its caller, and its caller's caller. You wanted to move some work later in time, and instead you rewrote a call stack. import defer is the piece that was missing, and it is riding along with ES2026.

Linked up front, evaluated on first touch

The syntax is a single keyword in one position:

import defer * as ts from "typescript";

function compileFile(path) {
  // The typescript module graph evaluates here, on first property access.
  return ts.createProgram([path], {});
}

Nothing from typescript runs at startup. The module and its dependencies are still resolved, fetched, parsed, and linked, so a missing file or a bad named import still blows up immediately rather than lurking. What is deferred is evaluation: the top-level code only runs the first time you read a property off ts. If compileFile is never called, that graph never executes.

That distinction is the whole value proposition. import() defers everything, which is why it has to be async. import defer defers only the synchronous part that can safely be moved, so property access stays synchronous and nothing above it needs to change colour.

Only the namespace form works. There is no import defer { createProgram } from "typescript" and no default form, because the namespace object is the thing doing the work — evaluation is triggered by a property read, and a destructured binding has nothing left to intercept.

The parts that will surprise you

The deferred namespace is effectively a proxy, and the list of operations that trip evaluation is broader than "read a property". Reading a key triggers it, but so does "value" in ns, Object.keys(ns), a for...in, Object.getOwnPropertyDescriptor, and even delete ns.value or Object.defineProperty on it — the operation fails, since the namespace is sealed, but evaluation happens anyway. Object.isSealed() and Object.isFrozen() enumerate keys, so those count too.

Which also means this defeats the whole thing:

import defer * as squares from "./squares.js";

const { getSquare } = squares; // evaluates immediately — you read a property

Three behaviours are worth committing to memory:

Top-level await opts out. Reading a property is synchronous, so it cannot wait on an async module. A module containing top-level await is evaluated eagerly, along with whatever its evaluation requires. The rest of the graph can still stay deferred, but do not assume defer bought you anything if the target awaits at the top level.

Side effects move. If a module installs a polyfill, registers a custom element, or patches a global, deferring it means that side effect now happens at an unpredictable moment, or never. Those modules should stay on a plain import.

Evaluation errors are cached and synchronous. If the deferred module throws while initializing, the throw comes out of whatever expression touched the namespace, catchable with a normal try...catch. Every later access rethrows the same error rather than retrying.

One more detail that saves a debugging session: the namespace deliberately does not expose an export named then, even after evaluation. Without that carve-out, handing the namespace to Promise.resolve() would look like a thenable and force evaluation as a side effect of promise resolution.

Where you can actually use it

Tooling got there first, as usual. TypeScript has understood the syntax since 5.9, and Babel, webpack, and Prettier all handle it. Bun and Deno ship it enabled by default. In browsers, V8 has had it behind a flag with an Intent to Ship filed in September 2026, WebKit has it implemented, and Gecko has signalled support — so treat it as landing rather than landed, and check the compatibility table before you rely on it in production.

The honest use case today is server-side and CLI code, where Bun, Deno, and a bundler give you a straight path. Go find the heaviest module on your cold-start path that is only needed conditionally, swap the import, and measure. If it turns out the module has top-level await, or installs something on import, you have learned something useful about your dependency either way.

Turbopack's Persistent Build Cache Only Helps If Your CI Keeps It

Danny Holloran — Mon, 21 Sep 2026 10:06:01 +0000

You upgrade to Next.js 16.3, read that Turbopack's persistent file system cache is now on by default for next build, see a chart claiming up to 5.5x faster builds, push to CI, and watch your pipeline take exactly as long as it did yesterday. Nothing is broken. The feature is doing precisely what it says. The problem is that "persistent" means persisted to a directory, and your build container throws that directory away the moment it exits.

This is the least glamorous kind of performance work: the speedup is real, it's free, and collecting it is an infrastructure chore rather than a code change.

The cache is a directory, not a feature flag

Turbopack has been persisting its incremental compilation cache to disk for next dev since 16.1. In 16.3 the same mechanism graduated for next build, and both are enabled by default:

// next.config.ts
import type { NextConfig } from "next";

const nextConfig: NextConfig = {
  experimental: {
    turbopackFileSystemCacheForDev: true, // default
    turbopackFileSystemCacheForBuild: true, // default
  },
};

export default nextConfig;

Dev writes to .next/dev/cache/turbopack, builds write to .next/cache/turbopack. On the second build Turbopack reads those entries off disk before compiling anything new, so you only pay for what changed. Vercel's published numbers span a wide range depending on how much of the route graph the change touches: nextjs.org went from 21s cold to 9.2s warm, vercel.com/home from 66s to 46s, and vercel.com/geist from 30s to 5.5s.

Every one of those numbers assumes .next/cache survives between runs. Restoring it in GitHub Actions is a handful of lines:

- uses: actions/cache@v4
  with:
    path: |
      ~/.npm
      ${{ github.workspace }}/.next/cache
    key: ${{ runner.os }}-nextjs-${{ hashFiles('**/package-lock.json') }}-${{ hashFiles('**/*.[jt]s', '**/*.[jt]sx') }}
    restore-keys: |
      ${{ runner.os }}-nextjs-${{ hashFiles('**/package-lock.json') }}-

The restore-keys fallback matters more than the exact key. If your lockfile is unchanged but source files moved, you still want the previous cache as a starting point instead of a cold compile.

Docker is the case that quietly eats this. A containerized build starts from a clean layer, so unless you explicitly mount a cache or use RUN --mount=type=cache, .next/cache is empty on every single build and Turbopack spends time writing a cache that nothing will ever read. If that describes your setup and you don't plan to fix it, turn the thing off rather than paying for it:

experimental: {
  turbopackFileSystemCacheForBuild: false,
}

That's the actual decision in front of you: persist the directory, or opt out. Leaving it on with nothing to restore is the one configuration that costs you something and returns nothing.

The dev-memory win needs no setup at all

The other half of the release is the part you'll notice without touching any config. Because cached results are now safely on disk, Turbopack can evict them from memory instead of holding every visited route forever. After compiling 50 routes, Vercel measured its own dashboard app dropping from 21.5 GB to 2 GB, and nextjs.org from 4,600 MB to 840 MB.

That's roughly a 90% and 82% reduction, and it lands in a moment when your dev machine is more crowded than it used to be. A coding agent, a TypeScript server, a linter, and a test watcher are all competing for the same RAM as your bundler. Eviction requires the dev file system cache to be enabled, and both are on by default. The escape hatch exists if you're debugging cache behavior itself:

experimental: {
  turbopackMemoryEviction: false, // default is 'auto'
}

Your mileage genuinely varies here. The reduction depends on the size of your route graph, how much of it you touched, and how long the session ran. A three-route side project has nothing to evict.

Two smaller things worth a look

The React Compiler has been stable in Next.js since 16.0, but only as a Babel transform, which meant large apps waited on JS execution during builds. The React team shipped a native Rust port, and Turbopack now wires it up behind an experimental flag with early tests on large apps showing 20-50% compilation wins:

const nextConfig = {
  reactCompiler: true,
  experimental: {
    turbopackRustReactCompiler: true,
  },
};

Turbopack also picked up Vite's import.meta.glob, which is a small quality-of-life upgrade for anyone hand-maintaining a list of content files:

const posts = import.meta.glob("./posts/*.mdx");

for (const path in posts) {
  const post = await posts[path]();
}

Pass eager: true to import each match immediately. It's Turbopack-only, so it won't work if you're still building with --webpack.

Of the four, the build cache is the one with a real chance of being invisible to you. Before you file the 16.3 upgrade as done, go look at whether .next/cache actually survives a CI run. If it doesn't, you've been paying for a cache you never read.

Sources: the Turbopack 16.3 release post, the turbopackFileSystemCache reference, and the CI build caching guide.