Then Vercel shipped the scoreboard.

What is-agentic.com does

is-agentic.com measures how well an agent can discover, read, and use a public website. The scan runs on Ora's agent-readiness research, and Vercel wraps it in a public report with observed agent journeys and a fix-it prompt.

The scoring is applicability-aware, which is the part I care about. Essential checks share an 80-point pool, recommended checks share 20, and emerging signals can add a capped 5-point bonus without ever becoming a requirement. Checks that do not apply to your site get excluded instead of counting against you. So a static portfolio and a public API surface get graded on what they actually are, not against one universal checklist. The methodology page spells out the model, and it is worth reading before you argue with a number.

Running it

There is a CLI, so I did not have to open a browser:

npx is-agentic agnelnieves.com

It returns a stored report if one exists, or kicks off a scan and waits. Add --json and you get the raw API response with structured errors, which is the shape an agent wants when it runs this as a step in its own loop rather than reading a terminal.

That detail is the whole point. The report API answers Accept: text/markdown, follows RFC 9457 for its error bodies, and exposes a read-only MCP server at https://is-agentic.com/mcp with three tools for pulling a report, the methodology, and the integration docs. The tool that grades your site for agent-readiness is built to be read by agents. Which is the joke Chris made better than I can:

The checks lined up with the work

Going through the essential group felt like reading back my own commit list. The status-code and error-shape checks map to the JSON error helper I added across the API. The discovery checks map to the OpenAPI spec and the llms.txt entry that now points at it. The markdown-negotiation check is the Accept: text/markdown proxy and the Vary header I set on every negotiated route. The 404 check is the not-found page that returns a real 404 with links back to llms.txt, the sitemap, and the OpenAPI spec.

I did not build those things because a tool told me to. I built them from a hand audit, then a tool showed up that grades the same fundamentals. That is the useful signal here: the checks are not exotic agent tricks, they are ordinary web hygiene an agent happens to depend on. Accurate status codes. HTML that means something. Docs that describe what a service can do. An agent needs those for the same reason a screen reader does.

Where I'd send you first

If you own a public site, run the CLI once and read the essential failures before anything else. The recommended and bonus tiers are where you chase points; the essential pool is where an agent actually gets stuck. Then hand the fix-it prompt to whatever coding agent you use and let it close the gaps, which is the agentic-fixing-agentic loop the announcement is pointing at.

The docs cover the report API, rate limits, and the MCP server. The about page is honest about the limits: a score is a public snapshot, not a certification, and automated checks can be wrong, so read the evidence in context. I like that they said so.

I went in expecting to defend my recent work against a stricter grader. I came out with a second opinion that agreed with the audit I already trusted, plus an API I can wire into the CLI behind ssh agnelnieves.sh later. Good week for the robots reading this.

I curled the live HTML. promptway.com/blog said its canonical was https://promptway.com. So did /authors. So did /authors/agnel-nieves, /authors/diego-ferraro, and the rest of the writer pages. Google was doing exactly what I asked: treating the archive and the writer pages as copies of the homepage, and refusing to index them.

This is the sequel to From Invisible to Indexed. That piece was about the domain serving the wrong product. This one is about the product serving the wrong address on its own pages.

What a "proper" canonical actually means

The status is not an error. Google is saying: this URL has a canonical pointing somewhere else, we agree, we will not index this one. When that is a /blog/slug.md alternate, or a trailing-slash redirect, you want that outcome. When it is /blog, the page you put in the sitemap as the archive, you do not.

I had done the sitemap work. I had index, follow on those routes. None of that matters if the <link rel="canonical"> says "the real page is /."

The Next.js metadata docs are explicit about this. Metadata objects shallow-merge down the tree, and nested fields like alternates get replaced by the last segment that defines them. They do not get replaced by a page that never mentions them. A root layout with alternates.canonical: "/" becomes the canonical of every child that forgets to set its own.

I had set self-canonicals on /about, /tools, /subscribe, the pillar pages, and every article. I had not set them on /blog, /authors, or /authors/[slug]. Those three inherited the homepage. Production HTML confirmed it.

og:url had the same leak. The root layout set openGraph.url: "/", and pages that never defined their own openGraph object inherited the homepage as the social URL. Google treats og:url as a secondary canonical hint. I pulled that field off the root layout too.

The four reprints pointing the wrong way

The Search Console bucket also held four articles I had published first here and then reprinted on Promptway with canonical pointing back:

• From Invisible to Indexed
• Optimizing Your Site for AI Agents and LLMs
• Optimizing for SEO, AEO, GEO, and AI Search in 2026
• Connecting Claude to Google Ads and GA4 via MCP

That is the HackerNoon pattern. The original keeps the credit. I wrote Getting Your Writing Seen Beyond Your Own Site arguing the opposite for the publication: Promptway is the hub, everywhere else is a spoke. I had applied the rule everywhere except to my own reprints.

So I flipped them. Promptway now self-canonicalizes. The copies on this site declare canonical at the Promptway URL, drop out of this sitemap, and show a visible "Originally published on Promptway" line in the header. llms.txt here lists the Promptway URL too, so agents that land on this domain still get pointed at the hub.

If you keep a reprint with an off-site canonical, do not submit it in your sitemap. Submitting it says "index this URL." The page itself says "index that other URL." Search Console will file the contradiction under the same status that started this post.

The fix, in the order I would do it again

