Astro Render Component

Zero-Config • DOM-Free • HTML String • Fast Node Testing

Astro component renderer. Zero configuration. Produces clean HTML strings directly in Node.js without any DOM environment.

Table of Contents

• ✨ Features
• 🕵🏼 Usage
• 🤹🏼 API
• 🗒️ Examples
• ⚙️ Implementation
• 🎯 Motivation
• 📝 Changelog
• 🪪 License
• 💖 Support
• 🧬 Related
• 👨🏻‍💻 Author

Features

• ✨ Zero-config: drop in and render Astro components instantly
• 🐢 Fast: pure Node.js, no DOM simulation overhead
• 🔧 Returns clean HTML string: ready for snapshots or text checks
• 🚫 No happy-dom/jsdom needed: runs in plain Node environment
• ✅ Works with Vitest: perfect with @vitest-environment node
• 📦 Tiny footprint: minimal wrapper over Astro's Container API
• 🛡️ Safe types: full TypeScript support, exported AstroComponentFactory
• 🔄 Supports props/slots: pass options just like renderToString
• ⚡ Modern baseline: Node >=24, Astro >=7 ready, leveraging the AstroContainer API
• 🧼 Clean errors: meaningful messages on render failures

Usage

Install it by executing any of the following, depending on the preferred package manager:

bun add -D @igorskyflyer/astro-render-component

pnpm add -D @igorskyflyer/astro-render-component

yarn add -D @igorskyflyer/astro-render-component

npm i -D @igorskyflyer/astro-render-component

API

async renderAstroComponent()

async function renderAstroComponent(
  component: AstroComponentFactory,
  options: ContainerRenderOptions = {}
): Promise<string>

Renders an Astro component to an HTML string using the experimental Container API.
Server-side only utility – no DOM environment required.
Perfect for Vitest tests (@vitest-environment node), snapshots, and SSR checks.

Examples

Render an Astro component to HTML string:

MyComponent.test.ts

// @vitest-environment node
import { renderAstroComponent } from '@igorskyflyer/astro-render-component'
import MyComponent from '../MyComponent.astro'

const html: string = await renderAstroComponent(MyComponent, {
  props: { title: 'Hello' }
})

expect(html).toContain('<h1>Hello</h1>')

Implementation

This utility is a thin, zero-config wrapper over Astro's experimental Container API:

• Core API used
  experimental_AstroContainer.create() → creates isolated render context
  container.renderToString(component, options) → renders to HTML string

• Behavior
  • Server-side only: runs in plain Node.js (no DOM, no happy-dom/jsdom)
  • Returns plain string containing full rendered HTML (tags, attributes, text, islands)
  • Supports props, slots, and other ContainerRenderOptions
  • Throws meaningful error on failure (e.g. invalid component, render crash)
  • No side effects, no caching, no hydration setup

• Key characteristics
  • Type-safe: derives AstroComponentFactory from renderToString signature
  • ESM-only output (.js + .d.ts)
  • Designed for testing (Vitest with @vitest-environment node) and lightweight SSR

Motivation

Provide the lightest possible server-side Astro component renderer: zero config, no DOM dependency, fast HTML string output for testing and SSR checks.

Changelog

Read about the latest changes in the CHANGELOG.

License

Licensed under the MIT license.

Support

If this open-source project has saved you time or improved your workflow, consider supporting its continued development via LiberaPay or Ko-Fi.

Support helps fund new open-source tools, maintenance, and documentation, thank you!

Related

@igorskyflyer/astro-easynav-button

🧭 Add an easy-to-use navigational button (jump to top/bottom) to your Astro site. 🔼

@igorskyflyer/astro-post-excerpt

⭐ An Astro component that renders post excerpts for your Astro blog - directly from your Markdown and MDX files. Astro v2+ collections are supported as well! 💎

@igorskyflyer/chars-in-string

🪐 Provides ways of testing whether an array of chars is present inside a given String. ☄

@igorskyflyer/magic-queryselector

🪄 A TypeScript-types patch for querySelector/querySelectorAll, make them return types you expect them to! 🔮

@igorskyflyer/vscode-folderpicker

✨ Provides a custom Folder Picker API + UI for Visual Studio Code. 🎨

Author

Created by Igor Dimitrijević (@igorskyflyer).