npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2026 – Pkg Stats / Ryan Hefner

@contentful/optimization-core

v1.3.0

Published

Platform-agnostic core SDK for Contentful Optimization

Vulnerabilities

Powered byPowered by Snyk
  • 0High
  • 0Medium
  • 0Low

Links

Git

Maintainers

it-internalit-internalwhydah-gallywhydah-gallycontentful-ecosystemcontentful-ecosystemmichaelpearcemichaelpearce

Keywords

Readme

Guides · Reference · Contributing

The Optimization Core SDK owns the platform-agnostic optimization state machine, event builders, queues, resolvers, and interceptors used by the application-facing SDKs. Web, React Web, Node, React Native, and native bridge layers build on this package.

We recommend starting application code with a platform SDK rather than Core directly. Use this README when building or maintaining SDK layers, and use Choosing the right SDK when deciding which application-facing package belongs in an integration. Generated reference documentation remains the source of truth for exported API signatures.

Getting started

Install using an NPM-compatible package manager, pnpm for example:

pnpm install @contentful/optimization-core

Choose the stateful or stateless Core class based on the runtime layer you are building:

import { CoreStateful, CoreStateless } from '@contentful/optimization-core'

const statefulOptimization = new CoreStateful({ clientId: 'your-client-id' })
const statelessOptimization = new CoreStateless({ clientId: 'your-client-id' })

Stateful runtimes own durable in-process SDK state. Stateless runtimes bind request-scoped consent, profile state, event context, and Experience API options before calling event methods:

const requestOptimization = statelessOptimization.forRequest({
  consent: true,
  locale: 'en-US',
  eventContext: { locale: 'en-US' },
  experienceOptions: { preflight: false },
  profile: { id: 'f0837d7dc6344c36a3a0a06c4cde754b' },
})

const { accepted, data } = await requestOptimization.page()

When to use this package

Use @contentful/optimization-core when you are building or maintaining an SDK layer that needs the shared optimization state machine, event builders, queueing, resolvers, or interceptors. Most application code uses a platform SDK such as Web, React Web, Node, or React Native instead of depending on Core directly.

Core variants

Stateful Core

CoreStateful is the basis for SDKs that run in stateful JavaScript runtimes such as browsers, mobile JavaScript containers, and native bridge runtimes. It maintains consent, profile, selected optimization, flag, event-stream, blocked-event, and preview-panel state as read-only observables.

[!IMPORTANT]

CoreStateful uses module-global state by design. Initialize exactly one stateful instance per JavaScript runtime and reuse it.

Stateless Core

CoreStateless is the basis for SDKs that run in stateless environments such as Node servers and server-side functions. It does not store consent or profile state between requests. Consumers call forRequest() to create a request-bound event client with the consent, profile, event context, and Experience options for that one incoming request.

Common configuration

Shared Core configuration:

| Option | Required? | Default | Description | | -------------- | --------- | --------------------- | ----------------------------------------------------------- | | clientId | Yes | N/A | Shared API key for Experience API and Insights API requests | | environment | No | 'main' | Contentful environment identifier | | api | No | See API options below | Experience API and Insights API endpoint options | | contentful | No | undefined | App-owned contentful.js client, default query, and cache | | eventBuilder | No | SDK-layer defaults | Event metadata overrides for platform SDK authors | | fetchOptions | No | SDK defaults | Fetch timeout and retry behavior | | logLevel | No | 'error' | Minimum log level for the default console sink |

Consent and event configuration:

| Option | Required? | Default | Description | | ------------------- | --------- | ----------- | ------------------------------------------------------------ | | allowedEventTypes | No | [] | Event types allowed before consent is explicitly set | | onEventBlocked | No | undefined | Callback invoked when consent or guard logic blocks an event |

Core itself fails closed before consent. Platform SDKs set runtime-specific defaults for the event types that make sense in that runtime, such as browser identify/page, server identify/page, and mobile identify/screen.

