@keystone-sites/services

v1.0.0

Published

a day ago

Keystone Sites Services - analytics/ads providers (Meta Pixel, PostHog, GTM) and the KeystoneServices injection shell for customer websites

0High
0Medium
0Low

keystonepzjr

gauravgrover-keystone

amanjs-ks

sreenivasanac-keystone

@keystone-sites/services

Analytics/ads providers and the injection shell for Keystone customer websites. Supplies Meta Pixel (browser + CAPI coordination), PostHog (events, pageviews, client log shipping via OTel), Google Tag Manager, and the KeystoneServices server component that wires them all up from server-fetched config.

KeystoneServices

KeystoneServices is a slim async server component that replaces the tracking role of the legacy KeystoneRootLayout. It fetches getAdsConfig(), getAnalyticsConfig(), and getCompanyInformation() itself (via @keystone-sites/core) and renders Meta Pixel, PostHog + Keystone analytics tracking, and the GTM script around {children}.

// app/layout.tsx
import { KeystoneServices } from '@keystone-sites/services';

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="en">
      <body>
        <KeystoneServices>{children}</KeystoneServices>
      </body>
    </html>
  );
}

Every service is a silent no-op when its config is not provisioned. Any future site-wide service (a new pixel, consent management, etc.) is added here once and every site picks it up on version bump.

Package exports

| Import path | Contents | |---|---| | @keystone-sites/services | KeystoneServices + everything from ./tracking | | @keystone-sites/services/tracking | MetaPixel, MetaPixelTracker, firePixelEvent, setPixelUserData, PostHogProvider, KeystoneAnalyticsTracker, GoogleTagManager, captureEvent, captureCustomEvent, log/warn/error client logging | | @keystone-sites/services/services/KeystoneServices | The injection shell on its own |

Source directory structure

src/
├── services/
│   └── KeystoneServices.tsx  # Injection shell (async server component)
└── tracking/                 # Meta Pixel, PostHog, GTM components and helpers
    ├── MetaPixel.tsx / MetaPixelTracker.tsx / firePixelEvent.ts
    ├── PostHogProvider.tsx / KeystoneAnalyticsTracker.tsx / captureEvent.ts
    ├── GoogleTagManager.tsx
    └── logging.ts            # Structured client logging (OTel → PostHog Logs)

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/services — 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/services
# or update an existing link
yalc update @keystone-sites/services

To restore the published npm version:

yalc remove @keystone-sites/services
npm install

Docs

docs/meta-tracking.md — Meta Pixel + CAPI tracking contract
docs/posthog-tracking.md — PostHog events and taxonomy

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

@keystone-sites/services

KeystoneServices

Package exports

Source directory structure

Publishing workflow

Docs