Implementation Details

Imports

@query-api/next uses react-server conditional exports to load code that is optimized for use in Server or Client Components.

For example, hooks like useCraftUri() rely on useContext when used in Client Components. On the server, however, values like the current URI or site are resolved directly via headers().

Usage in Server Components:

import { getCraftUri, getCraftCurrentSite, getCraftEntry } from '@query-api/next/server'

Usage in Client Components:

'use-client'

import { useCraftUri, useCraftCurrentSite, useCraftEntry } from '@query-api/next'

Components

All of the components are context independent, meaning you can use them in client and in server components.

Provider

The CraftClientProvider is also context-agnostic. This is achieved through two CraftClientProvider components that work together through composition, bridging the gap between the Next.js server and client environments.

Server-Side Provider (@query-api/next/server)

• This is an async React Server Component. Its primary function is to resolve request-specific data that is only available on the server.
• It reads the incoming request headers (set by the createQueryApiMiddleware) to determine the full URL and path of the user's request. This server-side context is essential for site and preview resolution.
• After resolving the location data from the headers, it renders the client-side CraftClientProvider, passing the resolved location and the shared config object down as props.

Client-Side Provider (@query-api/next)

• This is a standard React Client Component, marked with 'use client'.
• Its sole responsibility is to take the config and location props it receives from the server provider and inject them into a React Context using the underlying CraftProvider from @query-api/react.
• This makes the configuration and location context available to any descendant client component.

Execution Flow:

1. On a page request, the Server Provider executes first.
2. It awaits the request headers to get the URL.
3. It then returns the Client Provider in its render output, passing the URL data as props.
4. The Client Provider receives these props and establishes the React Context for the rest of the application, including all client-side hooks (useCraftQuery, etc.).

This pattern allows you to initialize the provider with server-known information (the URL) while making that information accessible to client-side components through a standard React Context.