How to Migrate Astro to Bun on CloudFlare Pages (2026 Guide)

Migrate your Astro project from Node.js to Bun on CloudFlare Pages. Step-by-step guide with build commands, BUN_VERSION setup, verification & troubleshooting.

DragosJuly 27, 202610 min read

Swapping Node.js and npm for Bun on CloudFlare Pages can cut dependency install times by 10-30x and shave 15-30% off I/O-heavy builds. Bun is a supported build runtime on CloudFlare Pages, not an experiment. If you have an existing Astro static site on Node.js and npm, this guide covers the full migration. Whether you built a free blog with Astro and Cloudflare or migrated from WordPress to Astro, the Bun swap is the next step for faster deploys.

Video Note

The video above shows the original 2024 migration flow. The written guide below is fully updated for 2025 with current Bun versions, Cloudflare build system changes, and new troubleshooting guidance.

Prerequisites and compatibility

Astro version compatibility

This migration works the same way for Astro v3 through v7 on static (SSG) sites. Astro 7 added a Rust compiler and Rolldown (Vite 8), which means faster builds. You can read more about Astro 7 build performance for details. The Bun migration steps themselves have not changed across Astro versions.

Static sites only

This guide covers static (SSG) Astro sites. If you use SSR, read the next section first.

SSR users: important caveat

If you use @astrojs/cloudflare for server-side rendering with Astro 6+, Cloudflare Pages is no longer supported for SSR deployments. As of @astrojs/cloudflare v13, only Cloudflare Workers is supported for on-demand rendering. Static sites are unaffected by this change.

SSR on Cloudflare Pages no longer supported

If you use @astrojs/cloudflare for SSR with Astro 6+, you must deploy to Cloudflare Workers, not Pages. Static sites are unaffected.

1. Install Bun

curl -fsSL https://bun.sh/install | bash

brew install bun

powershell -c "irm bun.sh/install.ps1 | iex"

npm install -g bun

After installing, verify it works:

bun --version

You should see 1.3.x or later. If you get command not found, restart your terminal or run source ~/.bashrc / source ~/.zshrc.

Verify your install

Run bun --version. You should see 1.3.x or later. If it is below 1.1.x, you will want to upgrade for Sharp image optimization compatibility.

You can check Bun vs NPM, Yarn, PNPM, and Others for a detailed comparison of Bun against other package managers.

2. Remove existing lock files

Remove the lockfile from whatever package manager you were using before:

# If you were using npm:
rm package-lock.json

# If you were using pnpm:
rm pnpm-lock.yaml

# If you were using Yarn:
rm yarn.lock

Bun creates its own lockfile: bun.lock (text format, default since ~v1.2) or bun.lockb (binary). This gets generated on the next bun install.

Commit your lockfile

Cloudflare Pages runs bun install --frozen-lockfile by default. If bun.lock or bun.lockb is not committed to your repo, your build will fail with a lockfile mismatch error.

3. Install dependencies with Bun

Run bun install to install your project’s dependencies:

bun install

This reads your package.json and downloads packages much faster than npm (typically 10-30x for fresh installs). The biggest win is CI/CD dependency install time.

Sharp, Astro’s image optimization library, works with Bun natively. It was broken in 2023-2024 but has been fixed since Bun ~1.1.x. No workarounds needed.

If you need to update packages to their latest versions later, see how to update packages with Bun.

4. Test your Astro project locally

Start the dev server to make sure everything works:

bun run dev

Open http://localhost:4321 and verify your pages load correctly. Then test the production build:

bun run build

The dist/ directory should be created without errors.

Understanding the `--bun` flag

There is a distinction most guides skip:

bun run dev / bun run build runs Astro through Bun’s Node.js compatibility layer. This is stable and recommended for most projects.
bun run --bun dev / bun run --bun build runs Astro using the actual Bun runtime. Faster, but some integrations may have rough edges.

The --bun flag

Start with bun run build (Node compat mode) for stability. If your project builds cleanly and you want more speed, try bun run --bun build. If you hit ERR_HTTP_SOCKET_ASSIGNED or other Node-specific errors, drop back to compat mode. It is still faster than npm.

If you want to squeeze more speed out of your builds, check the guides on Astro 7 build performance and how to optimize Astro build speed.

5. Configure Cloudflare Pages for Bun

Log into the Cloudflare dashboard and go to your project’s settings. You’ll need to update the build command and optionally pin your Bun version. If you haven’t set up Cloudflare Pages yet, see how to deploy an Astro site on Cloudflare Pages first.

Update the build command

Change your Cloudflare Pages build command to:

bun run build

bun run --bun build

The recommended bun run build uses Bun’s Node.js compatibility layer, which is stable and faster than npm. The --bun variant uses the native Bun runtime. It is faster but may not work with all integrations. Start with the recommended option.

Pin your Bun version with BUN_VERSION

In Cloudflare Dashboard → Settings → Environment variables, add:

BUN_VERSION=1.3.14

Replace 1.3.14 with the latest stable Bun release. Pinning prevents surprise breakage when Cloudflare updates the default Bun version on their build image.

Avoid BUN_VERSION=latest

Setting BUN_VERSION=latest causes a 403 error during build. Bun’s installer script hits rate-limiting issues when fetching the version list through Cloudflare’s build image (which uses asdf under the hood). Always pin a specific version like 1.3.14.

