astro-nice-asset-filenames

Astro integration for short, readable asset URLs.

Before:

By default, Astro's static build emits client-script chunks named after the synthetic module ID, with all the URL boilerplate replaced by underscores:

_assets/ThemeToggle.astro_astro_type_script_index_0_lang.BhEhlh7m.js
_assets/BaseLayout.Pt3ADYuj.css

After:

This integration shortens the script-block boilerplate and converts PascalCase to snake_case (or kebab-case):

_assets/theme_toggle.BhEhlh7m.js
_assets/base_layout.Pt3ADYuj.css

Contents

• Install
• Usage
• Options
• What it does
• Compatibility
• Development
• License

Install

npm install astro-nice-asset-filenames
# or: bun add, pnpm add, yarn add

Usage

// astro.config.mjs
import { defineConfig } from "astro/config";
import niceAssetFilenames from "astro-nice-asset-filenames";

export default defineConfig({
  integrations: [
    niceAssetFilenames()
  ],
});

Options

| Option | Type | Default | Description | | ----------- | --------- | ------- | ------------------------------------------------------------------------------------------------------ | | enabled | boolean | true | When false, the integration is a no-op. Handy for env-flag toggling while debugging. | | separator | string | "_" | Separator passed to decamelize. Use "-" for kebab. |

niceAssetFilenames({
  enabled: process.env.NICE_FILENAMES !== "0",
  separator: "-",
});

What it does

Three transforms, layered:

1. Strips Astro's script-block URL boilerplate. <File>.astro?astro&type=script&index=N&lang.ts becomes just <File>—no more _astro_type_script_index_0_lang in the filename.
2. Snake_cases (or kebab-cases) the basename. ThemeToggle → theme_toggle via decamelize, which handles acronym-heavy names correctly: OAuth2Client → o_auth_2_client, HTMLParser → html_parser.
3. Preserves the script-block index when it matters. A .astro file with multiple <script> blocks emits separate chunks. index=0 is dropped (the common case); index >= 1 is appended as -N so the filenames remain distinguishable: foo.HASH.js, foo-1.HASH.js, foo-2.HASH.js.

Compatibility

• Astro 6+ (the integration relies on Vite's Environment API, which Astro adopted in 6.0)
• Node ≥ 22.12.0 (matches Astro 6's minimum)

Tested against static builds on rather simple websites; be wary.

Server-output (SSR) and prerender-only builds should work the same way; if you run into edge cases, you can open an issue.

Development

npm test

Tests run against src/ directly via Node's built-in test runner.

License

MIT.