Images get emitted to `_astro`, even though they're not used in the output

[spaceemotion]

Astro Info

Astro                    v5.17.2
Vite                     v6.4.1
Node                     v24.13.0
System                   Linux (x64)
Package Manager          pnpm
Output                   static
Adapter                  none
Integrations             none

If this issue only occurs in one browser, which browser is a problem?

No response

Describe the Bug

When importing an image, either synchronously via import Image from '...', or async via import('...'), the final build output in dist/_astro contains the images even though no Astro-native image functions are used (e.g. getImage, or the Image/Picture components from astro:assets).

In the reproduction, I am only importing the image metadata itself, and process it manually into a base64 Data URI string. However, the final build output still contains a processed image (dist/_astro/example.C_B8VLaJ.png).

I replicated this with both, Astro 5 as well as the latest Astro 6 beta.

Curiously enough, this also happens when just importing an image to get its width or height, and not even touching its src property.

Why depend on ImageMetadata in the first place?

If I try to work around this via importing an image using the ?url query (e.g. import Image from './example.png?url'), Astro already processes the URL into something that points to the _astro/ folder (and not the original vite-internal module source).

What's the expected result?

Images that aren't actively used in the output should not appear in the final build output (as in, rendered to HTML).
Times when I expect images to be included:

1. When adding to the module graph via:

   <img src={MyImage.src} />

2. When using the Astro-native getImage method:

   const processedImg = await getImage({
     src: MyImage,
     width: 200,
     height: 200,
     format: 'webp',
   })

3. When using the Astro-native Image and Picture components (which use getImage under the hood, afaik).

4. Manually calling the emitImageMetadata function - as it implies we're "emit"-ing an asset.

Link to Minimal Reproducible Example

https://github.com/spaceemotion/astro-bug-incorrect-image-emits

Participation

• I am willing to submit a pull request for this issue.

[astrobot-houston]

I was able to reproduce this issue. When importing an image and using only its ImageMetadata for manual processing (e.g., converting to a base64 data URI via sharp), the image file is still emitted to dist/_astro/ despite never being referenced in any rendered HTML output.

Fix: I was able to fix this issue. Added a post-build cleanup step that scans the rendered output for references to emitted image files and deletes any that are unreferenced. All existing image-related tests continue to pass, and images that are directly referenced via <img src={img.src} /> are correctly preserved. View Fix

Cause: Images are unconditionally emitted via Rollup's emitFile() during the Vite load hook when imported, but the existing cleanup logic only handles images that go through Astro's optimization pipeline (<Image>, getImage()). Images imported solely for their metadata are emitted but never cleaned up, leaving orphaned files in the build output.

Impact: Any user who imports images for manual processing (e.g., reading file paths, generating base64 data URIs, extracting metadata) without using Astro's built-in <Image>/<Picture> components or getImage() will have unnecessary image files in their build output, wasting disk space and CDN bandwidth.

Full Triage Report

Issue #15505: Images get emitted to _astro, even though they're not used in the output

Reproduction Status: REPRODUCED

Original Issue Summary

Reporter: spaceemotion
Title: Images get emitted to _astro, even though they're not used in the output

Bug Description

When importing an image (either synchronously via import Image from '...' or async via import('...')), the final build output in dist/_astro contains the images even though no Astro-native image functions are used (e.g., getImage, or the Image/Picture components from astro:assets).

The user imports image metadata only to process it manually into a base64 Data URI string using sharp. The image should not need to be emitted as a separate file in the build output, since its content is already inlined as a data URI.

Expected Behavior

Images that aren't actively referenced in the rendered HTML output (i.e., not used via <img src={MyImage.src} />, getImage(), or the Image/Picture components) should not appear in dist/_astro/.

Actual Behavior

The image file appears in dist/_astro/example.CxqzCtN0.png despite:

1. Not being referenced via src attribute in any HTML element
2. Not being processed via getImage()
3. Not being used with Image or Picture components
4. Only the ImageMetadata object being used to read the file path for manual sharp processing

Environment Details

• Astro: workspace (latest from monorepo, equivalent to v6 beta / latest v5)
• Output: static
• Adapter: none
• Integrations: none
• Node.js: v22+ (sandbox)
• Package Manager: pnpm
• Additional dependency: sharp ^0.34.5

