astro-debug-build-filter

Astro integration for conditional page filtering. Mark your pages as intended for 'debug' builds only and ensure they aren't accidentally published in your production builds.

How it works

• Enabled only in release mode (when BUILD_PROFILE is not DEBUG). Set BUILD_PROFILE=DEBUG to disable filtering.
• Dev (astro:server:setup):
  • Middleware blocks requests whose path matches the debug route pattern (by default any path under /debug).
  • Also blocks exact routes derived from pages flagged via frontmatter.
• Config (astro:config:setup):
  • Blocks disallowed @astro-page: virtual modules early by returning an empty module, preventing inclusion.
• Build (astro:build:setup):
  • Removes disallowed pages from the build graph before output (so they never get generated).

What’s filtered by default

• Routes matching the pattern /(^|\/)debug(\/|$)/ (i.e. anything under /debug).
• Files with frontmatter flag debug: true in .astro/.md/.mdx (also accepts some other 'truthy' values)

Limitations

• requires Astro v5.13 or higher
• only intended for use with Astro in static site generation mode

Usage

Setup

Add astro-debug-build-filter to your project:

bun add -d astro-debug-build-filter

In your astro.config.ts:

import { defineConfig } from 'astro/config'
import astroDebugBuildFilter from 'astro-debug-build-filter'

export default defineConfig({
  integrations: [astroDebugBuildFilter()]
})

Now all pages identified as debug-only will be filtered out in all builds.

To enable 'debug' pages again, set environment variable BUILD_PROFILE=DEBUG. For example:

BUILD_PROFILE=DEBUG bunx astro build
# or
BUILD_PROFILE=DEBUG bunx astro dev

Filtering is active whenever BUILD_PROFILE is not DEBUG. Or to phrase another way: your debug pages will only show up when you explicitly set BUILD_PROFILE to DEBUG.

Configuration details

The integration accepts an optional options object. Defaults are safe and work out-of-the-box:

• patterns: array of RegExp or string prefixes. Default: /(^|\/)debug(\/|$)/.
  • String values are treated as a simple prefix match on the route string, e.g. "/admin" matches /admin and /admin/settings.
  • String prefixes are not segment-aware. If you need segment-aware matching, use a regular expression
• frontmatterField: string name of the frontmatter flag. Default: "debug".
• logoutput: boolean to enable console logging. Default: true.

import astroDebugBuildFilter from 'astro-debug-build-filter'

export default defineConfig({
  integrations: [
    astroDebugBuildFilter({
      // Blocked route patterns. Accepts RegExp or string prefixes.
      patterns: [/(^|\\/)debug(\\/|$)/],

      // Frontmatter flag name that marks a page as debug-only.
      frontmatterField: 'debug',

      // Output filtering details to console
      logoutput: true,
    })
  ]
})

Plugin developer notes

Testing

bun install
bun run test # concise summary only
bun run testv # usual verbose test output

bun run clean # forces cleanup of some temp files which are re-used for faster integration tests

ASTRO_VERSION=5.13 bun run test # run against specific Astro version

Changelog

vFuture

• (maybe) more configuration options
• (maybe) support server-side render mode

v1.0.0 (2025-09-04)

• build disallowed routes cache with astro:routes:resolved hook
• add logging for filtering (on by default)
• convert all file operations to async
• integratin test refactoring
  • support testing against specific Astro versions
  • build test projects with package.json and bun install
  • cleanup script
• utils can handle file URLs
• established minimum supported version
• clean up Typescript definitions
• better error handling
• misc minor bug fixes and redundant code cleanup

v0.2.1

• add index.d.ts to remove Typescript warnings on package consumers

v0.2.0 (2025-09-01)

• support Astro sites with non-standard srcDir (e.g. app/pages instead of the default src/pages)
• configurable pattern for which routes to filter
• debounce dev-mode file watcher when recomputing routes
• better test guardrails around erroring routes
• better NPM package hygiene
• route normalisation bug fixes

v0.1.1 (2025-08-30)

• now supports dev server mode (previously only worked on build output)
• rewrote integration tests to perform better and be better citizens (e.g. avoid ENOSPC in /tmp)

v0.1.0 (2025-08-29)

• fix case sensitivity of BUILD_PROFILE checks
• integration tests against actual Astro project
• better explicit handling of static and dynamic */debug/* routes

v0.0.3

• filtering was backwards - fixed
• better defined behaviour
• more thorough tests as documentation of expected behaviours

v0.0.1

• Initial release
• Default functionality implemented

Credits

• [Nathan Chere]