vite plugin theme shadowing

Gatsby inspired theme component shadowing for Vite and Astro projects.

Allows users of a theme package to override any file in that theme's src/ directory by placing a file at the matching path inside their own src/<theme-name>/ directory — without forking or patching the theme.

How it works

Gatsby's shadowing is a Webpack resolver plugin that intercepts module resolution and redirects imports of theme-pkg/src/foo.js to a user's shadow file at src/theme-pkg/foo.js.

This plugin does the exact same thing using Vite's resolveId hook, which runs before any other resolver. When a file from a registered theme package is imported anywhere in the build graph, the plugin:

1. Detects that the resolved path lives inside a theme's src/ directory
2. Computes the relative path within that src/
3. Searches for a shadow file in this priority order:
   • User's project src/<theme-name>/<relative-path> ← always wins
   • Later themes in the themes array (last-listed theme has highest priority)
   • Extra shadowRoots if provided
4. If a shadow is found, returns it — otherwise, lets Vite use the original

my-theme/src/components/Header.tsx   ← original
     ↓
src/my-theme/components/Header.tsx   ← user shadow (wins)

Installation

npm install -D vite-plugin-theme-shadowing

Usage

Vite (vite.config.ts)

import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react'
import { themeShadowing } from 'vite-plugin-theme-shadowing'
import path from 'node:path'

export default defineConfig({
  plugins: [
    react(),
    themeShadowing({
      projectSrc: path.resolve(__dirname, 'src'),
      themes: ['my-design-system', 'my-blog-theme'],
    }),
  ],
})

Astro (astro.config.mjs)

import { defineConfig } from 'astro/config'
import { themeShadowing } from 'vite-plugin-theme-shadowing'

export default defineConfig({
  vite: {
    plugins: [
      themeShadowing({
        projectSrc: './src',
        themes: ['my-astro-theme'],
      }),
    ],
  },
})

Shadowing a file

Say you've installed my-blog-theme which has this structure:

node_modules/my-blog-theme/src/
  components/
    Header.tsx
    Bio.tsx
  layouts/
    Post.astro

To shadow Bio.tsx, create:

src/
  my-blog-theme/
    components/
      Bio.tsx    ← your shadow

That's it. Every import of my-blog-theme's Bio.tsx in the entire build will now resolve to your file.

Extending (wrapping) the original

You can import the original component from within your shadow:

// src/my-blog-theme/components/Bio.tsx
import OriginalBio from 'my-blog-theme/src/components/Bio'

export default function Bio(props) {
  return (
    <div className="custom-wrapper">
      <OriginalBio {...props} />
      <p>Extra content from my shadow</p>
    </div>
  )
}

⚠️ Vite will detect this as a circular reference if not handled carefully. The safest pattern is to import from the theme package's public API (its index.ts) rather than directly from src/, or use the ?no-shadow query param escape hatch (see below).

Options

| Option | Type | Default | Description | |---|---|---|---| | projectSrc | string | ./src | Path to user's source directory | | themes | string[] | required | npm package names of theme packages | | shadowRoots | string[] | [] | Extra directories to scan for shadows | | extensions | string[] | see below | Extensions to probe for extensionless imports | | debug | boolean | false | Log shadow resolution to console |

Default extensions:

.tsx .ts .jsx .js .mjs .astro .svelte .vue .css .scss .sass .less .json

Priority rules

When multiple themes are installed, the last theme in the themes array wins. This matches Gatsby's behaviour exactly.

themes: ['gatsby-theme-blog', 'gatsby-theme-blog-core']
//        lower priority       higher priority (wins)

The user's project always overrides everything regardless of order.

Full order (high → low):

user projectSrc  >  shadowRoots (reversed)  >  peer themes (reversed)  >  original

Theme authoring guide

To make your theme shadowable, ensure your src/ directory contains the files you want to expose:

my-theme/
  src/
    components/
      Header.tsx     ← shadowable
      Footer.tsx     ← shadowable
    utils/
      format.ts      ← shadowable
  package.json

No special configuration is needed in the theme itself — shadowing is entirely consumer-side.

Recommended: export a public API

// my-theme/index.ts  ← public re-exports
export { default as Header } from './src/components/Header'
export { default as Footer } from './src/components/Footer'

This lets theme consumers import from the public API while still being able to shadow internals.

Differences from Gatsby

| Feature | Gatsby | This plugin | |---|---|---| | Build tool | Webpack | Vite (Rollup) | | Framework | React only | Framework-agnostic | | Theme discovery | gatsby-config.js | Explicit themes array | | Last-wins ordering | ✅ | ✅ | | Extend/wrap originals | ✅ | ✅ | | Monorepo/symlink support | Partial | Via Vite's native resolver | | File watching (HMR) | ✅ | ✅ (Vite handles this) |

License

MIT

Author

Ash Hitchcock