Reproduction Steps

1. Created a minimal Astro project with output: static
2. Added a test PNG image at src/assets/example.png (100x100 red square)
3. Created src/lib/images.ts that:
   • Takes an ImageMetadata object
   • Resolves the image's file path from ImageMetadata.src
   • Uses sharp to resize and convert to a base64 data URI string
4. Created src/components/TestComponent.astro that:
   • Accepts an ImageMetadata prop (thumbnail)
   • Calls renderImageDataUrl() to convert the image to a data URI
   • Renders <img src={thumbnailUrl} /> where thumbnailUrl is a data:image/png;base64,... string
5. Created src/pages/index.astro that:
   • Dynamically imports the image: (await import('../assets/example.png')).default
   • Passes the metadata to TestComponent
6. Ran astro build

Results

With image import (bug case):

Build output files:

dist/_astro/example.CxqzCtN0.png    <-- THIS SHOULD NOT EXIST
dist/favicon.ico
dist/favicon.svg
dist/index.html

The HTML output (dist/index.html) contains:

<!DOCTYPE html><html> <head><title>Issue 15505 Reproduction</title></head> <body> <img src="data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAGQAAABkCAMAAABHPGVmAAAAA1BMVEX/AAAZ4gk3AAAACXBIWXMAAAPoAAAD6AG1e1JrAAAAIUlEQVR4nO3BgQAAAADDoPlTX+EAVQEAAAAAAAAAAAAdBid0AAHO0uJOAAAAAElFTkSuQmCC"> </body></html>

Key observation: The <img> tag uses a data: URI. There is no reference to /_astro/example.CxqzCtN0.png anywhere in the HTML. The emitted image file is unreferenced and wastes disk space / CDN bandwidth.

Baseline (without image import):

Build output files:

dist/favicon.ico
dist/favicon.svg
dist/index.html

No _astro/ directory exists at all. This confirms the image emission is triggered by the import statement, not by some other mechanism.

Root Cause Analysis

The issue is in Astro's image asset handling during the build process. When an image is imported (e.g., import img from './example.png'), Astro's Vite plugin intercepts this import and:

1. Returns an ImageMetadata object containing src, width, height, format, etc.
2. The src property points to the hashed filename in _astro/ (e.g., /_astro/example.CxqzCtN0.png)
3. The image is always emitted to the build output as part of the module transformation, regardless of whether the src property is ever used in the final HTML

