Nuxt layers overwrite not working
I have a project with a submodule where a nuxt project is in.
In the root nuxt config i'm extending this submodule. When I create a component with the same name in the same folder like in the submodule it does not get overwritten
30 Replies
Hi @Spctr. I'm kapa.ai, your friendly support bot. I will try to answer your question by searching through the knowledge base. :wave:
----------------------
When using Nuxt layers, components in the main project should override components with the same name and path in extended layers. However, if overriding is not working as expected, there are a few things to check based on the official documentation and related issues:
1. Layer Structure and Extending
Ensure your main project’s
Nuxt auto-imports components and resolves conflicts by giving priority to the main project. If you have issues, check if the
Make sure your layer is placed correctly. Layers should be in the project root or in the
Nuxt loads modules and components from extended layers first, then from the main project, so the main project should always override the layer Corrected Module Loading Order in Layers. 5. Cache and Build Artifacts
Sometimes, stale build artifacts can cause unexpected behavior. Try deleting
Ensure your main project’s
nuxt.config.ts
is correctly extending the submodule (layer) using the extends
property:
The directory structure in both the main project and the layer should mirror each other for overrides to work (e.g., both have components/MyComponent.vue
) Authoring Nuxt Layers.
2. Component Auto-Import and NamingNuxt auto-imports components and resolves conflicts by giving priority to the main project. If you have issues, check if the
experimental.normalizeComponentNames
option is affecting component resolution. You can try disabling it in your nuxt.config.ts
:
normalizeComponentNames
3. Correct Directory PlacementMake sure your layer is placed correctly. Layers should be in the project root or in the
layers/
directory at the root. If a layer is inside another folder (like app/layers/
), auto-registration may not work as expected. This was a known issue and has been fixed, but if you’re on an older version, try moving your layer to the root Layers.
4. Module and Component Loading OrderNuxt loads modules and components from extended layers first, then from the main project, so the main project should always override the layer Corrected Module Loading Order in Layers. 5. Cache and Build Artifacts
Sometimes, stale build artifacts can cause unexpected behavior. Try deleting
.nuxt
, node_modules
, and running a fresh install and build.
If after checking these points the override still does not work, there may be a specific issue with your setup or a bug. In that case, providing a minimal reproduction (e.g., on StackBlitz or GitHub) can help diagnose the problem further.
If you need more detailed troubleshooting, please share your directory structure and relevant config files.
----------------------
Note: you can ask me a follow up question by @ mentioning me again :speech_balloon:
----------------------<@320895029008793600> Kapa.ai is still learning and improving, please let me know how I did by reacting below.
@kapa.ai I don't have a layers folder. My
standard/
folder has the layer in it directlyLet me check the knowledge base for you again. One moment! :books:
----------------------
You do not need to use a
layers/
folder specifically—your layer can be in any directory, such as standard/
, as long as you reference it correctly in your nuxt.config.ts
using the extends
property:
The important part is that the path you provide in extends
points to the directory containing the layer's nuxt.config.ts
. The directory name itself (e.g., standard/
vs layers/standard/
) does not affect the layer functionality, as long as the structure inside the layer matches Nuxt's expectations (e.g., it has its own components/
, pages/
, etc.) Authoring Nuxt Layers.
However, if you want auto-registration of layers (where Nuxt automatically picks up layers without specifying them in extends
), this only works for layers inside the layers/
directory at the project root. If your layer is in standard/
, you must explicitly add it to extends
in your config Layers.
So, your setup with a standard/
folder is valid, but you need to reference it manually in your config. If component overriding is still not working, the issue is likely elsewhere (such as directory structure, naming, or build cache), not the folder name.
----------------------
Note: you can ask me a follow up question by @ mentioning me again :speech_balloon:
----------------------<@320895029008793600> Kapa.ai is still learning and improving, please let me know how I did by reacting below.
@kapa.ai
my root nuxt.config.ts
my
standard/nuxt.config.ts
in the root and in the standard is an app/
directory where components/ pages/ and everything is inLet me check the knowledge base for you again. One moment! :books:
----------------------
Your setup—with both the root project and the
According to the Nuxt documentation, when you have the same component (or page) in both the main project and the extended layer, the main project’s version should take precedence and override the one from the layer, provided the directory structure and filenames match Authoring Nuxt Layers. Key Points to Check: 1. Directory Structure:
Both the root and the layer should have the same structure, e.g.: The root’s
You do not need a
The
Nuxt auto-imports components from all registered layers, and the main project’s components should override those from layers if they have the same name and path components directory. 5. Cache Issues:
If overrides are not working, try clearing
- Double-check that the filenames and relative paths match exactly. - Ensure you are not using any custom component registration logic that could interfere. - If you are using custom component directories or prefixes, make sure the configuration order is correct Custom Directories. - If you are using TypeScript, ensure your
standard/
layer having their own app/
directories containing components/
, pages/
, etc.—is valid in Nuxt 4, as long as you reference the layer correctly in your root nuxt.config.ts
using the extends
property, which you are doing.
Component/Page Overriding Should WorkAccording to the Nuxt documentation, when you have the same component (or page) in both the main project and the extended layer, the main project’s version should take precedence and override the one from the layer, provided the directory structure and filenames match Authoring Nuxt Layers. Key Points to Check: 1. Directory Structure:
Both the root and the layer should have the same structure, e.g.: The root’s
MyComponent.vue
should override the one in standard/
.
2. No Need for a layers/
Directory:You do not need a
layers/
directory; any directory (like standard/
) can be used as a layer as long as you reference it in extends
Layers.
3. Aliases and Imports:The
~
alias points to the app/
directory by default, so ~/components
refers to app/components/
in the current layer or project New Directory Structure.
4. Component Auto-Import:Nuxt auto-imports components from all registered layers, and the main project’s components should override those from layers if they have the same name and path components directory. 5. Cache Issues:
If overrides are not working, try clearing
.nuxt
and node_modules
and rebuilding, as stale caches can cause unexpected behavior.
If Overriding Still Does Not Work:- Double-check that the filenames and relative paths match exactly. - Ensure you are not using any custom component registration logic that could interfere. - If you are using custom component directories or prefixes, make sure the configuration order is correct Custom Directories. - If you are using TypeScript, ensure your
tsconfig
includes the correct paths for both the root and layer app/
directories, as recent changes ensure type resolution works for layers/*/app/
folders PR #32592.
If all of the above is correct and it still does not work, the knowledge sources do not provide further troubleshooting steps for this specific scenario. In that case, it may be a bug or require a minimal reproduction for further investigation.
----------------------
Note: you can ask me a follow up question by @ mentioning me again :speech_balloon:
----------------------<@320895029008793600> Kapa.ai is still learning and improving, please let me know how I did by reacting below.
both files have the same name and are in the same strucutre .. but it's not working
@kapa.ai check the screenshot .. two files are in the root but it doesn't change anything

Let me check the knowledge base for you again. One moment! :books:
----------------------
I'm sorry, but I do not have access to any screenshot in your message. If you intended to share a screenshot, please upload it or provide its content so I can review it and give you a more accurate answer.
Based on the knowledge sources, if you have two files with the same name and path in both your root project and the extended layer, the file in the root project should override the one from the layer, provided the directory structure and filenames match exactly Authoring Nuxt Layers. If this is not happening, and you have confirmed the structure is correct, it could be a cache issue or a bug.
If you can provide the screenshot or more details, I can help you further.
----------------------
Note: you can ask me a follow up question by @ mentioning me again :speech_balloon:
----------------------
<@320895029008793600> Kapa.ai is still learning and improving, please let me know how I did by reacting below.
@kapa.ai how do i handle paths. In my root app/ structure there are
"~/.."
paths for components.. do I need an alias or something? the wrong paths are out of the standard/ layer so i need to link the file, which is in the root/app/ folder to the standard/app/Let me check the knowledge base for you again. One moment! :books:
----------------------
When working with Nuxt layers, global aliases like
Nuxt automatically creates named aliases for layers in the
- Use relative paths inside layers to reference layer-local files. - Use
~/
and @/
always resolve to the root project's app/
directory, not to the layer's app/
directory. This means that if you use ~/components/Foo.vue
in your layer, it will import from the root project's app/components/Foo.vue
, not from the layer's own components folder. This is by design and is documented in the Nuxt docs:
When importing using global aliases (such asHow to handle this: - Within a layer, use relative imports (e.g.,~/
and@/
) in a layer components and composables, note that these aliases are resolved relative to the user's project paths. As a workaround, you can use relative paths to import them, or use named layer aliases.
Relative Paths and Aliases
../components/Foo.vue
) to reference files inside the layer itself.
- If you want to reference files in the root project from the layer, you can use the ~/
alias.
- If you want to reference files inside the layer from the root project, you need to use relative paths or set up a named layer alias (e.g., #layers/standard
).
Example:
If you have a component in standard/app/components/Foo.vue
and want to import it from another file in the same layer, use:
If you want to import a component from the root project's app/components/Bar.vue
, use:
Aliases for layers:Nuxt automatically creates named aliases for layers in the
layers/
directory (e.g., #layers/standard
), but if your layer is not in layers/
, you can set up a custom alias in your nuxt.config.ts
if needed Nuxt Configuration: alias.
Summary:- Use relative paths inside layers to reference layer-local files. - Use
~/
to reference files in the root project.
- Consider setting up a custom alias if you need to reference files in your layer from the root project or vice versa.
If you need to link files from the root app/
folder to the standard/app/
folder, you must use the correct alias or a relative path, as described above. There is no built-in way for ~/
to point to the layer's app/
directory; it always points to the root project's app/
directory Relative Paths and Aliases.
----------------------
Note: you can ask me a follow up question by @ mentioning me again :speech_balloon:
----------------------<@320895029008793600> Kapa.ai is still learning and improving, please let me know how I did by reacting below.
@kapa.ai
I installed all needed packages but I think that the root nuxt.config.ts doesn't know defineNuxtConfig() .. cause it's marked red and has this message
Vue: Cannot find name defineNuxtConfig. Did you mean defineNitroConfig?
could this be a problem to override files?Let me check the knowledge base for you again. One moment! :books:
----------------------
The error message
in your
This error does not affect Nuxt's layer overriding mechanism. If your overrides are not working, the cause is elsewhere (such as directory structure, cache, or import paths), not this TypeScript warning. ---------------------- Note: you can ask me a follow up question by @ mentioning me again :speech_balloon: ----------------------
Cannot find name 'defineNuxtConfig'. Did you mean defineNitroConfig?
in your
nuxt.config.ts
is a TypeScript/IDE type resolution issue and is not related to your ability to override files via Nuxt layers.
According to the official documentation, defineNuxtConfig
is globally available in nuxt.config.ts
and does not require an explicit import Nuxt Configuration nuxt.config.ts. However, some users have reported that their IDE (especially VS Code) sometimes fails to recognize this, particularly after upgrading Nuxt or TypeScript, or when using certain versions of Nuxt 4 alpha. This is a known issue and does not affect the actual runtime behavior of Nuxt, nor does it prevent file overrides from working Github Issue: Cannot find name 'defineNuxtConfig'.
What you can do:
- You can safely ignore this error if your project builds and runs correctly.
- If you want to resolve the IDE warning, you can explicitly import defineNuxtConfig
at the top of your nuxt.config.ts
:
This is optional and only for IDE/type-checking purposes nuxt.config.ts.
Summary:This error does not affect Nuxt's layer overriding mechanism. If your overrides are not working, the cause is elsewhere (such as directory structure, cache, or import paths), not this TypeScript warning. ---------------------- Note: you can ask me a follow up question by @ mentioning me again :speech_balloon: ----------------------
<@320895029008793600> Kapa.ai is still learning and improving, please let me know how I did by reacting below.
@kapa.ai
I've added an alias in my root nuxt config and I'm tryin to use it but it's not working
my component
Let me check the knowledge base for you again. One moment! :books:
----------------------
Based on the knowledge sources, Nuxt allows you to define custom aliases in your
The value for your alias should be an absolute path, not a relative one. In your config, you have: This should be: This ensures the alias resolves correctly at runtime and for TypeScript Nuxt Configuration: alias. 2. Alias Availability
Aliases defined in
If you are using TypeScript, make sure your IDE picks up the generated
Once the alias is set up correctly, you should be able to import your component like this: Summary:
Update your alias definition to use an absolute path. This should resolve the issue with the alias not working in your imports. If you have done this and it still does not work, double-check that your build cache is cleared and that your IDE is using the correct TypeScript configuration. If the problem persists, the knowledge sources do not provide further troubleshooting steps for this specific scenario. ---------------------- Note: you can ask me a follow up question by @ mentioning me again :speech_balloon: ----------------------
nuxt.config.ts
using the alias
property. These aliases are then available for JavaScript and CSS imports in your project, and are also automatically added to the generated TypeScript configuration for type support and auto-complete Nuxt Configuration: alias.
However, there are a few important points and potential pitfalls:
1. Alias Path Should Be AbsoluteThe value for your alias should be an absolute path, not a relative one. In your config, you have: This should be: This ensures the alias resolves correctly at runtime and for TypeScript Nuxt Configuration: alias. 2. Alias Availability
Aliases defined in
nuxt.config.ts
are available for imports in your application code (components, composables, etc.), but not in the nuxt.config.ts
file itself or in build tools that run before Nuxt processes the config Nuxt Configuration: alias.
3. TypeScript SupportIf you are using TypeScript, make sure your IDE picks up the generated
.nuxt/tsconfig.json
files, which include your custom aliases. If you have a custom tsconfig.json
, ensure it references the generated configs as described in the docs tsconfig.json.
4. Component ImportOnce the alias is set up correctly, you should be able to import your component like this: Summary:
Update your alias definition to use an absolute path. This should resolve the issue with the alias not working in your imports. If you have done this and it still does not work, double-check that your build cache is cleared and that your IDE is using the correct TypeScript configuration. If the problem persists, the knowledge sources do not provide further troubleshooting steps for this specific scenario. ---------------------- Note: you can ask me a follow up question by @ mentioning me again :speech_balloon: ----------------------
<@320895029008793600> Kapa.ai is still learning and improving, please let me know how I did by reacting below.
@kapa.ai
Inside my root nuxt config I'm getting this error
my tsconfig.json in the root
Let me check the knowledge base for you again. One moment! :books:
----------------------
The error message:
Your error is likely caused by a conflict or override in your TypeScript configuration. Follow Nuxt's recommended approach for
The import.meta meta-property is only allowed when the --module option is es2020, es2022, esnext, system, node16, node18, or nodenextindicates that your TypeScript configuration's
module
option must be set to one of the supported module types for import.meta
to work.
What the knowledge sources say:
- The import.meta
property is supported when the TypeScript module
option is set to es2020
, es2022
, esnext
, system
, node16
, node18
, or nodenext
(Nuxt Import Meta Docs).
- Your current tsconfig.json
sets "module": "Node16"
, which is a valid value for supporting import.meta
(TypeScript Configuration Splitting).
Possible issues:
- If you are extending another tsconfig.json
(in your case, ./standard/tsconfig.json
), the extended config might override your module
setting. TypeScript uses the last defined value, so check the effective value of module
after merging.
- Nuxt generates multiple tsconfig
files for different contexts, and recommends using project references instead of extending a single config. Overwriting options such as "compilerOptions.module"
in your own config can cause issues, as Nuxt expects to manage these settings itself (Nuxt Directory Structure: tsconfig.json).
Recommended solution:
- Let Nuxt manage your TypeScript config: Use a root tsconfig.json
with only project references, as recommended:
This allows Nuxt to set the correct module
option for each context and avoids conflicts (Nuxt Directory Structure: tsconfig.json).
- If you must customize compilerOptions
, do not override module
, target
, or moduleResolution
in your own config, as this can break Nuxt's expectations and lead to errors like the one you are seeing.
Summary:Your error is likely caused by a conflict or override in your TypeScript configuration. Follow Nuxt's recommended approach for
tsconfig.json
and avoid setting module
yourself. Let Nuxt's generated configs handle it for you.
If you need to customize other options, do so in the appropriate place, but do not override module
, target
, or moduleResolution
(Nuxt Directory Structure: tsconfig.json).
----------------------
Note: you can ask me a follow up question by @ mentioning me again :speech_balloon:
----------------------<@320895029008793600> Kapa.ai is still learning and improving, please let me know how I did by reacting below.
@kapa.ai I removed the extend in the tsconfig.json to set the module right .. but it still shows the error
Let me check the knowledge base for you again. One moment! :books:
----------------------
If you have removed the
Nuxt 4 generates multiple
The knowledge sources explicitly recommend not to override
Sometimes, stale build artifacts can cause persistent errors. Try deleting
If you have other
The knowledge sources indicate that you should use project references in your root
"extends"
from your tsconfig.json
and set "module": "Node16"
(or another supported value), but you are still seeing the error about import.meta
, the knowledge sources suggest a few things to check:
1. Let Nuxt Manage TypeScript ConfigurationsNuxt 4 generates multiple
tsconfig
files for different contexts and recommends using a root tsconfig.json
with only project references, not custom compilerOptions
. Overriding options like "module"
in your own config can cause issues, as Nuxt expects to manage these settings itself. The recommended root tsconfig.json
is:
This allows Nuxt to set the correct module
option for each context and avoids conflicts tsconfig.json.
2. Do Not Override module
The knowledge sources explicitly recommend not to override
module
, target
, or moduleResolution
in your own config, as this can break Nuxt's expectations and lead to errors like the one you are seeing tsconfig.json.
3. Clear Cache and RebuildSometimes, stale build artifacts can cause persistent errors. Try deleting
.nuxt
, node_modules
, and running a fresh install and build.
4. Check for Other tsconfig
FilesIf you have other
tsconfig.json
files in subdirectories (like in your standard/
layer), they might be interfering. Make sure only the root config is used for project references, as recommended.
Summary:The knowledge sources indicate that you should use project references in your root
tsconfig.json
and let Nuxt manage the TypeScript configuration. Overriding module
or other core options can cause the error you are seeing. If you follow the recommended setup and still see the error, the knowledge sources do not provide further troubleshooting steps for this specific scenario.
See Nuxt's recommended tsconfig setup
----------------------
Note: you can ask me a follow up question by @ mentioning me again :speech_balloon:
----------------------<@320895029008793600> Kapa.ai is still learning and improving, please let me know how I did by reacting below.
so .. atm this things are not working
- overriding components/pages/.. in the root
- aliases are not completely clear and not working
maybe someone could help
https://gitlab.com/spctr_dev/nuxt4-layers-demo-with-submodule/main
This is the demo project.. when set
it doesn't overwrites the default one in
~/submodule/app/components/menu/
The README.md
in ~/
contains the setuphas someone an idea or could test it?
maybe i did something wrong
@manniL sorry for the ping and for bothering .. maybe i've found the problem .. but I don't understand it completely
I've setup a layout
admin.vue
where i created a admin dashboard with a menu and buttons .. after putting the layout from the layer in the root .. the button was overwritten