appLayout property in nuxt config

[tender hinge]

Is the https://nuxt.com/docs/4.x/examples/features/layouts doc ahead of its time? Because it lists a cool feature about defining layouts via routeRules, but it appears the MR for this feature has only been merged 3 weeks ago and no nuxt release has happened since then? I have updated nuxt to the latest and it does not work as the docs describe. I also get a TS error that appLayout is not a valid property for routeRules, further hinting that this does not exist yet in the latest release?

[summer mango]

Hi @tender hinge. I'm kapa.ai, your friendly support bot. I will try to answer your question by searching through the knowledge base. :wave:

---

You’re right: the docs are slightly ahead of the latest stable Nuxt release.

The appLayout support in routeRules was added in a recent PR and is not available in the Nuxt version you’re currently using. The feature is implemented in this merged PR, which shows the exact routeRules syntax you mention:

export default defineNuxtConfig({
  routeRules: {
    '/admin': { appLayout: 'admin' },
    '/dashboard/**': { appLayout: 'dashboard' }
  }
})

[appLayout PR]

A user in a related issue ran into the same problem: they tried to use appLayout following the docs, found it didn’t work, and then realized their Nuxt version didn’t yet include the PR; they noted that the version with this feature “has not been released yet.” [appLayout issue]

So:

• The docs example you linked describes a feature that’s merged in Nuxt’s codebase but not yet in the latest published release.
• That’s why TypeScript complains that appLayout is not a valid routeRules property and why it doesn’t work at runtime.
• Once a Nuxt release including PR #31092 is published, the appLayout option in routeRules should start working as documented.

---

Note: you can ask me a follow up question by @ mentioning me again :speech_balloon:

@tender hinge Kapa.ai is still learning and improving, please let me know how I did by reacting below.

[tender hinge]

@summer mango Why would official docs include features that are not released yet?

[summer mango]

Let me check the knowledge base for you again. One moment! :books:

---

The knowledge sources don’t contain an explicit explanation from the Nuxt team about why unreleased features sometimes appear in the official docs, so I can’t give a definitive, “official” reason.

What we can see from the sources is:

• The appLayout support in routeRules was merged in a PR (feat(nuxt): support appLayout in route rules) with the documented usage you’re referring to. [appLayout PR]
• A user reported that appLayout from the docs didn’t work and discovered that the version containing the feature “has not been released yet,” confirming that the docs were ahead of the latest published Nuxt version. [appLayout issue]

However, there is no statement in these documents explaining the documentation process or why this mismatch happened. So all I can say with confidence is:

• The docs for appLayout describe a feature that exists in the main codebase but was not yet part of a tagged/released Nuxt version at the time of that issue.
• The knowledge sources do not explain why the docs were updated before a release, nor whether this is intentional policy or an oversight.

---

Note: you can ask me a follow up question by @ mentioning me again :speech_balloon:

@tender hinge Kapa.ai is still learning and improving, please let me know how I did by reacting below.

[steel cedar]

Hi @tender hinge
The reason why docs sometimes ahead is the follow: If a PR is merged, the Features/Fixes are first available on Next release. But the docs are retrieved from nuxt.com (from the GitHub repo) and you can see all changes directly.

Is not the best, yes. but it's due to technical reasons.

[tender hinge]

I see, I understand the technical reason but DX-wise it's very confusing / unclear. Maybe at least some info that the docs might be out of sync with latest release might help. Thank you for taking time to explain 🙂