Open-Source Wikis

/

Astro

/

Systems

/

Vite plugins

withastro/astro

Vite plugins

Astro's framework is, in practice, a curated stack of Vite plugins coordinated by packages/astro/src/core/create-vite.ts. This page is the index of what each plugin does and where to look when something breaks.

Purpose

Compile .astro files, generate routes, transform content, ship hydration shims, surface errors, and gate the dev/build experience — all by registering Vite plugins.

The plugin stack

Plugins are registered in the order returned by createVite() in packages/astro/src/core/create-vite.ts. Order matters because enforce: 'pre' and enforce: 'post' only get you so far.

Plugin Source Responsibility
vite-plugin-environment src/vite-plugin-environment/index.ts Sets optimizeDeps.entries so deps reachable through .astro files get pre-bundled.
vite-plugin-config-alias src/vite-plugin-config-alias/ Honor user tsconfig.json paths.
vite-plugin-fileurl src/vite-plugin-fileurl/ ?fileurl import suffix → URL string.
vite-plugin-astro src/vite-plugin-astro/ Compiles .astro files via @astrojs/compiler.
vite-plugin-html src/vite-plugin-html/ .html files as routes.
vite-plugin-markdown src/vite-plugin-markdown/ .md files as routes via @astrojs/markdown-remark.
vite-plugin-pages src/vite-plugin-pages/ Discover routes from src/pages/.
vite-plugin-routes src/vite-plugin-routes/ Route manifest virtual module.
vite-plugin-static-paths src/vite-plugin-static-paths/ getStaticPaths evaluator.
vite-plugin-renderers src/vite-plugin-renderers/ Wires framework renderers (React/Vue/etc.).
vite-plugin-css src/vite-plugin-css/ CSS ordering and chunking helpers.
vite-plugin-head src/vite-plugin-head/ <head> propagation.
vite-plugin-scripts src/vite-plugin-scripts/ <script> propagation and hoisting.
vite-plugin-app src/vite-plugin-app/ App entrypoint generator.
vite-plugin-astro-server src/vite-plugin-astro-server/ Dev SSR middleware.
vite-plugin-overlay src/vite-plugin-overlay/ Dev error overlay.
vite-plugin-hmr-reload src/vite-plugin-hmr-reload/ Force full reload for non-HMR-safe changes.
vite-plugin-load-fallback src/vite-plugin-load-fallback/ Last-resort module resolver.
vite-plugin-utils src/vite-plugin-utils/ Shared helpers used by other plugins.
vite-plugin-integrations-container src/vite-plugin-integrations-container/ Mounts integration-supplied Vite plugins.
vite-plugin-adapter-config src/vite-plugin-adapter-config/ Lets adapters add Vite config late.
vite-plugin-chromedevtools src/vite-plugin-chromedevtools/ Chrome DevTools workspace JSON.

Feature-specific plugins live alongside their feature, not under src/vite-plugin-*/:

Plugin Source Feature
vite-plugin-actions src/actions/vite-plugin-actions.ts Server actions virtual module
vite-plugin-i18n src/i18n/vite-plugin-i18n.ts i18n virtual modules
vite-plugin-prefetch src/prefetch/vite-plugin-prefetch.ts Built-in prefetch script
vite-plugin-transitions src/transitions/vite-plugin-transitions.ts View transitions
vite-plugin-server-islands src/core/server-islands/vite-plugin-server-islands.ts Server islands codegen
vite-plugin-content-imports src/content/vite-plugin-content-imports.ts astro:content import side
vite-plugin-content-virtual-mod src/content/vite-plugin-content-virtual-mod.ts astro:content virtual module
vite-plugin-content-assets src/content/vite-plugin-content-assets.ts Content image transforms
vite-plugin-fonts src/assets/fonts/vite-plugin-fonts.ts Font subsetting + URL injection
vite-plugin-assets src/assets/vite-plugin-assets.ts astro:assets image service

When plugin order matters

A handful of recurring incidents map to plugin ordering:

  • CSS for client:only components — vite-plugin-css and vite-plugin-renderers need to coordinate so styles are emitted on the page that hosts the island.
  • Content-collection HMR — vite-plugin-content-virtual-mod and vite-plugin-content-imports must invalidate together; otherwise pages render stale content.
  • optimizeDeps thrashing — vite-plugin-environment runs early so its optimizeDeps.entries augmentation lands before Vite computes the dep graph. See reference / Vite dep optimizer.
  • i18n redirect after middleware — vite-plugin-i18n must register the i18n middleware in the right slot of the chain (handled in src/i18n/middleware.ts, not the plugin).

Virtual modules

Astro reserves the astro: namespace for virtual modules. The dispatchers live in packages/astro/src/virtual-modules/. Examples:

  • astro:content
  • astro:actions
  • astro:assets
  • astro:db
  • astro:env
  • astro:transitions
  • astro:prefetch
  • astro:i18n
  • astro:middleware
  • astro:routes

Entry points for modification

  • Add a plugin: define it under src/vite-plugin-<name>/ (or alongside its feature directory), then register it in core/create-vite.ts.
  • Adjust order: edit core/create-vite.ts. Be wary — the existing order has been hardened over years of bug reports.
  • Add a virtual module: add a stub file under src/virtual-modules/, register it in the plugin's resolveId/load hooks, and ship its types under packages/astro/types/.

Built by Factory AutoWiki from public repository content. It is a generated preview for codebase exploration, not source-maintained documentation.

Vite plugins – Astro wiki | Factory