feat: +pages for programmatically defining pages (closes #1691)

[brillout]

What

Implements the config-time half of #1691: define pages from code, without a +Page/+config file on the filesystem.

// pages/+config.js
import ProductPage from './ProductPage'
import LoginPage from './LoginPage'

export default {
  pages: [
    { route: '/product/@id', Page: ProductPage },
    { route: '/login',        Page: LoginPage },
  ],
}

This unblocks the "Single Route File" request (#341), is the foundation for extension-defined pages (e.g. vike-authjs/vike-better-auth), and is the registration primitive needed for the page-variant use cases in #1525 (OG images, .md for LLMs).

Note

Per discussion, this is only the list form. The function/transformer form (pages: (pages) => [...]) is intentionally left for a follow-up. Runtime/post-build programmatic pages are also out of scope.

How

Each pages entry is turned, at config-time, into a synthetic +config.js at a namespaced locationId — {definingLocationId}/(programmatic)/{slug} — so it flows through the existing config-resolution pipeline unchanged, with no duplicated logic:

• The entry { route, Page, … } is structurally a +config.js default export, so it reuses getPlusFileFromConfigFile(). This means Page is a top-level pointer import and gets resolved + serialized into a real runtime import for free.
• Nesting under the defining location makes the page inherit the surrounding config (renderer via extends, title, etc.).
• The (programmatic) marker is a parenthesis route-group (already a first-class Vike concept): it's stripped from the Filesystem-Routing fallback and guarantees a synthetic page can never collide with — nor become the inheritance parent of — a real page.
• slug is derived from id (optional) or the route string; duplicates are asserted with a clear message.

Touchpoints:

• types/Config.ts — pages?: ConfigPageEntry[] + exported ConfigPageEntry type; registered as a built-in global config name.
• metaBuiltIn.ts — pages: { env: { config: true }, global: true, cumulative: true } (config-time only; never shipped to runtime; definable globally or by extensions).
• getPlusFilesByLocationId.ts / addProgrammaticPages.ts — addProgrammaticPages() runs right after the filesystem crawl.

Verification

• tsc --noEmit clean for packages/vike and first-party playground files.
• Unit suite green: 180/180 (vitest --project unit).
• Added a programmatic page to test/playground (+ e2e test wired into testRun.ts) and verified end-to-end, browser-free:
  • Build/prerender: emits dist/.../programmatic.html with the rendered Programmatic Page heading, inherits the page title (title: 'Big Playground'), and the Page component is shipped in a client chunk (hydrates via the client-routing entry). pageId === /pages/(programmatic)/programmatic.
  • Dev: GET /programmatic → 200 with rendered + inherited content.

Follow-ups (not in this PR)

• Function/transformer form pages: (pages) => [...] (the New hook onRenderContent(): generate non-HTML files with arbitrary content #1525 variant story).
• Docs page https://vike.dev/pages.

Closes part of #1691.

🤖 Generated with Claude Code

https://claude.ai/code/session_01FMtgpc4sFVWUa7PPo1U92z

[suleimansh]

Small thing, the description says it exports PageConfigEntry, but the code
exports ConfigPageEntry. Worth aligning the two (and the upcoming docs) on one name.

[brillout]

Good catch — aligned the PR description with the code. The exported type is ConfigPageEntry (the rename from PageConfigEntry landed in a later commit); that's the canonical name to use for the upcoming docs too. Thanks!

---

Generated by Claude Code

[brillout]

config.pages — known limitations (first iteration)

For reviewers/users, the current scope and intentional limitations of programmatically defined pages:

1. Config-time only. config.pages is resolved at config-time. The function/transformer form (pages: (pages) => [...]) and runtime/CMS-driven (post-build) pages are out of scope for now.
2. Route Strings only. A page entry's route must be a string. Route Functions are rejected with an assertion for now (ConfigPageEntry.route is typed string).
3. pages is a global config. Define it at a global location (e.g. /pages/+config.js or /+config.js, or via an extension). Defining it at a non-global/scoped location still works but emits the usual "global config at a non-global location" warning.
4. Identity is positional. A page's pageId is …/(programmatic)/<index> (the entry's index, scoped per defining location). Reordering/inserting/removing entries changes the pageIds of later entries — and thus globalContext.pages keys and client chunk filenames. URLs and pre-rendered output are unaffected (they're route-based). There is intentionally no per-entry id.
5. No ImportStringList for pages or route. pages must be an inline array (or a +pages.js value file); route must be an inline string.
6. Config-time values via pointer import inside an entry (e.g. an imported value for a env: { config: true } config) aren't loaded at config-time, so config-time readers see them as absent. Inline config-time values and all runtime imports (Page, data, hooks, …) work normally. (The main case — route functions — is already covered by Inject CSS of server-side only imports #2.)
7. +config.js Page resolution rules are unchanged. A Page (or other component) referenced by an entry must be a pointer import — i.e. a .jsx/.tsx/.vue file (or any non-plain-script). A plain .ts/.js component isn't a pointer import (same as filesystem pages).
8. getVikeConfig().config.pages (build-time) reflects the raw entries (including internal import strings for Page); use getVikeConfig().pages (the resolved page map) for the resolved pages.

Everything else (config inheritance, meta.effect, computed values, precedence, routing, pre-rendering, client-side hydration, both config.pages and +pages.js forms, and extension-defined pages) goes through the same pipeline as filesystem pages.

---

Generated by Claude Code