For a portfolio that is mostly writing, project pages and a few interactive touches, Bun, Astro and MDX cover the job with three tools that each do one thing. Bun handles JavaScript tooling. Astro handles routing, content and rendering. MDX lets you drop components into Markdown. This article explains that division of labor, what the official documentation does and doesn’t support, and how to decide whether “more complex” is worth it for your site.
One limit up front: documentation can show what these tools do, but it can’t show what any particular site needed. The reasoning below is a decision framework, not a set of benchmark results from a specific project.
As an Amazon Associate I earn from qualifying purchases.
What each piece does
Bun: the tooling layer
Bun’s overview describes it as “a single, dependency-free binary” that “includes a runtime, package manager, test runner, and bundler” (Bun documentation). For a small site, that means fewer separate tools to install and keep in sync. The same page says Node.js compatibility is still ongoing, so don’t assume every Node workflow or package behaves identically.
Bun also ships a Jest-compatible test runner with TypeScript support, though the docs note that not all Jest features are implemented (Bun test runner). That is plenty for testing a few utility functions, but check it if your tests lean on niche Jest features.
#1 Best Overall
Astro: the site layer
Astro maps files in src/pages/ to routes, and it supports .mdx pages once the MDX integration is installed (Astro pages). For a portfolio, that file-based routing means a new project page is a new file.
Astro’s islands model keeps most page output as static HTML and adds JavaScript only where a component needs interaction (Astro islands architecture). That suits content-led sites with a few interactive parts, such as a theme toggle or a filterable project grid. It is not proof that Astro is right for an app-like site where interaction is everywhere.
Rank #2
- HTML CSS Design and Build Web Sites
- Comes with secure packaging
- It can be a gift option
MDX: the authoring layer
Astro’s documentation says the MDX integration “enhances your Markdown authoring with JSX variables, expressions and components” (Astro MDX integration). In practice you write a case study in Markdown and embed a image comparison, a callout or a demo component where plain Markdown falls short.
Why this counts as “less complex”
“Complex” can mean several different things, and the stack only wins on some of them. Define the term before you compare:
Rank #3
| Axis | What the chosen stack offers | What it costs |
|---|---|---|
| Site scope | Content-led pages with selective interactivity via islands | A poor fit if the whole site behaves like an application |
| Authoring | Markdown plus components where needed | MDX syntax rules and integration configuration to maintain |
| Rendering and operations | Static output, generated at build time | Per-request content needs on-demand rendering with an adapter, which adds a runtime and deployment decision |
| Toolchain | Runtime, package manager, test runner and bundler in one binary | You must verify Node compatibility, scripts, dependencies and your host’s environment |
Astro supports both static rendering and adapter-based on-demand rendering (on-demand rendering; background in the rendering modes guide). A portfolio whose content changes when you publish, not when a visitor arrives, rarely needs the second option. Skipping servers, databases and a CMS is where most of the removed complexity comes from.
Organizing content
Astro’s content collections organize and query Markdown and MDX with defined schemas, which keeps project entries consistent (title, date, tags) (Astro v5 content collections). Collection APIs have changed between Astro generations, and the MDX integration docs now sit under a newer version than the collections docs cited here. Confirm the exact configuration against the version you install before copying any setup.
Rank #4
- Brand: Wiley
- Set of 2 Volumes
- A handy two-book set that uniquely combines related technologies Highly visual format and accessible language makes these books highly effective learning tools Perfect for beginning web designers and front-end developers
What the speed numbers do and don’t mean
Bun’s runtime docs report a Linux Hello World comparison of 5.2 ms for Bun versus 25.1 ms for Node.js (Bun runtime). Its quickstart cites about 6 ms of overhead for bun run versus 170 ms for npm run (Bun quickstart). Both are vendor-published, and neither page gives a date.
They measure startup of tooling commands. They say nothing about your site’s build time, Core Web Vitals or what visitors experience. For visitors, the relevant property is the shipped output: mostly static HTML with little JavaScript, which comes from Astro’s approach rather than from Bun.
Independent reader supportYour contribution helps us test, update, and keep practical guides available for everyone.When to choose something heavier
- You need logins, per-user content or data fetched on every request: plan for on-demand rendering and an adapter, or a framework built around servers.
- Most pages are stateful interfaces: islands help less when nearly everything is an island.
- Your dependencies or deployment host rely on Node behavior Bun doesn’t yet match: keep Node as the runtime and use Astro as usual.
- Non-technical editors will write content: plain Markdown or a CMS may serve them better than MDX.
A practical way to decide
- List what the portfolio must do: pages, posts, interactive widgets, forms.
- Mark anything that needs a server at request time. If nothing does, default to static output.
- Start with plain Markdown and add MDX only when a page needs an embedded component.
- Install with Bun, run your build and any scripts, and confirm your host builds the same way.
- Judge the result by output weight and maintenance effort, not by tooling benchmarks.
If those steps turn up no server needs, this stack gives you a portfolio with few moving parts, and you can add complexity later when a concrete requirement appears.
Quick Recap
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
