`globalContext`

Environment: client, server

Provided by: vike

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 configurations of all pages.

Most configurations of a page aren't eagerly loaded: they're only loaded when rendering that page and, consequently, aren't available to other pages. Only a few configurations are eagerly loaded — the notable ones being the page's route and the page's prefetch setting.

Some page configurations aren't available at runtime; they are only available at config-time.

See also: globalContext.config

`globalContext.config`

Environment: server, client

The app's global runtime configuration (such as the base URL setting).

Most global configurations aren't available at runtime; they are only available at config-time.

See also:

pageContext.config

globalContext.pages

getVikeConfig()

`globalContext.prerenderContext`

Environment: config (build-time)

If you use pre-rendering, you can access:

globalContext.prerenderContext.pageContexts — the list of all pre-rendered URLs.
globalContext.prerenderContext.output — the list of all written files.

`globalContext.isClientSide`

Environment: server, client

Same as pageContext.isClientSide.

It can also be used to narrow down the GlobalContext type to either GlobalContextClient or GlobalContextServer, see Narrowing down.

`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 shuts down. For example, if your server process runs for 5 days, then the globalContext object lives for 5 days.

If your JavaScript server runs as a single process, then you have only one globalContext object for your entire server-side.

On edge environments, there are typically multiple server processes/workers, so you get multiple server-side globalContext objects — one per process/worker.

In development, the globalContext object is re-initialized if you make a file change that triggers a full page reload (i.e. a change that isn't covered by HMR).

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, then there is one globalContext per tab.

For example, if 3 users are simultaneously visiting your website — two users with 1 tab and one user with 3 tabs — then there are 5 (1 + 1 + 3 = 5) client-side globalContext objects.

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.