PR Description

🔗 Context & Motivation

Route groups (e.g. (marketing)/, (admin)/) allow organizing files without affecting the URL path. Previously, unrouting treated route group segments transparently, assigning meta.groups to individual child pages.

However, frameworks like Nuxt require the ability to define dedicated parent layout components for specific route groups (e.g. (marketing).vue wrapping all routes inside (marketing)/) without introducing path prefixes to the generated routes.

This PR adds first-class support for route group parent files (group).vue acting as pathless parent layout routes for (group)/ children.

🚀 What's Changed

1. Tree Representation (src/tree.ts):

   • buildTree, addFile, and removeFile now recognize (group).vue files and link them as layout parent nodes for their corresponding (group)/ children.
   • Preserves full backward compatibility when route groups do not define a (group).vue file (flat routes with meta.groups are retained).

2. Vue Router 4 Emitter (src/converters.ts):

   • Emits (group).vue as pathless parent layout routes with nested children.
   • Route Matching Priority: Enhanced compareRoutes so that when multiple pathless route group parents exist (all sharing path: ''), route groups containing default/index child routes are prioritized ahead of route groups without index routes. This prevents empty layout components from capturing root / navigations in Vue Router.
   • Seamlessly handles nested combinations:
     • Group layouts inside standard directories: pages/products/(marketing).vue
     • Standard nested routes inside group layouts: pages/(marketing)/blog.vue + pages/(marketing)/blog/post.vue
     • Group layouts nested inside standard parent files: pages/users.vue + pages/users/(admin).vue

3. Incremental HMR (addFile / removeFile):

   • Dynamically adding or deleting (group).vue seamlessly upgrades flat group routes to nested layout routes and vice-versa without needing full tree rebuilds.

4. Documentation (README.md):

   • Added Group Layout pattern to the supported routing patterns table.

📂 Route Generation Examples

1. Root Route Groups with Parent Layout

Files:

pages/
├── (marketing).vue
├── (marketing)/
│   ├── index.vue
│   └── about.vue
├── (admin).vue
└── (admin)/
    ├── dashboard.vue
    └── settings.vue

Vue Router Output:

[
  {
    "path": "",
    "file": "pages/(marketing).vue",
    "meta": { "groups": ["marketing"] },
    "children": [
      { "name": "about", "path": "about", "file": "pages/(marketing)/about.vue", "meta": { "groups": ["marketing"] } },
      { "name": "index", "path": "", "file": "pages/(marketing)/index.vue", "meta": { "groups": ["marketing"] } }
    ]
  },
  {
    "path": "",
    "file": "pages/(admin).vue",
    "meta": { "groups": ["admin"] },
    "children": [
      { "name": "dashboard", "path": "dashboard", "file": "pages/(admin)/dashboard.vue", "meta": { "groups": ["admin"] } },
      { "name": "settings", "path": "settings", "file": "pages/(admin)/settings.vue", "meta": { "groups": ["admin"] } }
    ]
  }
]

2. Nested Groups Inside Directories

Files:

pages/
└── products/
    ├── (marketing).vue
    └── (marketing)/
        ├── campaign.vue
        └── deals.vue

Vue Router Output:

[
  {
    "path": "/products",
    "file": "pages/products/(marketing).vue",
    "meta": { "groups": ["marketing"] },
    "children": [
      { "name": "products-campaign", "path": "campaign", "file": "pages/products/(marketing)/campaign.vue", "meta": { "groups": ["marketing"] } },
      { "name": "products-deals", "path": "deals", "file": "pages/products/(marketing)/deals.vue", "meta": { "groups": ["marketing"] } }
    ]
  }
]

🧪 Tests & Quality Assurance

• Unit tests: Added unit tests in test/unit/converters.spec.ts covering root and nested group parent layouts, incremental updates, and mixed nesting permutations.
• Nuxt compatibility tests: Added tests in test/unit/nuxt-compat.spec.ts validating matching behavior.
• Test Coverage: 100% statement, branch, function, and line coverage across the entire repository.
• Linter & Typecheck: Passed (eslint . and tsc --noEmit).
• E2E Tested: Verified in Nuxt 4 playground.

Summary by CodeRabbit

• New Features

  • Added support for group-based parent layouts in Vue Router route generation.
  • Grouped routes now nest correctly under matching parent layouts, including nested groups and index routes.
  • Improved route ordering and naming for grouped layouts.

• Bug Fixes

  • Corrected grouped parent paths and dynamic route updates when files are added or removed.
  • Improved compatibility with Nuxt grouped layouts.

• Documentation

  • Documented the new group layout pattern.