Core Concepts
Overriding
Overrides let you replace any file in web/, admin/, docs/, or shared_modules/ without editing the original. At build time, Nuxt resolves the override path instead of the source path.
Overrides are Nuxt-only. They do not apply to the compiler import cycle, Astro in production builds outside Nuxt, or generated hosts (web-next/, web-solid/, web-svelte/, …) unless separately configured.
How it works
- Mirror the original file path under
overrides/{package}/ - Nuxt dev/build scans
overrides/at startup - When a match exists, the override fully replaces the original - no merge, no partial patch
Original: web/src/composables/useAuth.ts
Override: overrides/web/src/composables/useAuth.tsDirectory layout
overrides/
├── web/
│ └── src/… # mirrors web/src/…
├── admin/
│ └── src/…
├── docs/
│ └── src/…
└── shared_modules/
└── nuc_colors/…Each subdirectory has a README.md with examples for that package.
Examples
Override a landing page section
Original: web/src/pages/home/index.vue
Override: overrides/web/src/pages/home/index.vueUse when you fork branding or layout for a white-label deployment while keeping the upstream web/ tree intact.
Override a composable
Original: web/src/composables/useAuth.ts
Override: overrides/web/src/composables/useAuth.tsUse when auth flow differs per deployment but the rest of the app stays the same.
Override a module API handler
Original: shared_modules/nuc_colors/supabase/api/handle.ts
Override: overrides/shared_modules/nuc_colors/supabase/api/handle.tsUse when backend behavior must diverge without forking the entire nuc_colors module.
Override docs layout
Original: docs/src/layouts/DocsLayout.astro
Override: overrides/docs/src/layouts/DocsLayout.astroNote: Astro override resolution depends on your docs build setup - verify in dev after adding the file.
Debugging overrides
When behavior differs from what you expect in source:
- Check
overrides/{package}/for a path matching the file you are reading - Temporarily rename or remove the override to confirm it is the active version
- Remember: overrides shadow entire files - a one-line change still requires copying the full file
What overrides are not
| Concern | Override? | Alternative |
|---|---|---|
| Portable component emit | No | Edit *.nuc.tsx, run pnpm compiler:build |
| Import emit back to authoring | No | pnpm compiler -- import --from=vue|react|solid|svelte |
| Generated product host (Next / Solid / Svelte / Astro) | No* | Edit web/, convert with make web --target=next|solid|svelte|astro |
| Environment-specific config | No | Root .env, web/.config/nuxt/runtime.ts |
| Database schema | No | Module migrations in shared_modules/nuc_*/supabase/ |
*Unless you add separate override tooling for converted shells - not part of the default Nuxt override scanner.
Best practices
- Keep overrides small in count - many overrides make upgrades hard
- Document why - add a comment at the top of override files explaining the fork reason
- Prefer modules - if multiple apps need the change, extend
shared_modules/instead - Sync upstream - when merging upstream Nucleify changes, diff override files against originals
- Do not commit secrets - overrides are source files; use
.envfor keys
Related docs
- Monorepo Layout -
overrides/in context - Modules - when to extend a module vs override
- Compiler - overrides excluded from import cycle