feat(nuxt): warn when page uses a layout without <NuxtLayout>

[luc122c]

🔗 Linked issue

#19392

❓ Type of change

• 📖 Documentation (updates to the documentation, readme or JSdoc annotations)
• 🐞 Bug fix (a non-breaking change that fixes an issue)
• 👌 Enhancement (improving an existing functionality like performance)
• ✨ New feature (a non-breaking change that adds functionality)
• 🧹 Chore (updates to the build process or auxiliary tools and libraries)
• ⚠️ Breaking change (fix or feature that would cause existing functionality to change)

📚 Description

Resolves #19392 by adding a warning in development if layouts are present but the <NuxtLayout> component has not been used. All changes are dev-only and should be tree-shaken out.

We first add a new variable nuxtApp.payload._isNuxtLayoutUsed which is false by default. When the <NuxtLayout> component is declared, this is switched to true. A new plugin is added which runs onNuxtReady. If Nuxt Layout has not been used, then it counts the layouts registered and if this is greater than 0, displays a warning. #build/layouts provides the layouts in the src directory, as well as in any layers.

📝 Checklist

• I have linked an issue or discussion.
• I have updated the documentation accordingly.

[stackblitz]

Run & review this pull request in StackBlitz Codeflow.

[luc122c]

Agh, I commited to my main branch 😞

[luc122c]

Please could the CI be re-run, I think it's an unrelated timeout.

[danielroe]

This is a nice improvement 👌

[codecov-commenter]

Codecov Report

All modified and coverable lines are covered by tests ✅

❗ No coverage uploaded for pull request base (main@db74ead). Click here to learn what that means.

Additional details and impacted files

@@           Coverage Diff           @@
##             main   #24116   +/-   ##
=======================================
  Coverage        ?   58.76%           
=======================================
  Files           ?        5           
  Lines           ?      861           
  Branches        ?       46           
=======================================
  Hits            ?      506           
  Misses          ?      355           
  Partials        ?        0           

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

[nathanchase]

Question: what about if you only ever declare your layouts for your page components in definePageMeta - is this no long recommended? It doesn't seem "in error" if your layouts are all declared this way, is it?

definePageMeta({
  layout: 'user-layout',
});

[danielroe]

@nathanchase That should be totally fine and is recommended. What is the issue you are experiencing?

[nathanchase]

@nathanchase That should be totally fine and is recommended. What is the issue you are experiencing?

With the nightly build, I was noticing the warning that I had layout files but didn't use <NuxtLayout>.

[danielroe]

Were you visiting a page with a layout defined in metadata, but not using <NuxtLayout>?

[nathanchase]

Correct.

[danielroe]

Well, then that's exactly what this PR is meant to warn against. You have defined a layout for a page but aren't displaying that layout. Or am I missing something?

[nathanchase]

No, I have the layout defined in the meta tag, but is that not enough to indicate that the page should be automatically wrapped by that layout? Are you meant to additionally add a <NuxtLayout layout="user-layout"></NuxtLayout> around your page component, as well as add it to definePageMeta?

[danielroe]

No, just <NuxtLayout><NuxtPage /></NuxtLayout> is enough. NuxtLayout defaults to the layout specified by the current route.

And this isn't a change. It's not automatically added, which is why we created this PR. Layouts can be used on their own or separately so you need to add it to your app.vue when you start defining them in your route metadata or nothing will happen.

[nathanchase]

What about nested layouts?

Example:
I have a default.vue layout in /layouts.

Then I have another layout (/layouts/user-layout.vue) that is wrapped like so:

<NuxtLayout name="default">
...
</NuxtLayout>

Then in a page component, I reference the user-layout with just definePageMeta:

definePageMeta({
  layout: 'user-layout',
});

This has worked without issue until now.

[danielroe]

Perhaps you had better create a new issue with a reproduction. This PR did not change the actual behaviour at all, only added some console logging to avoid users expecting to see a layout but not seeing one because they forgot to add <NuxtLayout> to their app. But that doesn't seem to be your situation.

[nathanchase]

Perhaps it is the absence of an app.vue altogether?

[danielroe]

I still don't understand the issue you're having.

[nathanchase]

The problem is that I've been using layouts for months and it all works as expected, but this PR seems to think I was doing it incorrectly and sends a warning that I'm not using NuxtLayout, even though I am using <NuxtLayout name="default"> in several layout files. Will try to reproduce it. Just wanted to raise the flag here in case it was an issue with how this was determining the warning.

[danielroe]

So you are using it.

That sounds like a bug in how we are detecting usage, then. Could you create a reproduction?