1. Do not set canonical or og:url on the root layout. Keep feed auto-discovery there if you want. Put the homepage canonical on app/page.tsx.
2. Give every indexable route a self-canonical. Archive, writers index, writer pages, pillars, tools, about, subscribe. If a page is in the sitemap, it needs its own address.
3. Curl the rendered HTML. Do not trust the source file. I used Googlebot as the user agent and grepped for rel="canonical". The leak was obvious in one pass.
4. Decide the hub before you syndicate. If Promptway is the home copy, this domain points there. If the personal essay is the home copy, do not put Promptway in the sitemap for that slug.
5. Give markdown alternates a Link: rel="canonical" header pointing at the HTML article. I want /blog/<slug>.md crawlable for agents. I do not want it competing as a search result.

The www, http, trailing-slash, and *.vercel.app copies were already 308ing to the apex. Those were fine. The bug was inside the HTML I was proud of.

What I am watching now

After deploy I will request indexing on /blog, /authors, and each writer page on Promptway. The four flipped articles get the same request there. On this site, those four URLs should move into "Duplicate page with proper canonical tag" and stay there. That is the correct status for a spoke.

I do not have the recrawl numbers yet. I will update this if Google disagrees with the new tags. Last time the domain pointed at the wrong product, the machines believed the tag. I am betting they will believe it this time too.

The real reason

I keep starting side projects. Some of them die. Others few stick. The ones that stick almost always want to live near my personal site, because they share the same brand, the same writing, the same identity. The terminal CLI behind ssh agnelnieves.sh is the obvious example. It reads from this site's API, it carries my voice, it is the same project in a different shape. But sometimes they have nothing to do with React or Tailwind, and it should not have to pretend to.

So the actual problem the monorepo solves for me is not Google scale or Vercel scale or any other scale. I just wanted a single place where my personal stuff lives, and I want each piece to stay clean and separate without me having to invent a new repo every time an idea shows up. Compartmentalize. Separate the concerns. Keep things tidy. Make the next thing cheap to start.

Before this week, the layout was a Next.js app with a Rust CLI in a sibling folder, sharing one package.json that did not care about it. That worked until I started writing down all the other things I want to ship from here, and the folder names started overlapping.

What I'm planning to add

These are the side projects that are already drawn on a napkin somewhere:

• An automatic resume generator. The data lives here already (work history, projects, links). I want to feed it into a Resume builder package that renders to PDF, to a /resume page, and to a JSON endpoint for the CLI, all from one source. Maintaining up to date resumes are a huge pain of mine, so one of those things which is worth automating.
• A social media post pipeline. Take a blog post I just published, generate the X thread, the LinkedIn version, and the headline-friendly image, all from code. Tag what posted where so nothing gets sent twice.
• More CLI commands. The Rust binary is going to grow. Just for fun.
• Probably something with AI agents. Some helper that drafts things based on my writing history.
• Games, ideas, whatever else shows up.

I do not want to make one of those a folder inside src/. Not because it would not work, but because they are not part of the Next.js app and they should not have to be. They are their own thing. They should have their own dependencies, their own build, their own deployments if they need one. A monorepo was the cheapest way I know to give each of them its own room without making me run bun init in a new GitHub repo every time and then forgetting which one had the latest version of my bio.

What the layout looks like now

.
├── apps/
│   ├── web/         the Next.js site you are reading
│   └── cli/         the Rust binary behind ssh agnelnieves.sh
└── packages/
    └── tsconfig/    shared TypeScript presets, room for more

apps/ is for things I ship. packages/ is for things those apps share. Right now there is only one shared package, on purpose. I do not want to invent abstractions before they have a second consumer. The day the resume generator and the social media tool both want the same "load my blog posts" helper, I will pull it into packages/content and let both of them depend on it. Until that day, it stays inside the Next.js app.

The tooling underneath is the same Rust-first stack I have written about before. Bun for the lockfile and the workspaces. Turborepo for the task graph. Biome and oxlint for the linters. Cargo for the Rust side. None of that is new. What is new is that they all sit inside one turbo run, and the cache means that editing a blog post does not re-typecheck the CLI, and editing the CLI does not rebuild the site. That is the whole point.

If you want the numbers (I do, because I like metrics): a clean rebuild with nothing changed runs in 67 milliseconds across both apps. That is the cache talking. The first cold build is about 80 seconds, mostly because the Rust binary is link-time optimized. Subsequent commits are nearly free. Pre-commit hooks stay out of my way. That is the day-to-day payoff.

What I almost talked myself out of

A few times during the migration I thought "this is too much for a personal site." It would have been faster to keep going with the old layout for another year. The Rust CLI was already working. Nothing was actually broken.

What flipped me back was looking at the list of side projects I had stopped because they did not have a home. Three of them were dead by the same path: I wanted to ship a thing, I did not want to create a new repo for it, I tried to wedge it into this site as a folder, it felt wrong, I lost interest. The friction was not the code. The friction was that I did not have a clean place to put it. Sometimes my ideas/side projects are just experimental. Just as a way to do something fun or different.

A monorepo is, for me, a way of pre-committing to that clean place existing. The next time I want to start a small thing, it goes in apps/whatever-it-is or packages/whatever-it-is. I do not have to make any decisions about hosting, repo naming, or where it should live. The decision is already made.

Things that broke, briefly, so future me knows

There were three real hitches. I am writing them down because I will hit them again.

The first was a hoisting thing. The Next.js code imported viem, but viem was not in the package.json. It had been getting pulled in transitively through another package, and the flat node_modules made it look like it was installed. The minute I turned on bun workspaces, bun switched to isolated installs, and viem was no longer reachable from where the code expected it. The fix is one line. The lesson is that workspaces will surface every latent assumption your old install had been quietly covering for. Treat them as bugs the workspaces helped you find, not as new problems the workspaces caused.

