`globalContext`

The globalContext object is used for storing global information (i.e. information shared by multiple pages).

It has built-in properties set by Vike, and you can define custom properties.

For example, you can use globalContext to save the list of URLs for a navigation menu.

Each environment has a single, unique globalContext object created when it starts — see Lifecycle. An environment can be either a server-side process (Node.js, Bun, Deno, or a worker) or a browser session.

If you store information (e.g. globalContext.someData = 42) then it's available anywhere in your app until the process is terminated. You can access globalContext anywhere by using getGlobalContext() and pageContext.globalContext. You can define globalContext properties on the server-side while using +passToClient for accessing them on the client-side.

Built-in

While globalContext has some built-in properties, it's mostly used to store custom properties.

The globalContext object also contains many internals (they are prefixed with _, e.g. globalContext._viteDevServer). You should use them only if strictly needed and, if you do, then let us know so that we can add official support for your use case (otherwise you'll expose yourself to breaking changes upon any version update).

`globalContext.pages`

Environment: server, client

Eagerly loaded runtime information about all your pages' configuration (e.g., all page routes).

`globalContext.config`

Environment: server, client

Runtime information about your app's global configuration.

`globalContext.isClientSide`

Environment: server, client

Same as pageContext.isClientSide.

`globalContext.isGlobalContext`

Environment: server, client

Like pageContext.isPageContext.

`globalContext.assetsManifest`

Environment: server

The assets manifest.

`globalContext.viteConfig`

Environment: server

The entire Vite's config, only available at development and during pre-rendering.

`globalContext.viteConfigRuntime`

Environment: server

A tiny subset of Vite's config that is also available in production.

`globalContext.baseAssets`

Environment: server

The assets Base URL.

`globalContext.baseServer`

Environment: server

The server Base URL.

Custom

You can define custom globalContext properties.

globalContext.myCustomProp = someValue // Add or modify

Custom properties are typically initialized using one or several onCreateGlobalContext() hooks.

You can also create and modify globalContext properties at any time and anywhere in your app — for example, in your UI components, using pageContext.globalContext.

See the section TypeScript > Extend for how to define the type of globalContext.myCustomProp.

Lifecycle

See also:

API > pageContext > Lifecycle

API > Hooks > Lifecycle

The lifecycle of the globalContext object is completely different between the client- and server-side.

Server-side

The globalContext is created when the server starts and lives until the server process is shut down.

If your JavaScript server runs in a single process, then you have a single globalContext object for your entire server-side. If that server process stays alive for many days at a time, then the globalContext object does too.

On edge environments, where there can be multiple server processes/workers, you can have multiple server-side globalContext object — one per process/worker.

Client-side

When a user starts visiting your website, a new globalContext object is created that lives until the user closes your website. If the user opens your website in multiple tabs, there is one globalContext per tab.

Given multiple users visiting your website, there can be a lot of client-side globalContext objects, which are, by their very nature, ephemeral.

Pre-rendering

Upon pre-rendering, there is exactly one globalContext object that lives from the beginning until the end of the pre-rendering process.

TypeScript

Basics

import type {
  // For code loaded in client and server
  GlobalContext,
  // For code loaded in client only
  GlobalContextClient,
  // For code loaded in server only
  GlobalContextServer
} from 'vike/types'

Narrowing down

You can use globalContext.isClientSide and globalContext.isGlobalContext to narrow down TypeScript unions, see API > pageContext > Narrowing down.

Extend

To extend GlobalContext/GlobalContextServer/GlobalContextClient, use the global interface Vike.GlobalContext:

declare global {
  namespace Vike {
    interface GlobalContext {
      // Type of globalContext.user
      user?: {
        name: string
        id: string
        isAdmin: boolean
      }
    }
  }
}
 
// If you define Vike.GlobalContext in a .d.ts file then
// make sure there is at least one export/import statement.
// Tell TypeScript this file isn't an ambient module:
export {}

To define properties only for the server-/client-side, use the interfaces Vike.GlobalContextServer and Vike.GlobalContextClient instead.