Stateful-only configuration:

| Option | Required? | Default | Description | | ---------------- | --------- | ------------ | --------------------------------------------------------------------------------- | | defaults | No | undefined | Initial state, commonly including consent, persistence consent, or profile values | | getAnonymousId | No | undefined | Function used to provide an anonymous ID from application-owned identity state | | queuePolicy | No | SDK defaults | Flush retry behavior and offline queue bounds |

Persistence consent controls durable profile-continuity storage for SDKs with runtime storage: profile, anonymous ID, changes, and selected optimization caches. Event consent, stored consent decisions, and debug state are tracked separately.

Common api options:

| Option | Applies to | Default | Description | | ------------------- | ---------- | ------------------------------------------ | ------------------------------------------------- | | experienceBaseUrl | All | 'https://experience.ninetailed.co/' | Base URL for the Experience API | | insightsBaseUrl | All | 'https://ingest.insights.ninetailed.co/' | Base URL for the Insights API | | enabledFeatures | All | ['ip-enrichment', 'location'] | Experience API features for each request | | ip | Stateful | undefined | IP address override for Experience API analysis | | plainText | Stateful | true for single-profile mutations | Sends single-profile Experience mutations as text | | preflight | Stateful | false | Aggregates a profile state without storing it |

When plainText is omitted, single-profile Experience mutation/event requests use text/plain. Pass plainText: false to send JSON. Experience batch profile updates still default to JSON.

In stateless environments, pass ip, locale, plainText, and preflight as experienceOptions when creating the request-bound client instead of constructor config. Pass request-specific Insights API options, such as a last-chance beacon sender, as insightsOptions.

Core-backed stateful SDKs can accept an initial top-level locale and runtime setLocale(locale) calls. They expose that SDK Experience API and default event locale through the live locale getter and states.locale observable. Stateless server SDKs should pass the request-scoped SDK locale as forRequest({ locale }); advanced callers can still pass experienceOptions.locale when no request locale is supplied.

Applications own Contentful CDA locale selection and pass that locale directly to their Contentful client. For the full locale model, see Locale handling in the Optimization SDK Suite.

Common fetchOptions are fetchMethod, requestTimeout, retries, intervalTimeout, onFailedAttempt, and onRequestTimeout. Default retries intentionally apply only to HTTP 503 responses.

For every option, callback payload, and exported type, use the generated Core SDK reference.

Campaign attribution

Event builders use explicit campaign data when supplied. Otherwise, they infer context.campaign from utm_campaign, utm_source, utm_medium, utm_term, and utm_content parameters in page.url. They do not inspect page.referrer.

For a page event, properties.url supplies the inferred campaign when it contains at least one supported UTM parameter. Otherwise, the builder uses the resolved context.page.url. That resolved URL comes from an explicit page.url, or from getPageProperties() when event input does not override it. If neither eligible URL parses with a supported UTM parameter, the inferred campaign is empty.

Package surface

Core exposes reusable primitives for SDK layers:

| Surface | Purpose | | ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- | | CoreStateful | Stateful optimization runtime for browser, mobile, and bridge SDKs | | CoreStateless | Stateless optimization runtime for server SDKs | | Event methods | identify, page, screen, track, trackView, trackClick, etc. | | Resolution and fetch helpers | resolveOptimizedEntry, fetchContentfulEntry, fetchContentfulEntries, fetchOptimizedEntry, prefetchManagedEntries, getMergeTagValue, and getFlag | | Selection handoff helpers | Framework-neutral selection state, cache keys, cache-safety warnings, bulk entry resolution, and createHandoffFromSelections | | Current-state tracking | AcceptedCurrentStateTracker for SDK-owned page or screen adapters | | states | Stateful observable state streams | | Interceptors | First-party hooks for event and state lifecycle customization | | Queue policy and fetch helpers | Shared retry, flush, timeout, and offline buffering behavior | | Signal and observable utilities | Lightweight reactive primitives used internally by stateful SDK layers |

