Improve astro preview DX by exposing the internal preview plugin for advanced use cases like HTTPS serving

[SanariSan]

Summary

This RFC proposes officially exporting Astro's internal vite-plugin-astro-preview to enable advanced vite preview setups, like enabling HTTPS, while preserving Astro's specific static routing logic.

Background & Motivation

As seen in past issues (#12880), users have found it difficult to enable HTTPS for the local static preview server. This problem stems from an inconsistency in how Astro commands handle Vite configuration. While astro dev correctly merge with a user's vite.config.js, allowing plugins like vite-plugin-mkcert to provide HTTPS, the astro preview command intentionally ignores this configuration. This creates a confusing developer experience and blocks advanced customizations, forcing users who require HTTPS for previewing their static build to find complex workarounds.

While the simplicity of astro preview is a valuable feature for most use cases, this limitation creates a significant hurdle for testing modern web features that require a secure context (e.g., some Service Workers, Web Authentication APIs). Currently, developers are forced to choose between:

1. Using astro preview only in HTTP mode and getting HTTPS in astro dev.
2. Using vite preview with HTTPS, which abandons Astro's "clean URL" routing and brings inconsistency with astro dev (e.g., /nested/page fails to resolve to /nested/page/index.html due to vite's default behavior).

This RFC proposes a solution that maintains the simplicity of the default command while providing a clear, officially supported "escape hatch" for users who need more control.

A working mvp demonstrating this issue and the proposed solution is available here: https://github.com/SanariSan/astro-expose-vite-preview-plugin

Goals

• Provide a supported, official method for developers to enable HTTPS on the local static preview server.
• Resolve the inconsistency where astro dev respects advanced Vite configurations but astro preview does not.
• Offer a clear "escape hatch" for advanced preview server customization without complicating the default astro preview command.
• Ensure developers can use vite preview directly without losing Astro's specific static routing logic.

Example

This RFC proposes officially exporting the internal vite-plugin-astro-preview via the astro package's exports map. This would enable developers to create a custom vite.config.js for advanced previews.

A user wanting to enable HTTPS could then use the following configuration and run vite preview:

vite.config.js

import { vitePluginAstroPreview } from 'astro/internal/vite-plugin-astro-preview';
import { defineConfig } from 'vite';
import mkcert from 'vite-plugin-mkcert';

// This config enables a preview server with both HTTPS and correct Astro routing.
export default defineConfig({
  plugins: [
    mkcert(),
    vitePluginAstroPreview({
      config: {
        outDir: new URL('./dist/', import.meta.url),
        base: '/',
        trailingSlash: 'ignore',
      },
    }),
  ],
  preview: {
    https: true,
  },
});

---

Deeper Analysis & Implementation Details

Looking at the Astro source code it's clear the fix is quite simple.

The Problem: configFile: false

The astro preview command programmatically creates a Vite server and explicitly disables loading any user configuration.

File: packages/astro/src/core/preview/static-preview-server.ts

// ...
  previewServer = await preview({
    configFile: false, // root cause, by design
    base: settings.config.base,
    // ... other hardcoded options
    plugins: [vitePluginAstroPreview(settings)], // Only Astro's internal plugin is used
  });
// ...

Effect: This design choice prevents Vite from discovering vite-plugin-mkcert or respecting the preview.https setting, making HTTPS impossible through the standard astro preview command.

The Solution: Expose the Internal Plugin

The logic for Astro's static routing already exists in vitePluginAstroPreview. The only change required is to make this plugin accessible to users. This can be done with a one-line change in Astro's package.json. Export path is a subject to change.

Proposed Change: packages/astro/package.json

--- a/packages/astro/package.json
+++ b/packages/astro/package.json
@@ -70,7 +70,8 @@
     "./zod": "./dist/zod.js",
     "./errors": "./dist/core/errors/userError.js",
     "./middleware": "./dist/core/middleware/index.js",
-    "./virtual-modules/*": "./dist/virtual-modules/*"
+    "./virtual-modules/*": "./dist/virtual-modules/*",
+    "./internal/vite-plugin-astro-preview": "./dist/core/preview/vite-plugin-astro-preview.js"
   },
   "bin": {
     "astro": "astro.js"

This change is non-breaking and simply exposes an internal tool that empowers developers to solve this problem themselves, aligning perfectly with the goal of providing a powerful escape hatch while keeping the default command simple.

It should be noted that docs should provide devs a clear path for astro to vite fallback in case of advanced (or not so advanced as in this case) static serving requirements. vite-plugin-mkcert has over 1 mil. monthly downloads which shows a clear demand for the feature overall.