feat: new namespace Vike to enable users to refine type Config

Author: brillout

vite-plugin-ssr/TODO

@@ -1,11 +1,12 @@
+- Add Vike.PageContext
+  - improve TypeScript DX for `abortReason`
+  - improve TypeScript DX for `usePageContext()`
 - fix pageContext._renderHook.hookFilePath / replace with new prop hookSrc
 - refacor/fix skipConfigValue to differentiate between global/page virtual file
 - use json-s instead of JSON
 
 - By default, only call guard() hooks on the server-side?
 
-- improve TypeScript DX for abortReason
-- improve TypeScript DX for usePageContext
 - release 0.5.0
   - `import * from 'vite-plugin-ssr'`
   - pageContext.url
@@ -55,3 +56,4 @@ Contact:
  - Cloudflare Workers
  - UI frameworks like qwik (maybe even Angular)
    - See `pnpm create vite@latest` for a list of UI frameworks
+

vite-plugin-ssr/node/runtime/renderPage/preparePageContextForUserConsumptionServerSide.ts

@@ -30,7 +30,7 @@ type PageContextForUserConsumptionServerSide = PageContextBuiltInServerInternal
   is404: null | boolean
   isClientSideNavigation: boolean
   pageProps?: Record<string, unknown>
-}
+} & Record<string, unknown>
 function preparePageContextForUserConsumptionServerSide(pageContext: PageContextForUserConsumptionServerSide): void {
   assertPageContextUrlComputedProps(pageContext)
 

vite-plugin-ssr/shared/VikeNamespace.ts

@@ -0,0 +1,39 @@
+export type { Vike }
+export type { VikePackages }
+
+// Enable users and vike-* packages to define types, e.g.:
+//  - User can set Config['Page'] over Vike.Config['Page']
+//  - vike-vercel can add Config['isr'] over Vike.Config['isr']
+
+declare global {
+  /** Refine Vike types. */
+  namespace Vike {
+    /** Define/refine the type `Config`.
+     *
+     *  For example:
+     *  - You can refine the type of `Config['Page']`.
+     *  - You can define a newly created configuration to `Config`, when creating new configurations using `config.meta` https://vite-plugin-ssr.com/meta
+     *
+     */
+    interface Config {}
+  }
+
+  /** This namespace is only used by:
+   *  - `vike-react`
+   *  - `vike-vue`
+   *  - `vike-solid`
+   *  - `vike-svelte`
+   *
+   *  As a Vike user, you can ignore this.
+   */
+  namespace VikePackages {
+    // Enable vike-{react/vue/solid/svelte} to extend the type `Config`.
+    //  - We need a different interface for each vike-{react/vue/solid/svelte} package because of conflicts.
+    //    - E.g. Config['Page'] is a React/Vue/Solid/Svelte componenent depending on which vike-{react/vue/solid/svelte} package is being used.
+    //      - The user can be using more than one vike-{react/vue/solid/svelte} package.
+    interface ConfigVikeReact {} // For vike-react
+    interface ConfigVikeVue {} // For vike-vue
+    interface ConfigVikeSolid {} // For vike-solid
+    interface ConfigVikeSvelte {} // For vike-svelte (the vike-svelte package doesn't exist yet)
+  }
+}

vite-plugin-ssr/shared/page-configs/Config.ts

@@ -3,15 +3,11 @@ export type { ConfigBuiltIn }
 export type { ConfigNameBuiltIn }
 export type { ConfigMeta }
 export type { HookName }
-export type { ConfigInterface }
-export type { ConfigVikeReact }
-export type { ConfigVikeVue }
-export type { ConfigVikeSolid }
-export type { ConfigVikeSvelte }
 
 import type { PrefetchStaticAssets } from '../../client/client-routing-runtime/prefetch/getPrefetchSettings.js'
 import type { ConfigDefinition } from '../../node/plugin/plugins/importUserCode/v1-design/getVikeConfig/configDefinitionsBuiltIn.js'
 import type { ConfigVpsUserProvided } from '../ConfigVps.js'
+import type { Vike, VikePackages } from '../VikeNamespace.js'
 
 type HookName =
   | 'onHydrationEnd'
@@ -34,7 +30,14 @@ type ConfigNameBuiltInPublic =
 type ConfigNameBuiltInInternal = 'isClientSideRenderable' | 'onBeforeRenderEnv'
 type ConfigNameBuiltIn = ConfigNameBuiltInPublic | ConfigNameBuiltInInternal
 
-type Config = ConfigBuiltIn & ConfigInterface & (ConfigVikeReact | ConfigVikeVue | ConfigVikeSolid | ConfigVikeSvelte)
+type Config = ConfigBuiltIn &
+  Vike.Config &
+  (
+    | VikePackages.ConfigVikeReact
+    | VikePackages.ConfigVikeVue
+    | VikePackages.ConfigVikeSolid
+    | VikePackages.ConfigVikeSvelte
+  )
 
 // TODO: write docs of links below
 
@@ -168,16 +171,3 @@ type ConfigBuiltIn = {
 }
 type ConfigMeta = Record<string, ConfigDefinition>
 type ImportString = `import:${string}`
-
-// Enable users and vike-* packages to extend the type Config, for example:
-//  - The user can set Config['Page'] over ConfigInterface['Page']
-//  - vike-vercel can add Config['isr'] over ConfigInterface['isr']
-interface ConfigInterface {}
-
-// Enable vike-{react/vue/solid/svelte} to extend the type Config.
-//  - We need a different interface for each vike-{react/vue/solid/svelte} package because of conflicts.
-//    - E.g. the config 'Page' can be a React/Vue/Solid/Svelte componenent depending on which vike-{react/vue/solid/svelte} packages the user installed.
-interface ConfigVikeReact {} // For vike-react
-interface ConfigVikeVue {} // For vike-vue
-interface ConfigVikeSolid {} // For vike-solid
-interface ConfigVikeSvelte {} // For vike-svelte (the vike-svelte package doesn't exist yet)

vite-plugin-ssr/shared/page-configs/Config/PageContextConfig.ts

@@ -1,23 +1,27 @@
 export type { PageContextConfig }
 
-import type { ConfigBuiltIn, ConfigVikeReact, ConfigVikeSolid, ConfigVikeSvelte, ConfigVikeVue } from '../Config.js'
+import type { VikePackages } from '../../VikeNamespace.js'
+import type { ConfigBuiltIn } from '../Config.js'
 import type { Combine, IsNotEmpty, XOR4 } from './helpers.ts'
 
 // Like the type `Config` but meant for pageContext.config
 type PageContextConfig = ConfigBuiltIn &
   (ConfigVikePackagesNotEmptyXor extends true ? ConfigVikePackagesIntersection : ConfigVikePackagesCombined)
 
 // Preserves JSDocs, such as the the JSDoc pageContext.config.title defined by vike-react
-type ConfigVikePackagesIntersection = ConfigVikeReact & ConfigVikeVue & ConfigVikeSolid & ConfigVikeSvelte
+type ConfigVikePackagesIntersection = VikePackages.ConfigVikeReact &
+  VikePackages.ConfigVikeVue &
+  VikePackages.ConfigVikeSolid &
+  VikePackages.ConfigVikeSvelte
 // Loses JSDocs, such as the the JSDoc pageContext.config.title defined by vike-react
 type ConfigVikePackagesCombined = Combine<
-  ConfigVikeReact,
-  Combine<ConfigVikeVue, Combine<ConfigVikeSolid, ConfigVikeSvelte>>
+  VikePackages.ConfigVikeReact,
+  Combine<VikePackages.ConfigVikeVue, Combine<VikePackages.ConfigVikeSolid, VikePackages.ConfigVikeSvelte>>
 >
 
 type ConfigVikePackagesNotEmptyXor = XOR4<
-  IsNotEmpty<ConfigVikeReact>,
-  IsNotEmpty<ConfigVikeVue>,
-  IsNotEmpty<ConfigVikeSolid>,
-  IsNotEmpty<ConfigVikeSvelte>
+  IsNotEmpty<VikePackages.ConfigVikeReact>,
+  IsNotEmpty<VikePackages.ConfigVikeVue>,
+  IsNotEmpty<VikePackages.ConfigVikeSolid>,
+  IsNotEmpty<VikePackages.ConfigVikeSvelte>
 >

vite-plugin-ssr/types/index.ts

@@ -5,11 +5,6 @@ export type { InjectFilterEntry } from '../node/runtime/html/injectAssets/getHtm
 export type {
   Config,
   ConfigMeta as Meta,
-  ConfigInterface,
-  ConfigVikeReact,
-  ConfigVikeVue,
-  ConfigVikeSolid,
-  ConfigVikeSvelte
 } from '../shared/page-configs/Config.js'
 export type { ConfigEnv } from '../shared/page-configs/PageConfig.js'
 export type {