The second was Vercel. Next.js 16 plus bun's isolated install plus Vercel's monorepo defaults collide in a way that the docs do not warn you about. The build fails locally and on Vercel until you set the project's Root Directory to apps/web in the Vercel dashboard and pin turbopack.root and outputFileTracingRoot in next.config.ts. The Vercel CLI cannot change Root Directory for you. You have to click it in the dashboard. I spent an embarrassing amount of time discovering this.

The third was that vercel link from inside apps/web/ overwrites your .env.local with whatever the Vercel project has. If you had local-only secrets in there, they are gone. Back up first.

If you ever do this migration on your own site and want the working version of next.config.ts, the relevant bit lives in the actual repo and is referenced in the toolchain doc.

What I want this to be

I want this site to be the thing I tinker with when I am bored, without it feeling like I am about to make a mess. I want every side project to have a room. I want the resume to update itself the next time I add a project. I want the CLI to grow without dragging the website along with it. I want to add a third runnable thing in two months without thinking about it for more than five minutes.

A monorepo is just the shape that makes that possible without making me feel like I am building infrastructure when I should be writing.

If you are one person and you keep starting things that go nowhere because they do not have a home, I would genuinely consider doing this. The migration is a single afternoon. The rest of the time, it stays out of your way and just lets you start the next thing.

Related

• Rust owns the JavaScript toolchain in 2026
• Building a terminal portfolio you can SSH into
• Turborepo
• Remotion (how packages/video at basement works)

Google published its Optimizing your website for generative AI features on Google Search guide. The headline is short: there is no special markup for AI Overviews or AI Mode. They use the same index as classic Search. If your site is fast, indexable, well structured, and useful, it is also AI search ready.

I audited this site against that guide, ran Lighthouse via the Node CLI, and patched what came back. Mobile homepage, before and after:

Four of five Lighthouse categories at 100. Page weight down 93%. LCP down 86%.

If you want the executable version of this post, the companion guide opens with an agent prompt block so you can paste it into Claude, Cursor, or any other coding agent and have it walk you through the same audit on your own site.

SEO vs AEO vs GEO: what the letters actually mean

These are not three different stacks. They are layers. Google's own guide confirms that AI Overviews and AI Mode rank from the same index as classic Search. AEO is SEO plus structured answers. GEO is AEO plus machine readable discovery for engines outside Google's ecosystem.

There is no AI specific markup that flips a switch. The work is foundational: be fast, be indexable, be unambiguous about what you are.

What was already in place

Before this session, the site already had the following baked into the Next.js metadata API and route handlers:

• Per page metadata. Title, description, canonical, OpenGraph, and Twitter card on every route. The root layout uses a title.template so child pages don't repeat the brand suffix.
• Structured data (JSON-LD). WebSite and Person on the root, BlogPosting and BreadcrumbList on blog posts, CreativeWork on project pages.
• sitemap.xml generated from blog posts, projects, decks, and tags via src/app/sitemap.ts.
• robots.txt with allow rules for GPTBot, Google-Extended, ChatGPT-User, Applebot-Extended, anthropic-ai, ClaudeBot, PerplexityBot, Bytespider, and cohere-ai. The same file blocks my x402 paywall endpoints under Disallow: /api/x402/ so they stay out of the index.
• Three feed formats. RSS, Atom, and JSON Feed. Different syndicators and AI ingestion paths favor different formats.
• llms.txt and llms-full.txt routes. Google has now publicly said it does not read these. Other engines may. The routes are cheap to keep.
• IndieAuth, webmention, and h-entry microformats. The indie web identity signals that compose into a single content graph across small sites.
• E-E-A-T signals. sameAs links pointing at my X, LinkedIn, and GitHub. Bylines. Reading time. Last modified timestamps. Tags. Author photo via OG image.

A separate AI optimization guide already documents those routes. This post is the audit companion: what to do after that foundation is in place.

What Google's guide says NOT to do

The guide spends real time on what to skip. Worth flagging up front, because the urge to over engineer for AI search is real:

• No AI specific markup. Google does not read llms.txt, special meta tags, "AI friendly schema," or any other invented marker.
• No content chunking. Don't break paragraphs into Q&A shards "for AI parsers."
• No content rewriting. Don't tone down your prose to sound machine friendly. Write for humans.
• Don't over rely on structured data. Use it where it earns rich result formats. Don't bolt FAQ schema on every page hoping for a citation lift.
• Don't pursue inauthentic mentions. Backlink for AI citation is the new keyword stuffing.

Most of the foundation list above sits inside what Google considers SEO already, even though some of it (microformats, IndieAuth, multiple feed formats) leans more web of data than ranking.

The discoverability fixes

Google Search Console verification via DNS TXT

The site was sending verification: {} in the root metadata. Google's guide flags Search Console verification as the one explicit must do. The wrinkle: my domain's nameservers point at Vercel, not at the registrar's cPanel DNS panel where an old TXT record had been sitting unnoticed for months. A quick dig +short TXT agnelnieves.com returned nothing for that record, which confirmed the registrar panel was a dead config.

Added the verification TXT in Vercel's DNS dashboard, then verified the Domain property in Search Console. Domain property covers apex, www, http, https, and every subdomain in one shot, so I removed the redundant https://www.agnelnieves.com/ URL prefix property right after.

Removed the inline <script type="text/llms.txt">