The core problem is that the image emission happens at import time (during Vite's module graph processing), not at render time (when the HTML is actually generated). This means any import of an image file triggers emission, even if the imported metadata is only used to read the file from disk for manual processing.

Relevant code areas:

The image handling happens in:

• packages/astro/src/assets/ — the assets system
• packages/astro/src/vite-plugin-astro/ — Vite plugin that transforms image imports
• emitFile / emitAsset calls related to image processing
• The ImageMetadata generation code that sets the src property to point to _astro/

---

Diagnosis

Confidence: high

Root Cause

The root cause is a gap in Astro's image asset lifecycle: images are always emitted to the build output via Rollup's emitFile() at import time, but the existing cleanup mechanism only handles images that go through the <Image> component / getImage() optimization pipeline. Images that are imported but never processed through Astro's image optimization system are emitted unconditionally and never cleaned up.

Detailed Code Path Analysis

The image handling involves two separate systems that don't fully communicate:

1. Image Emission (at Vite module resolution time)

File: packages/astro/src/assets/vite-plugin-assets.ts:261-318 — The astro:assets:esm Vite plugin's load hook.

When import img from './example.png' is encountered:

1. Line 281-283: A fileEmitter is created during build (shouldEmitFile = true), wrapping emitClientAsset().
2. Line 284: emitImageMetadata(id, fileEmitter) is called, which reads the file, extracts metadata, and unconditionally calls fileEmitter() to emit the asset via Rollup.

File: packages/astro/src/assets/utils/node.ts:72-138 — emitImageMetadata() function.

• Line 116-120: For non-SVG images, fileEmitter({ name, source, type: 'asset' }) is called unconditionally. This calls Rollup's this.emitFile(), which commits the asset to the build output. Once emitted, Rollup has no mechanism to "un-emit" an asset.
• Line 123: The src property is set to __ASTRO_ASSET_IMAGE__<handle>__, a placeholder later resolved to the final /_astro/example.hash.png path.

2. Reference Tracking (Proxy-based, during rendering)

File: packages/astro/src/assets/utils/proxy.ts:3-23 — getProxyCode() function.

For server/prerender environments (line 296-311 of vite-plugin-assets.ts), the returned ImageMetadata is wrapped in a Proxy. When any property is accessed on the metadata object, the proxy adds the image's fsPath to globalThis.astroAsset.referencedImages. This tracking is meant to identify which images are "used" at render time.

3. The Cleanup Gap

File: packages/astro/src/assets/build/generate.ts:102-131 — generateImagesForPath() function.

The deletion logic at lines 115-131 checks referencedImages and deletes the original emitted image if it's unreferenced. However, this function is only called for images in staticImageList — images that were processed through <Image> component or getImage() (which call addStaticImage).

File: packages/astro/src/core/build/generate.ts:192-281 — generatePages() function.

At line 192, getStaticImageList() is called. The loop at line 206 iterates only over staticImageList entries. If staticImageList is empty (which it is when no <Image> or getImage() is used), the entire cleanup section is skipped.

Instrumentation Results (confirmed via debug logging)

[DEBUG emitImageMetadata] Emitting image asset: .../src/assets/example.png, filename: example.png
[DEBUG emitImageMetadata] Emitted with handle: CHqTS6bC

[DEBUG generatePages] staticImageList size: 0       <-- Empty! No images went through optimization
[DEBUG generatePages] staticImageList keys: []
[DEBUG generatePages] referencedImages: [            <-- Image IS tracked as referenced (by proxy)
  '.../triage/issue-15505/src/assets/example.png'
]

Key findings:

1. The image is emitted via emitFile() during the load hook — this is the point of no return.
2. staticImageList is empty because the image was never passed to <Image> or getImage().
3. The referencedImages set correctly tracks the image (via the Proxy), but this information is never consulted for images outside staticImageList.
4. The emitted file at dist/_astro/example.CxqzCtN0.png persists in the output because no code path exists to clean it up.

Affected Files

File	Lines	Role
packages/astro/src/assets/vite-plugin-assets.ts	281-284	Unconditionally emits image via emitFile() in load hook
packages/astro/src/assets/utils/node.ts	114-121	emitImageMetadata() calls fileEmitter() unconditionally
packages/astro/src/assets/build/generate.ts	102-131	Deletion logic only runs for staticImageList entries
packages/astro/src/core/build/generate.ts	192-281	Only iterates staticImageList, skips cleanup when empty
packages/astro/src/assets/utils/proxy.ts	3-23	Proxy tracks reference access but data is unused for non-optimized images

Suggested Fix Approach

The cleanest fix would be to add a post-build cleanup step that deletes emitted image assets that are not referenced in the final output.

---

Fix

Fix Status: FIXED

What Was Changed

Added a post-build cleanup step that deletes emitted image files from the output directory when they are not referenced in any rendered output file (HTML, CSS, JS, etc.).

The fix consists of changes to 5 files in packages/astro/src/:

1. assets/types.ts — Added two new optional fields to the global astroAsset type:

   • emittedImageHandles: Maps Rollup emit handles → source file paths
   • emittedImageFiles: Maps output file paths → source file paths

2. assets/utils/node.ts — In emitImageMetadata(), after emitting an image via fileEmitter(), store the handle → fsPath mapping in globalThis.astroAsset.emittedImageHandles.

3. assets/vite-plugin-assets.ts — Two changes:

   • Initialize emittedImageHandles as an empty Map in the global setup
   • In the renderChunk hook, when resolving __ASTRO_ASSET_IMAGE__ placeholders, record the mapping from resolved output filename → source fsPath in emittedImageFiles

4. assets/build/generate.ts — Added new exported function cleanUnusedEmittedImages():

   • Gets the list of emitted image files from globalThis.astroAsset.emittedImageFiles
   • Excludes images that are handled by the optimization pipeline (staticImageList)
   • Recursively scans the output directory (excluding .prerender/ server chunks)
   • Checks if each emitted image's output filename appears in any text-based output file
   • Deletes unreferenced images

5. core/build/static-build.ts — Calls cleanUnusedEmittedImages() after page generation completes, for both static and server build modes.

Verification Results

Before fix:

dist/_astro/example.CxqzCtN0.png    ← Unreferenced image in output
dist/favicon.ico
dist/favicon.svg
dist/index.html

After fix:

dist/favicon.ico
dist/favicon.svg
dist/index.html

The emitted image file is correctly deleted because its URL (/_astro/example.CxqzCtN0.png) does not appear in any rendered output file. The HTML correctly contains only the data URI.

Test Results

All existing image-related tests pass:

• image-deletion.test.js: 5/5 pass
• core-image-service.test.js: 16/16 pass
• astro-assets.test.js: 5/5 pass
• passthrough-image-service.test.js: 11/11 pass
• core-image-svg.test.js: 11/11 pass
• astro-assets-prefix.test.js: 16/16 pass
• astro-assets-prefix-multi-cdn.test.js: 10/10 pass
• core-image-layout.test.js: 92/92 pass
• asset-query-params.test.js: 3/3 pass

This report was made by an LLM. Mistakes happen, check important info.

[matthewp]

We're not able to detect how you use the image so we can't omit it. You could remove it yourself in a post-build step if you know it's not needed. Maybe we could add an optional ?metadata or something to prevent processing the build, idk.

[spaceemotion]

@matthewp yeah that's what I thought. Having a simple way to not let Astro auto-emit things would be good though. From the Houstin bot reply it seems like Astro has a proxy, that even if you only access the image width property already tracks it?

If there'd be a manual opt-in flag like you described would already be very helpful for us (since we often compose images together at build-time).

[matthewp]

Yeah it might be possible via proxy tracking, could be tricky though.

[whooisdev]

I haven't seen this specific approach shared anywhere else yet, but I've managed to implement a clean, memory-level solution using a custom Vite plugin that runs during the generateBundle hook. This approach avoids the need for post-build filesystem scanning and keeps the manifest (e.g., for Cloudflare Workers) perfectly clean.

Since Astro's deployment adapters generate their asset manifests based on the internal bundle state, simply running a post-build script to delete files from the dist folder leaves behind "ghost" references in the manifest. This mismatch can lead to deployment failures or runtime errors on platforms like Cloudflare that strictly validate their deployed assets. By intercepting and removing the redundant files directly in memory during generateBundle, the assets are effectively erased before the adapters even process them, ensuring the final manifest perfectly matches the output directory."

The logic is straightforward:

1. Identify assets that Astro has already optimized (they exist in the bundle alongside their raw counterparts).
2. Scan only the generated HTML and CSS assets for references to these raw filenames.
3. Intentionally skip scanning JS chunks, as they contain the raw import definitions (the "false positives") which would otherwise prevent the cleanup.
4. If a raw image filename is not found in the final HTML/CSS output, it is safely removed from the bundle in memory before the manifest is finalized and written to the disk.

Here is the plugin. You can place this anywhere in your project structure, for example in src/integrations/vite-remove-original-images.mjs or a /scripts directory:

/**
 * Vite plugin to remove original/raw images from the final bundle that have been optimized by Astro.
 * This helps in reducing the deployment size by removing redundant assets.
 *
 * @param {Object} options - Configuration options.
 * @param {(string|RegExp)[]} [options.safeList] - Array of strings or RegExps to exclude from deletion (e.g. dynamic images).
 * @param {boolean} [options.scanJs] - If true, scans JS bundles for references. Safer, but might keep more unused images.
 * @returns {import('vite').Plugin} The Vite plugin object.
 */
export const removeOriginalImages = (options = {}) => {
  const { safeList = [], scanJs = false } = options;
  let shouldRun = false;
  let logger;

  return {
    name: "vite-remove-original-images",
    enforce: /** @type {'post'} */ ("post"),
    apply: /** @type {'build'} */ ("build"),

    configResolved(config) {
      const isProd = config.isProduction || config.mode === "production";
      const isSsrBuild = !!config.build.ssr;

      // Only run cleanup during the production build phase.
      // (Based on previous logs, this corresponds to when isSsrBuild is true in this specific setup).
      shouldRun = isProd && isSsrBuild;
      logger = config.logger;

      if (shouldRun)
        logger.info("[Astro Clean] Memory-level cleanup enabled.", {
          timestamp: true,
        });
    },

    generateBundle(_, bundle) {
      if (!shouldRun) return;

      const bundleEntries = Object.entries(bundle);
      const astroGeneratedAssets = new Set();

      // 1. Collect names of assets generated by Astro
      for (const asset of Object.values(bundle)) {
        if (asset.type === "asset" && asset.name) {
          astroGeneratedAssets.add(asset.name);
        }
      }

      // 2. Collect raw duplicates marked for deletion
      const candidates = new Set();
      for (const [fileName, asset] of bundleEntries) {
        if (
          asset.type === "asset" &&
          fileName.startsWith("_astro/") &&
          !asset.isEntry &&
          astroGeneratedAssets.has(asset.name) &&
          isRedundant(fileName) &&
          !isSafe(fileName, safeList) // Check against whitelist
        ) {
          candidates.add(fileName);
        }
      }

      // If nothing to delete, exit silently (to avoid cluttering logs)
      if (candidates.size === 0) return;

      // Only log if there is actual work to do
      process.stdout.write("\n");
      logger.info("Detecting redundant (raw) source images in memory...", {
        timestamp: true,
      });

      // 3. SCAN: Check codes (HTML/CSS/JSON/MD) for live references
      for (const [fileName, chunk] of bundleEntries) {
        const isText =
          chunk.type === "asset" && /\.(html|css|json|txt|md)$/.test(fileName);
        const isJs = scanJs && chunk.type === "chunk"; // Optional JS scanning

        if (isText || isJs) {
          let content = "";

          if (isText) {
            content =
              typeof chunk.source === "string"
                ? chunk.source
                : chunk.source.toString("utf-8");
          } else if (isJs) {
            content = chunk.code;
          }

          for (const rawFile of candidates) {
            // If the generated code contains the raw file name, remove it from the death list
            if (content.includes(rawFile)) {
              candidates.delete(rawFile);
            }
          }
        }
      }

      // 4. Final deletion and result logging
      let count = 0;
      for (const rawFile of candidates) {
        delete bundle[rawFile];
        count++;
      }

      if (count > 0) {
        logger.info(
          `✓ Total of ${count} redundant images removed from output.\n`,
          { timestamp: true },
        );
      }
    },
  };
};

/**
 * Checks if a file is an image that should be considered for redundancy check.
 * Supported formats: jpg, jpeg, png, gif, svg, tiff, avif, webp.
 *
 * @param {string} fileName - The name of the file to check.
 * @returns {boolean} True if the file is a supported image format.
 */
function isRedundant(fileName) {
  return /\.(jpg|jpeg|png|gif|svg|tiff|avif|webp)$/i.test(fileName);
}

/**
 * Checks if a file matches the safeList.
 * @param {string} fileName
 * @param {(string|RegExp)[]} safeList
 */
function isSafe(fileName, safeList) {
  return safeList.some((pattern) => {
    if (pattern instanceof RegExp) return pattern.test(fileName);
    return fileName.includes(pattern);
  });
}

Usage (astro.config.mjs)

Simply import and initialize the plugin in your Vite configuration array:

import { defineConfig } from "astro/config";
import { removeOriginalImages } from "./integrations/vite-remove-original-images.mjs";

export default defineConfig({
  vite: {
    plugins: [removeOriginalImages()],
  },
});

Important Caveats & Best Practices

Before dropping this into your project, please keep the following in mind:

• Project Size: This method involves string-scanning HTML and CSS buffers in memory. This is highly effective and fast for small to medium-sized sites. However, for very large sites with thousands of generated pages, memory consumption might become an issue. For enterprise-scale applications, offloading image handling to external providers (like AWS S3, Cloudinary, etc.) is the recommended architectural pattern anyway.
• Static/Prerendered Only: Please only enable this for statically generated (SSG) or heavily prerendered sites. SSR (Server-Side Rendering) architectures handle dynamic asset resolutions differently.
• Testing: I am using this solution in my own projects and it completely resolves the redundant asset bloat for my static setups. However, I haven't stress-tested it against every possible edge case (e.g., highly complex dynamic image imports). I recommend verifying your dist output after the first build.

Hope this helps anyone dealing with deployment bloat until a native resolution is implemented!