nuxt-preload-pruner
v1.1.1
Published
Opinionated preload & prefetch optimization for Nuxt 3. Prunes excessive resource hints from the build manifest and injects CSS preload hints at runtime.
Maintainers
elenhReadme
nuxt-preload-pruner
Opinionated preload & prefetch optimization for Nuxt 3. Strips excessive resource hints from your build manifest and intelligently re-injects CSS preload hints at runtime — improving LCP and FCP on mobile.
Why
Nuxt generates <link rel="preload"> and <link rel="prefetch"> hints for every chunk in the client manifest by default. On pages with many dynamic imports this causes network contention — the browser tries to preload dozens of resources simultaneously, delaying the critical ones.
This module takes a pragmatic approach:
- Prune first — remove all preload/prefetch hints from non-entry chunks
- Inject what matters — add preload hints for CSS files at the top of
<head>so styles resolve as early as possible
Quick Start
npm install nuxt-preload-pruner// nuxt.config.ts
export default defineNuxtConfig({
modules: ['nuxt-preload-pruner'],
})That's it. No configuration needed.
What It Does
① Build-time Manifest Pruning
Hooks into Nuxt's build:manifest and processes every chunk in the client manifest:
- Sets
preload = falseon all chunks - Sets
prefetch = falseon all chunks - Clears
dynamicImportsarrays - Only entry scripts (
isEntry + resourceType === 'script') keeppreload = true
This means your HTML only contains the essential <link rel="modulepreload"> for the entry script — all other resource hints are removed.
② Runtime CSS Preload Injection
A Nitro server plugin hooks into render:html during SSR:
- Scans
<head>for all_nuxt/*.cssstylesheet links - Re-inserts them as
<link rel="preload" as="style" crossorigin="anonymous">at the top of<head>
This ensures CSS files begin loading before the browser encounters the actual <link rel="stylesheet"> tags further down.
Production Only
The module skips entirely during dev mode and _prepare phase. It only activates in production builds, where these optimizations have real user-facing impact.
How to Verify
After building your Nuxt app for production:
npx nuxi buildCheck manifest pruning:
Open .output/server/chunks/build/client.manifest.mjs — only the entry script should have "preload": true. All other chunks should show "preload": false, "prefetch": false, "dynamicImports": [].
Check CSS preload hints:
node .output/server/index.mjs
curl -s http://localhost:3000 | grep 'rel="preload".*as="style"'You should see <link rel="preload" href="/_nuxt/....css" as="style" crossorigin="anonymous"> at the top of <head> for each CSS file.
Development
# Install dependencies
pnpm install
# Generate type stubs
pnpm dev:prepare
# Develop with the playground
pnpm dev
# Build the playground (production — module is active!)
pnpm dev:build
# Run ESLint
pnpm lint
# Run Vitest
pnpm testLicense
MIT