Old habit from a year ago when llms.txt was being floated as a real standard. Google has now confirmed it does not read it. The route at /llms.txt stays for other engines; the duplicate inline block in <head> is gone. Smaller HTML, less to argue about.

Bing IndexNow ping on blog content changes

Google ignores IndexNow. Bing and Yandex run it, and Bing powers ChatGPT's web search, Copilot, and DuckDuckGo. For a personal site that publishes occasionally, this is the difference between "indexed within hours" and "indexed within days."

Three pieces:

1. A key file at /public/<32-char-key>.txt so api.indexnow.org can verify ownership at the apex.
2. A scripts/indexnow.mjs that reads the push's git diff, filters to published blog posts, and POSTs the changed URLs.
3. A .github/workflows/indexnow.yml that only triggers when files under src/content/blog/** change, so code only pushes don't fire it.

The whole thing is about 90 lines and is a no-op when content hasn't changed.

The accessibility fixes

Multiple <h1> regressions

A third party SEO scan reported "more than one h1 tag, 7 instances." The h1 was creeping in from places that should have been h2 or h3:

• ProjectCard.tsx rendered each project title as h1. Pages that list projects had 1 + N h1s.
• Deck title slides used h1 even though the deck page already owned the page h1.
• The MDX components mapping rendered markdown # as h1, which would silently re-introduce the bug when any new blog post started with # Heading.
• An unused LandingIllustration had a leftover h1.

All demoted in one commit. The MDX one is load bearing because it prevents the bug from recurring.

Missing alt text on the dither shader

The site has a custom canvas dithering effect over photos. Its component was wrapping <img alt=""> (empty alt, decorative) inside a <div role="img" aria-label={alt}>. Screen readers handle this correctly because the outer div has the label, but strict SEO scanners only inspect the <img alt> and reported 10 missing alt instances across pages. Fix: put the real alt on the <img>, drop the wrapper's role and aria-label to avoid double announcement. One change, every page benefits.

Logo link missing aria-label

<Link href="/"><Logo /></Link> in MainNav.tsx rendered an SVG with no text node, so the link had no accessible name. That was the single root cause of both:

• link-name failing in Accessibility (-5 points).
• agent-accessibility-tree failing in Agentic Browsing (-33 points), Lighthouse's new category for AI agent compatibility.

Added aria-label="Home". Both scores went to 100 in the next audit.

The performance fixes

The Lighthouse mobile audit, baseline

Run via the Node CLI:

bunx lighthouse@latest https://agnelnieves.com/ \
  --output=json --output-path=./home-mobile.json \
  --quiet --chrome-flags="--headless=new --no-sandbox" \
  --form-factor=mobile

First run, mobile, homepage: Performance 63, LCP 43.2 s, total weight 14,561 KiB.

A 43 second LCP on a portfolio site is not subtle. The top 15 heaviest requests pointed at it: a 3.2 MB MP3 of background music and 14 raw JPEGs averaging 700 KB each.

Lazy init the background music

PowerButton.tsx was creating new Audio("/sounds/Future We Forgot.mp3") inside a useEffect, which triggers a full preload on mount even if the user never clicks the button. PowerButton renders inside the LogoEngraving bar in every page's chrome, so 3.3 MB of audio loaded on every route.

Lazy instantiate on the first toggle to "on" instead of on mount. The Audio object only exists if the user opts in.

Re-encode the MP3 itself

The MP3 was 187 kbps stereo with an embedded 360x360 cover art JPEG riding along. The track plays at audio.volume = 0.025 (effectively inaudible) when toggled on. There is no quality budget here.

ffmpeg -y -i "Future We Forgot.mp3" -vn -map_metadata -1 \
  -ac 1 -ar 44100 -b:a 64k -codec:a libmp3lame \
  "Future We Forgot.optimized.mp3"

3.3 MB to 1.1 MB. 66% reduction. -vn strips the cover art, -map_metadata -1 drops the ID3 tags. At 2.5% volume the difference is inaudible.

Convert the photo JPEGs to AVIF

14 photos in /public/images/an/ cycling on the homepage avatar grid at 500 ms intervals, sized 500 to 1,100 KB each. The component samples them pixel by pixel through a canvas dithering shader, but AVIF decodes to RGBA in the browser before the canvas reads, so the dither still works.

await sharp(inputPath)
  .rotate() // honor EXIF orientation
  .resize({ width: 400, withoutEnlargement: true })
  .avif({ quality: 47, effort: 6, chromaSubsampling: "4:2:0" })
  .toFile(outputPath);

10.5 MB to 113 KB across the set. 99% reduction. The visual output is indistinguishable from the originals because the dither pass downsamples everything anyway.

Bun blocks postinstall scripts by default per the project's bunfig.toml. sharp ships its native binary through @img/sharp-* optional dependencies rather than a postinstall, so no bun pm trust was required.

Convert the project thumbnails and decorations

Same conversion, run over /public/images/projects/ and /public/images/decorations/. 25 thumbnails plus 3 decoration PNGs. 1.16 MB to 91 KB total.

The conversion script lives at scripts/convert-an-to-avif.mjs with convert and reencode modes so reruns are idempotent. The reencode mode is what I used to drop the avatar AVIFs from width 800 to width 400 after a follow up audit said they were still oversized for their displayed dimensions.

Modernize the browserslist

Lighthouse's "Legacy JavaScript" insight flagged an Array.prototype.at polyfill shipped in Next's client bundle. Added an explicit browserslist field to package.json targeting Chrome 92, Firefox 90, Safari 15.4, Edge 92 and newer. Those are the versions where .at() ships natively, so Next's SWC compiler drops the polyfill.

"browserslist": [
  "chrome >= 92",
  "firefox >= 90",
  "safari >= 15.4",
  "edge >= 92",
  "not dead"
]

Saves about 14 KB on the client bundle. The pre-2022 traffic this excludes is rounding error for a 2026 portfolio site.

Make the LCP element discoverable

After the asset fixes, the homepage's LCP became the Puerto Rico flag sticker in the LogoEngraving bar (smallest decoration but the first visible image content). Lighthouse correctly identified it but flagged it for being lazy loaded with no fetch priority hint.

Added priority to the three LogoEngraving Image components:

<Image priority src="/images/decorations/pr-flag.avif" ... />

priority on Next/Image sets loading="eager", fetchpriority="high", and emits a <link rel="preload"> in the HTML head. The LCP element is now in the document's critical path before the JS parser sees anything else.

Remove the dead Typekit stylesheet

The root layout was pulling in https://use.typekit.net/qwf2lae.css as a <link rel="stylesheet">. A grep confirmed no font-family declarations anywhere on the site reference any Typekit font. All typography routes through Geist. The stylesheet was render blocking dead weight from an earlier design. Removed.

What I deliberately did not do

Per Google's guide and basic restraint:

• No new schema types like FAQPage, HowTo, or extended Article variants. The five already in place (WebSite, Person, BlogPosting, BreadcrumbList, CreativeWork) cover what gets rich result formatting. Adding more is maintenance debt with no measured upside.
• No content rewrites to be "AI friendly." The blog still reads like a human wrote it because a human does.
• No third party AEO services or "AI submission directories." Those are 2024 era spam moves that the guide explicitly warns against.
• No GA replacement. Google Analytics is now the heaviest single request on the page at 158 KB, but ripping it out before having a replacement in place would lose two years of historical traffic data. Trade later, not now.

What's left

A few items the audit surfaced that are not yet fixed:

• The render-blocking-insight flags the page's own CSS chunk. Standard Tailwind output, not worth splitting on a portfolio site.
• Some image dimensions still test slightly larger than display at 1x. DitherImage uses a raw <img> for canvas sampling, so it bypasses Next/Image's automatic srcset generation. A future pass could wrap it.
• The next thing to ship is probably swapping Google Analytics for something lighter, then re-auditing. That trade has its own tradeoffs and is worth its own post.

The companion guide

/guides/auditing-and-optimizing-for-ai-search.md is the step by step playbook. It opens with an agent prompt block so you can paste it into Claude or any other coding agent and have it walk you through the same audit on your own Next.js site. It covers:

1. Search Console verification (URL prefix vs Domain property)
2. Running the Lighthouse Node CLI and parsing the JSON output
3. The asset optimization workflow (sharp, ffmpeg, AVIF, MP3)
4. IndexNow setup with a targeted GitHub Action
5. browserslist modernization
6. Common accessibility regressions and how to find them
7. Making the LCP element a priority image
8. A verification block that confirms the audit passed

The guide is the executable version of this post. If you only want the punch list, start there.

Two weeks ago I argued that by 2026 the JavaScript build pipeline is mostly Rust binaries. Then I migrated this site (Next.js 16, App Router, MDX blog, Radix components, the works) and measured every step before and after. Cold lint went from 3,631 ms to 68 ms, a 53x speedup. Cold typecheck went from 3,176 ms to 222 ms (14x). Production build dropped from 19,948 ms to 10,349 ms (1.9x). Cold dependency install fell from 31.9 s to 12.0 s (2.7x). The lockfile shrank 38%. The dev tools themselves left the npm graph.

The one counterintuitive finding: my node_modules directory got bigger, from 1.3 GB to 1.6 GB. Native Rust binaries ship pre-compiled per platform, and they cost real disk. The savings live in install time, lockfile size, and the supply chain attack surface, not bytes on disk.

The setup

This is a personal site. Real, but small. The numbers below are what one design engineer ships in real life, not a synthetic mega-monorepo. The repo has:

• Next.js 16 (App Router)
• 13 published blog posts in MDX
• 11 components touching Radix UI (accordion, dropdown, slot)
• Tailwind for styling, with a shadcn-style HSL CSS variable theme
• A small Rust CLI in cli/ that serves the terminal portfolio over SSH
• A handful of API routes (RSS, OG images, JSON feed, the x402 paywall demo)

What changed:

Eight commits, four PRs in spirit, one branch landed cleanly into main. The full migration log is published at /TOOLCHAIN.md for anyone who wants the move-by-move.

How I measured

Same machine, same wall outlet, same coffee. Apple Silicon laptop, plugged in, no other heavy processes running. Each measurement averaged over three runs. The bench script that produced these numbers lives at scripts/bench.sh and is short enough to read in one sitting.

For the old toolchain numbers, I checked out the last pre-migration commit (4f00332), wiped node_modules, ran npm install from scratch, then ran each tool with time. For the new numbers, I checked out the current main, wiped node_modules, ran bun install, then ran the new tools the same way. No tricks, no warm caches between toolchains.

A few honest caveats up front:

1. Wall-clock numbers vary. Runs jitter ~10% with background load. I averaged three samples and reported the mean for lint and typecheck. Builds and installs are single-shot; nobody runs an install five times for a benchmark.
2. Time-to-ready is the easiest metric to game. Webpack reports "ready" before it has compiled most routes (lazy compilation). Turbopack precompiles more aggressively. The wall numbers below are end-to-end from npm run dev invocation to the first "Ready in" line, which is closer to what you actually feel.
3. macOS file caching helps every run after the first. I removed .next/ between build samples but did not flush OS-level page cache. The numbers are realistic for repeated dev cycles, not for a fresh machine.

Results

Cold dependency install

npm install   31,923 ms   2,205 packages installed
bun install   11,972 ms     875 top-level / 1,762 total packages

bun install is 2.7x faster on this project. Both ran cold (no node_modules, no global package cache primed). The bun lockfile is text format (bun.lock, 416 KB) which diffs cleanly in pull requests. The npm one was 669 KB of binary-ish JSON noise.

The package count drop matters more than the time. The new lockfile has 36% fewer top-level entries, mostly because removing ESLint sheds about 60 transitive dependencies and Tailwind v4 absorbs the PostCSS chain into Lightning CSS. Smaller surface area means fewer maintainers I need to trust before a bun install runs code on my machine.

Bun's other supply-chain win is its default postinstall policy. Bun blocks postinstall scripts by default and requires packages to be explicitly listed in trustedDependencies in package.json to run them. On this repo, two packages tried to run postinstalls during install: @vercel/speed-insights (an analytics-id sanity check) and @coinbase/x402 (a TOS notice). Both are informational. Bun blocked both. Net postinstalls executed during my install: zero.

Lint

eslint    cold avg  3,631 ms  (3 samples: 3874, 3518, 3500 ms)
biome     cold avg    124 ms  (3 samples:  125,  122,  125 ms)   29x
oxlint    warm avg     68 ms  (3 samples:   67,   69,   67 ms)   53x

This is the headline. A linter going from 3.6 seconds to 68 milliseconds changes how you use it. ESLint at 3.6 s is a thing you run before pushing, with anxiety, sometimes deferring to "I'll fix that later." Oxlint at 68 ms is a thing you run on every keystroke without thinking.

The Biome number includes formatter check and import-sort. Oxlint is purely the lint pass. Both are valid comparisons depending on what you want from the tool. In CI I run both: oxlint as a fast gate, Biome as the deeper check that also handles formatting.

What was lost from the migration: zero rules that I actually use. eslint-config-next ships about 60 packages and 17 Next-specific rules. Biome 2 already covers the ones we hit on this codebase: noImgElement, noHeadElement, noDocumentImportInPage, noHeadImportInDocument, noNextAsyncClientComponent, useGoogleFontDisplay, useGoogleFontPreconnect, useExhaustiveDependencies, useHookAtTopLevel. The rules unique to ESLint were almost all about the legacy Pages Router (no-html-link-for-pages, no-page-custom-font, no-script-component-in-head, no-document-styled-jsx). I use App Router exclusively, so they never fired anyway.

I dropped ESLint entirely in two lines: bun remove eslint eslint-config-next and one CI step removed. 60 transitive packages went with it.

Typecheck

tsc    cold      3,176 ms
tsc    warm avg  1,601 ms  (1629, 1573 ms)
tsgo   warm avg    228 ms  (222, 221, 242 ms)

tsgo is the Go-based port of TypeScript that Microsoft shipped as the 7.0 beta on April 21. The package is @typescript/native-preview@beta. Microsoft's own announcement says you can probably start using it day-to-day, and Bloomberg, Canva, and Figma have shipped it on multi-million-line codebases. Personal portfolio is well below that bar.

The cold-vs-warm gap on tsc is real. The first run pays a JIT and incremental-cache cost, then subsequent runs reuse .tsbuildinfo. tsgo is fast cold and warm because it does not need a JIT to begin with. On this codebase the warm comparison is 1.6 s vs 0.23 s, a 7x speedup. Cold-to-warm for tsc versus warm tsgo is 14x.

The migration was a one-line script change. tsc --noEmit became tsgo --noEmit and that was the entire diff. I kept typescript@5.9.3 installed alongside because Next.js's tsconfig.json plugin wants the regular typescript peer for the editor language server, and IntelliSense in VS Code falls back to it for anyone not running the Native Preview extension.

Production build

webpack    cold  19,948 ms
turbopack  cold  10,349 ms   1.9x

Both built the same 45 routes (13 blog posts, 1 deck, work pages, API routes, OG image generators, sitemap, robots, RSS, JSON feed). Turbopack is the default in Next 16. The --webpack flag still exists if you need it, mostly for compatibility with custom webpack loaders that have not been ported.

This is the most modest improvement on the page (1.9x), and it lines up with what Vercel has publicly reported: roughly 2 to 5x faster production builds in the wild. Build perf is harder to win than lint perf because a bundler is doing real, irreducible work (parsing, scope analysis, tree-shaking, code-splitting, minification, source maps, asset optimization) that does not shrink as much when you rewrite it in Rust. The bigger wins come from Rust's better parallelism on multicore machines.

For incremental builds, the gap widens significantly. I did not script that comparison cleanly enough to report numbers, but anecdotally an MDX edit goes from "make a coffee" to "blink and miss it." The HMR loop is what you actually feel.

Dev server time-to-ready

webpack    684 ms (Next reports: 260 ms)
turbopack  433 ms (Next reports: 294 ms)

This one is closer than I expected and worth being honest about. Webpack often reports "Ready" before it has compiled the routes you have not visited yet (lazy compilation). Turbopack precompiles more eagerly. The wall numbers above are from npm run dev to the first "Ready in" line, which is the user-visible signal.

The real Turbopack win is what happens after that first "Ready." On a route navigation or a file edit, Turbopack invalidates and recompiles in tens of milliseconds where webpack often took hundreds. The blog post I linked at the top cites Vercel's number of roughly 87% faster dev startup on real Next 16 apps once you account for typical edit-and-reload cycles, not just first boot.

Lockfile, dependency tree, and disk

The dependency tree shrank significantly in count, but the size on disk grew. This is the most counterintuitive finding of the migration and worth dwelling on, because it cuts against the easy "Rust toolchain is leaner" narrative.

What's happening: native Rust and Go binaries ship pre-compiled per platform. @biomejs/biome ships about 50 MB per platform. @typescript/native-preview ships the tsgo Go binary at ~150 MB. @tailwindcss/oxide (Lightning CSS) is another ~40 MB. Bun also installs platform binaries for next/swc even though it's the same swc; the npm install picks just one and bun grabs all of them by default. Add it up and the new toolchain costs about 300 MB more on disk than the old one, despite needing 36% fewer packages.

Where the cost actually matters: install time (where bun amortizes parallel binary downloads) and supply-chain surface area (where 875 npm packages with maintainers I do not know is half as many as 1,362). The disk bytes are the cheapest part of the equation. SSDs are huge and getting cheaper. Maintainer trust does not get cheaper.

What this means in practice

Three things shifted in how I work after the migration.

Pre-commit checks are now free. I added a .githooks/pre-commit shell script that runs oxlint, Biome, and tsgo on every commit. Total runtime on this codebase: about 750 ms. That is not a hook you grumble through, it is a hook you barely notice. The full sequence used to take 7 to 10 seconds with the old toolchain, which is exactly slow enough to make people commit with --no-verify after the first day.

CI minutes get cheaper. GitHub Actions bills by the minute. The js job in .github/workflows/ci.yml used to spend roughly 12 to 18 seconds in the lint/typecheck/build sequence; now it spends about 4 to 6 seconds. On a public repo with frequent contributors that scales. On this private repo I switched the workflow to manual trigger only and let the pre-commit hook handle most local verification, which saves the entire workflow run for the cases where it is actually needed.

Supply-chain hardening became practical. With the dev toolchain leaving the npm graph, the surface area shrank meaningfully. Combined with bun's default postinstall blocking, OSV-Scanner in CI, and bun audit plus cargo audit running on every push when CI is on, I can see every advisory affecting the project in one screen. The current count: 6 transitive advisories, all upstream-blocked (the web3 stack via @coinbase/x402, @walletconnect, and the russh dep tree on the Rust side). They surface as warnings; none are actionable from my side. That is the right state to be in.

What did not improve

For honesty's sake, here are the parts of the migration that did not pay off, or where the wins are smaller than the marketing suggests.

Disk usage went up, not down. Discussed above. If you are working on a machine with constrained disk (an old Air, a CI runner with quota), this matters.

Initial dev startup is only 1.6x faster. The HMR loop and edit-recompile cycle are dramatically better, but if you are someone who runs bun run dev once and leaves it open all day, the boot-time win is small. Turbopack pays its dividends incrementally.

Production build is 1.9x faster, not 5x. The Vercel marketing materials cite up to 5x for some workloads, but this depends heavily on what your build is doing. A site with lots of MDX (like this one) spends a meaningful chunk of build time in remark and rehype plugins running pure JavaScript, and Rust does not help there. If your bottleneck is webpack's bundle pass on TypeScript, the speedup is closer to the marketing number. If it is content processing, you save less.

Some advisories will not go away. Three of the npm advisories (ws, postcss, bn.js) and three of the cargo ones (lru, paste, rsa) are stuck waiting for upstream packages I do not control to bump. The migration improved my visibility into them but did not remove them. Anyone telling you their Rust toolchain migration "fixed all advisories" is lying or has no transitive deps.

The codemods only get you 70% of the way. bunx @tailwindcss/upgrade crashed on this codebase mid-flight because of an @apply border-border ordering issue in globals.css. The shadcn-style HSL theme indirection had to be done manually with @theme inline. Plugin migrations (tailwindcss-animate to tw-animate-css) are not automated. Plan on doing manual cleanup after every codemod, even when the docs imply it is one command.

Try it on your own project

Drop the script below into scripts/bench.sh (or wherever you like) and chmod +x it. It works on any Node-ish project; just adjust the bun run calls to match your scripts. The plain-time fallback means you do not need hyperfine installed, but brew install hyperfine will give you cleaner numbers.

The recipe to capture both old and new on the same machine:

# new toolchain numbers
bash scripts/bench.sh --full

# old toolchain numbers (after checking out the pre-migration commit)
git stash
git checkout <pre-migration-sha>
rm -rf node_modules bun.lock
npm install
bash scripts/bench.sh --full
git checkout main
rm -rf node_modules
bun install

The output is a markdown-shaped table you can paste straight into a writeup like this one.

The script

#!/usr/bin/env bash
# Toolchain benchmark.
# Measures install, lint, typecheck, build, and dev-server-ready timings on
# the checked-out tree. Re-run on an old commit (pre-migration) and on HEAD
# to compare. Output goes to stdout as a markdown table.
#
# Usage:
#   scripts/bench.sh                # Quick run (3 samples each, no install)
#   scripts/bench.sh --full         # Full run (5 samples, includes cold install)

set -e
cd "$(git rev-parse --show-toplevel)"

FULL=0
[[ "$1" == "--full" ]] && FULL=1

SAMPLES=3
[[ $FULL -eq 1 ]] && SAMPLES=5

HAS_HYPERFINE=0
command -v hyperfine >/dev/null 2>&1 && HAS_HYPERFINE=1

H=$'\033[33m'
R=$'\033[0m'

git_short=$(git rev-parse --short HEAD)
git_msg=$(git log -1 --pretty=%s | head -c 60)
echo "Benchmarking commit ${git_short}: ${git_msg}"
echo "Samples: ${SAMPLES}, hyperfine: $([ $HAS_HYPERFINE -eq 1 ] && echo yes || echo 'no (using time)')"
echo ""

run_bench() {
  local name="$1"
  local cmd="$2"
  printf "${H}== %s ==${R}\n" "$name"
  if [[ $HAS_HYPERFINE -eq 1 ]]; then
    hyperfine --warmup 1 --runs $SAMPLES --show-output --shell=bash "$cmd" 2>&1 | tail -8
  else
    local total=0
    for i in $(seq 1 $SAMPLES); do
      local start=$(date +%s%N)
      eval "$cmd" >/dev/null 2>&1 || true
      local end=$(date +%s%N)
      local elapsed=$(( (end - start) / 1000000 ))
      total=$(( total + elapsed ))
      printf "  run %d: %d ms\n" $i $elapsed
    done
    printf "  avg:   %d ms\n" $(( total / SAMPLES ))
  fi
  echo ""
}

clean_next() { rm -rf .next; }

echo "== Lockfile + node_modules =="
LOCKFILE=$(ls -1 bun.lock package-lock.json pnpm-lock.yaml yarn.lock 2>/dev/null | head -1 || echo "(none)")
LOCK_SIZE=$(du -h "$LOCKFILE" 2>/dev/null | cut -f1 || echo "?")
NM_SIZE=$(du -sh node_modules 2>/dev/null | cut -f1 || echo "(no node_modules)")
NM_COUNT=$(find node_modules -mindepth 1 -maxdepth 2 -type d 2>/dev/null | wc -l | tr -d ' ' || echo "?")
echo "lockfile:       $LOCKFILE ($LOCK_SIZE)"
echo "node_modules:   $NM_SIZE"
echo "package count:  $NM_COUNT"
echo ""

if [[ $FULL -eq 1 ]]; then
  echo "${H}== Cold install (rm -rf node_modules) ==${R}"
  rm -rf node_modules
  if command -v bun >/dev/null 2>&1; then
    PKG_CMD="bun install"
  elif command -v pnpm >/dev/null 2>&1; then
    PKG_CMD="pnpm install"
  else
    PKG_CMD="npm install"
  fi
  echo "running: $PKG_CMD"
  /usr/bin/time -p $PKG_CMD 2>&1 | tail -5
  echo ""
fi

run_bench "lint (biome check .)" "bun run lint"
run_bench "lint:fast (oxlint)" "bun run lint:fast"
run_bench "typecheck" "bun run typecheck"

echo "${H}== build (cold, removes .next first) ==${R}"
clean_next
/usr/bin/time -p bun run build > /tmp/bench-build.log 2>&1 || cat /tmp/bench-build.log
grep -E "real |compiled|next build" /tmp/bench-build.log | tail -5
echo ""

echo "${H}== dev server time-to-ready ==${R}"
clean_next
START=$(date +%s%N)
bun run dev > /tmp/bench-dev.log 2>&1 &
DEV_PID=$!
for i in $(seq 1 60); do
  if grep -q "Ready in" /tmp/bench-dev.log 2>/dev/null; then
    END=$(date +%s%N)
    READY_MS=$(( (END - START) / 1000000 ))
    READY_LINE=$(grep "Ready in" /tmp/bench-dev.log | head -1)
    echo "dev ready: ${READY_MS}ms (next reports: ${READY_LINE})"
    break
  fi
  sleep 0.5
done
kill $DEV_PID 2>/dev/null || true
wait 2>/dev/null || true
echo ""

It is intentionally one file with no dependencies. If you want to extend it (add HMR latency, RSS, memory footprint), the run_bench helper is the only piece you need to reuse.

What I would change if I were doing this again

1. Run the codemods first, separately, on a clean branch. I bundled the codemod with the manual cleanup and ended up with one big commit instead of a clean codemod checkpoint plus a manual cleanup commit. Keep them separate so you can revert just the manual part if you mess up.
2. Capture before-numbers up front. I had to check out the pre-migration commit and reinstall to get the old numbers retroactively. Running the bench on the pre-migration commit before starting saves an hour of branch swapping later.
3. Move ESLint last, not first. I kept ESLint as a "backstop" through most of the migration, which meant carrying its 60 dependencies and one extra CI step longer than necessary. After verifying Biome's Next-rule coverage, dropping ESLint was a one-line PR I should have done day one.
4. Skip the formatter PR until you are ready for the diff. Enabling Biome's formatter created a 1,440-line cosmetic diff. Worth doing, but worth doing as its own commit on a quiet day, not on top of a Tailwind migration.
5. Set up the pre-commit hook on day one. The faster the local verification loop is, the more aggressively you iterate. I left this until the end and immediately wished I had done it first.

Cited sources

• "Rust Owns the JavaScript Toolchain in 2026", the case for the migration
• Lee Robinson's "Rust Is Eating JavaScript", the original 2026 update
• Next.js 16 release notes for Turbopack defaults
• Tailwind CSS v4 announcement for the Oxide engine
• Biome v2 release post for type-aware lint claims
• Oxlint 1.0 stable release for the 50 to 100x ESLint claim
• TypeScript 7.0 beta announcement for tsgo

Built by Agnel Nieves, a design engineer with 15+ years across product, design systems, and crypto. The full migration log lives at /TOOLCHAIN.md. More writing on the blog.