When a contentful.js client is available, prefer SDK-managed fetching. Configure contentful: { client, defaultQuery?, cache? }, then identify each entry by ID or by content type and slug:

await sdk.fetchOptimizedEntry({
  contentType: 'page',
  slug: 'home',
  slugField: 'slug',
  entryQuery: { locale: 'en-US' },
})

slugField defaults to slug. Managed calls merge defaultQuery, entryQuery, an SDK or request locale fallback, and include: 10. Slug lookup then enforces content_type, fields.<slugField>, and limit: 2, so those selectors override conflicting query values. It throws these errors when the result isn't unique:

Contentful entry not found for content type "<contentType>" where "fields.<slugField>" equals "<slug>".
Multiple Contentful entries found for content type "<contentType>" where "fields.<slugField>" equals "<slug>".

ID lookups retain batching for same-query uncached entries and split large batches into 100-ID chunks. Results preserve descriptor order and duplicates. Managed fetching caches entries per SDK instance by default; set contentful.cache: false to disable the cache or call clearContentfulEntryCache() to clear it. Slug prefetch handoffs nest the normalized descriptor under managedEntry and retain the fetched entry's sys.id in entryId. resolveOptimizedEntry() remains the manual path for entries the app already fetched. Stateful Core uses current selections when omitted, request-bound stateless clients use the latest accepted selections and request locale fallback, and root stateless callers pass explicit selections.

Resolver types accept one skeleton or a union of every possible baseline and variant skeleton. See Entry optimization and variant resolution for heterogeneous entry typing and narrowing.

Framework SDKs use Core selection handoff helpers when server, static, or edge rendering already knows the selected optimizations. createHandoffFromSelections() records that explicit selection state and cache metadata without choosing browser hydration behavior. Cacheable public permutations can use createPublicPermutationCacheMetadata() for a deterministic key and optional caller-owned invalidation tags. resolveEntriesForSelections() resolves a batch of baseline entries in input order for server-rendered markup, and createSelectionFingerprint(), createOptimizationCacheKey(), getOptimizationCacheSafetyWarnings(), and assertOptimizationCacheSafety() support customer-owned cache keys and diagnostics.

Do not pass all-locale CDA responses from withAllLocales or locale=*; optimization fields such as fields.nt_experiences and fields.nt_variants must be direct single-locale field values. See Entry optimization and variant resolution for the entry contract and Locale handling in the Optimization SDK Suite for the broader locale model.

Custom entry-source adapters

@contentful/optimization-core/entry-source is an advanced subpath for custom JavaScript runtime or framework adapters that cannot use an official Web, React Web, React Native, Node, or native SDK surface. It is not part of the root Core API posture and is not the preferred path for application integrations.

Import OptimizedEntrySourceController when an adapter accepts a direct baselineEntry, a managed entry ID, or a managed content-type/slug source. The controller owns source lifecycle and query keying, SDK readiness/loading/error snapshots, stale request protection, and disconnect() cleanup. After a slug fetch, snapshots and downstream tracking use the fetched entry's sys.id. createOptimizedEntryLoadingEntry(entryId) creates a stable placeholder Contentful entry for ID loading states.

The entry-source controller does not own rendering, variant resolution, tracking, consent, Experience API calls, or Contentful client creation. After a snapshot contains baselineEntry, the adapter still calls resolveOptimizedEntry(), renders the result, and wires any runtime-specific tracking.

The generated reference owns method arguments, return types, callback payload shapes, and inherited members. Keep this README focused on package role and maintainer orientation.

Preview support

Preview-panel helpers live under the internal preview-support entry. They are used by first-party preview surfaces to register preview state bridges, apply optimization overrides, and map Contentful entries for local authoring workflows.

Application code must not use preview support directly unless it is building a first-party preview surface.

Related