@keystone-sites/core

Backend middleware for Keystone customer websites — no UI. Supplies the typed server-side API client, consumer session helpers, server actions, CTA URL resolution, and Next.js API route handler factories used by every customer site (legacy or generated).

Package exports

| Import path | Contents | |---|---| | @keystone-sites/core | Server actions (submitContactFormAction, submitLeadFormAction), resolveCtaUrls, resolvePortalPath, isExternalCtaUrl | | @keystone-sites/core/lib/server-api | All server-side data fetching functions (getCompanyInformation, getServices, getAdsConfig, getAnalyticsConfig, …) | | @keystone-sites/core/lib/server-log | Structured server-side logging (serverLog, serverWarn, serverError) | | @keystone-sites/core/lib/cta-urls | resolveCtaUrls, resolvePortalPath, isExternalCtaUrl | | @keystone-sites/core/lib/consumer-session | Consumer auth cookie constant + API helpers (fetchConsumerMe, fetchConsumerConversations, fetchConsumerMessages) | | @keystone-sites/core/lib/actions | Server actions for form submissions | | @keystone-sites/core/next/routes/form | createFormRouteHandlers | | @keystone-sites/core/next/routes/chat | createChatRouteHandlers | | @keystone-sites/core/next/routes/consumer-auth | createConsumerAuthHandlers | | @keystone-sites/core/next/routes/proxy-headers | clientContextHeaders | | @keystone-sites/core/types | Shared TypeScript types for Keystone API responses |

Source directory structure

src/
├── lib/
│   ├── server-api.ts       # Server-side API fetch helpers
│   ├── server-log.ts       # Structured server-side logging
│   ├── consumer-session.ts # Consumer auth cookie + API helpers
│   ├── actions.ts          # Server actions for form submissions
│   └── cta-urls.ts         # CTA URL resolution utilities
├── next/
│   └── routes/             # API route handler factories (form, chat, consumer-auth, proxy-headers)
└── types/
    └── api/                # Keystone API response types

Environment variables

Both this package and customer sites use two server-side environment variables:

| Variable | Required | Default | Description | |---|---|---|---| | API_URL | Yes | http://localhost:3000/api/v1 | Base URL for the Keystone API | | API_KEY | Yes | "" | Service account API key for this site |

These are read at SSR time only and never exposed to the browser. Set them in .env.local for local development.

Publishing workflow

Publish to the public npm registry in dependency order (wait for each package to propagate before publishing dependents):

# 1. @keystone-sites/core (no internal Keystone deps)
npm run test && npm publish --access public

# 2. @keystone-sites/services (depends on @keystone-sites/core)
npm run test && npm publish --access public

# 3. @keystone-sites/widgets (depends on @keystone-sites/core + @keystone-sites/services)
npm run test && npm publish --access public

prepublishOnly runs npm run build automatically before each publish.

For local development against an unpublished build, use yalc:

# In @keystone-sites/core — build and publish to local yalc store
npm run build && yalc publish

# In the customer site — link to the local build
yalc add @keystone-sites/core
# or update an existing link
yalc update @keystone-sites/core

To restore the published npm version:

yalc remove @keystone-sites/core
npm install

Docs

• docs/server-api.md — server API client reference