Cloudflare Pages build system versions (v2 vs v3)

Cloudflare Pages has three build system versions:

v3: default for new projects. Bun 1.2.15, Node 22.16.0, Ubuntu 22.04.2.
v2: default Bun 1.1.33, Node 18.17.1. Auto-migrating to v3 by February 2027.
v1: deprecated. Auto-migrating to v3 by September 2026.

Check your build system

New projects default to v3. If you are on v1 or v2, consider upgrading in Cloudflare Dashboard, Pages, Settings. v1 does not have Bun preinstalled, so you need v2 or v3.

Cloudflare Pages free tier gives you 500 builds/month, 1 concurrent build, and a 20-minute hard build timeout. Bun’s faster installs help large projects stay under that timeout. No additional cost for using Bun vs Node.

6. Deploy to Cloudflare

Commit your changes and push to your Git repository:

git add .
git commit -m "Migrate to Bun"
git push

Cloudflare will detect the push and start building with the new Bun settings. You can watch the build progress in Cloudflare Dashboard → Pages → your project → Deployments.

7. Verify the deployment

Do not just assume it worked. Check these things:

Build log shows bun install vX.X.X (confirming Bun, not npm, ran the install)
Build completes without errors
Site loads correctly at your production URL
No hydration errors or console warnings in browser DevTools

How to verify:

Build log: Cloudflare Dashboard → Pages → Deployments → click the latest build → read the log. Look for bun install vX.X.X near the top.
Site check: Visit your production URL and click through several pages.
Console check: Open browser DevTools → Console tab. Look for any errors or warnings that weren’t there before.

# Quick HTTP check from your terminal:
curl -I https://your-site.pages.dev

You should get a 200 OK response.

Troubleshooting common issues

Build hangs on bun install

Bun install can intermittently hang on Cloudflare Pages. This is a known issue.

Fix: Set SKIP_DEPENDENCY_INSTALL=true as an environment variable in Cloudflare Dashboard, then change your build command to install Bun manually via npm:

npm install -g --allow-scripts=bun bun && export PATH="$(npm prefix -g)/bin:$PATH" && bun --version && bun install && bun run build

This bypasses the preinstalled Bun and installs a fresh copy during the build.

BUN_VERSION=latest causes 403 error

Setting BUN_VERSION=latest fails because Bun’s installer script can’t fetch the version list through Cloudflare’s asdf-based build image.

Fix: Pin a specific Bun version instead:

BUN_VERSION=1.3.14

bun: command not found in build

Your Cloudflare Pages project is probably on build system v1, which doesn’t have Bun preinstalled.

Fix: Go to Cloudflare Dashboard → Pages → Settings and upgrade to build system v2 or v3.

Sharp / image optimization errors

In 2023-2024, Sharp (Astro’s image optimizer) didn’t work with Bun. This has been resolved since Bun ~1.1.x.

Fix: Make sure you’re running Bun 1.1.x or later. If you’re on an older version, update your BUN_VERSION environment variable.

ERR_HTTP_SOCKET_ASSIGNED or Node-specific errors

You’re likely using the --bun flag, which runs Astro through the native Bun runtime instead of Node.js compatibility mode. Some integrations don’t work cleanly with native Bun.

Fix: Remove the --bun flag. Use bun run build instead of bun run --bun build. You still get Bun’s faster install times.

Lockfile conflicts / frozen lockfile errors

Cloudflare Pages runs bun install --frozen-lockfile by default. If your bun.lock or bun.lockb file isn’t committed, the build fails.

Fix: Run bun install locally, then commit the lockfile:

git add bun.lock
git commit -m "Add Bun lockfile"
git push

Need the latest Bun on Cloudflare?

If the preinstalled Bun is too old and BUN_VERSION doesn’t support the version you need, use this workaround. Set SKIP_DEPENDENCY_INSTALL=true as an environment variable, then use this build command:

npm install -g --allow-scripts=bun bun && export PATH="$(npm prefix -g)/bin:$PATH" && bun --version && bun install && bun run build

This installs a fresh Bun during the build. If your build is timing out, Bun’s faster installs may help. The 20-minute build timeout is a hard limit. See how to optimize Astro build speed for more tips.

When not to migrate to Bun

Consider skipping if...

You use Astro SSR with @astrojs/cloudflare on Astro 6+. Cloudflare Pages no longer supports SSR, only Workers. This guide will not help.
You rely on Node.js-specific packages that have not been tested with Bun.
You use Vite plugins that assume Node.js internals. These may break under the --bun flag.
Your project already builds and deploys fine with npm or pnpm. Consider whether the migration effort is worth it for your use case.

Conclusion

Bun on Cloudflare Pages is a supported runtime with a mature build system (v3) and proper version pinning. The migration is a one-time effort: swap your lockfile, install dependencies with bun install, update the build command to bun run build, and pin BUN_VERSION in Cloudflare Dashboard. You get faster dependency installs, faster builds for I/O-heavy projects, and a simpler local dev experience.

If you are starting a new project, you can build a free blog with Astro and Cloudflare with Bun from day one. If you are looking at alternative deployment platforms for static Astro sites, Bunny.net is a solid option. Here is how to deploy Astro to Bunny.net.

#Bun #Astro #Cloudflare

Table of Contents