docs: Highlight option to opt in to use bun runtime over node default

[eugengi]

Description

Minor addition to the docs to inform users to opt in to use Bun as a runtime for the dev server, builds, and previews.

By default, Bun respects the Node shebang (#!/usr/bin/env node) found at the top of executable files and automatically passes execution over to the system's Node.js runtime. To bypass this and force execution inside the Bun runtime, you must use the --bun flag

Note

This option is described in the official Bun recipe docs but is missing in the corresponding Astro docs.

Docs

• Bun's Astro guide
• Astro's Bun recipe

References

• Closes: N/A
• Related to N/A
• For Astro version latest
• Discord username: @sweugene

[astrobot-houston]

Hello! Thank you for opening your first PR to Astro’s Docs! 🎉

Here’s what will happen next:

1. Our GitHub bots will run to check your changes.
   If they spot any broken links you will see some error messages on this PR.
   Don’t hesitate to ask any questions if you’re not sure what these mean!

2. In a few minutes, you’ll be able to see a preview of your changes on Netlify 🥳.

3. One or more of our maintainers will take a look and may ask you to make changes.
   We try to be responsive, but don’t worry if this takes a few days.

[astrobot-houston]

Lunaria Status Overview

🌕 This pull request will trigger status changes.

Learn more

By default, every PR changing files present in the Lunaria configuration's files property will be considered and trigger status changes accordingly.

You can change this by adding one of the keywords present in the ignoreKeywords property in your Lunaria configuration file in the PR's title (ignoring all files) or by including a tracker directive in the merged commit's description.

Tracked Files

File	Note
en/recipes/bun.mdx	Source changed, localizations will be marked as outdated.

Warnings reference

Icon	Description
🔄️	The source for this localization has been updated since the creation of this pull request, make sure all changes in the source have been applied.

[delucis]

Thanks for the PR @eugengi!

Astro doesn’t officially support running with Bun instead of the Node runtime currently, so we intentionally don’t document this.

[eugengi]

Thanks for the head-ups @delucis.

I've seen people in the community pull off Astro with Bun as a runtime.
It's worth knowing it's not officially supported by the team

[delucis]

Yeah, some people are able to use it successfully, but there are issues due to Bun not yet having reached it’s goal of full Node compatibility. I think we should maybe clarify the warning at the top of the page: https://docs.astro.build/en/recipes/bun/

It currently says “Using Bun with Astro may reveal rough edges,” but we should probably clarify specifically that the runtime is the riskiest part. AFAIK using the bun CLI as a package manager works OK-ish (although I haven’t tried it personally), so that’s why we document that but not the --bun runtime flag.

[eugengi]

There are a couple of Astro-related issues on bun. I didn't go through each, but got AI to analyze the issues. The majority are runtime-specific with recurring themes around: dev server crashes (tied to Babel), failing config reloads, native binary compatibility, and runtime API issues.

I'd argue it's safe to rely on Bun for installs/resolutions (package manager), which is outside the full Node-compatibility issue you highlighted

[eugengi]

It currently says “Using Bun with Astro may reveal rough edges,” but we should probably clarify specifically that the runtime is the riskiest part...

Good call! The claim in the docs is a bit broad.
Creating a distinction for using Bun as a package-manager vs runtime would be ideal.

I can follow up with a new PR for this! @delucis lmk your thoughts

[delucis]

Sure! It would only need a very minimal edit to that caution I think to clarify it.

[eugengi]

Hey @delucis, sorry for the late one.

I've opened a PR with the suggested edits for your review.
Kindly lmk your thoughts