Installation

Install only what your application needs#

Contoprix packages are deliberately split by job. Start with the framework-independent client, then add a framework package only when it helps your application.

@contoprix/react and @contoprix/next bring the core client and shared types through their dependencies. Installing @contoprix/client directly is still useful when your own code constructs and uses the client.

Before you install#

You need:

• a JavaScript or TypeScript application;
• the base URL of a running Contoprix CMS API;
• a delivery key for the website you want to render;
• Node.js 22 or newer if you will use the Contoprix CLI.

For the current React/Next integration packages, use a compatible React 19 and Next.js 16 application. If your project uses another framework, the core client works without React or Next.js.

Option A: data delivery only#

Use this for a Node.js service, a custom frontend, or a React app where you will render the data yourself.

npm install @contoprix/client

If you want to import shared types in application code, add them explicitly:

npm install @contoprix/types

Option B: React page and block rendering#

Add React support when your frontend receives Contoprix page blocks and you want the SDK renderer to resolve a component registry.

npm install @contoprix/client @contoprix/react @contoprix/types

You still write the visual components. The SDK supplies the renderer and the contract that passes a block's settings, content, or contents into your registered component.

Option C: Next.js#

For a Next.js application, install the core, React, and Next.js packages together:

npm install @contoprix/client @contoprix/react @contoprix/next @contoprix/types

@contoprix/next/server is designed for server-side code. It reads the server environment variables described in Configure the SDK, then creates a client for delivery or preview requests.

Optional: install the CLI#

The CLI is not required to fetch published content. Add it when your team wants the content model in source control, TypeScript interfaces generated from the model, or component stubs for new component types.

npm install --save-dev @contoprix/cli
npx contoprix --help

The safe first workflow is:

npx contoprix init
npx contoprix login
npx contoprix pull
npx contoprix generate
npx contoprix validate

login uses SDK client credentials with schema permissions; a delivery key is for reading published content and is not a replacement for CLI credentials. Run npx contoprix components only when you want to scaffold component files after reviewing the pulled schema.

Verify the package installation#

Create a server-side module. Do not use real credentials in this source file; configuration belongs in environment variables.

import { ContoprixClient } from "@contoprix/client";

export const client = new ContoprixClient({
  baseUrl: process.env.CONTOPRIX_BASE_URL!,
  auth: {
    type: "deliveryKey",
    deliveryKey: process.env.CONTOPRIX_DELIVERY_KEY!,
  },
  languageCode: "en",
});

If TypeScript recognizes the import, installation is complete. The request will work after you set valid environment values and publish content for the same website as the delivery key.

Common installation mistakes#

Next step#

Continue with Create your first project. It creates a small Article model, a published entry, and a real SDK request you can verify end to end.