Getting Started

What this guide helps you do

This guide is for frontend developers using the Contoprix SDK. It does not ask consumers to integrate directly with raw backend APIs.

By the end, you should be able to:

• understand the role of each Contoprix SDK package
• choose the right package for your frontend
• install the client and supporting SDK packages
• configure base URL, auth, and tenant-aware request setup
• fetch content in a clean way through the SDK
• use SDK-driven content to build your first page

The goal of this guide is simple: use the SDK as the main integration surface for frontend work.

SDK package map

The public Contoprix SDK is split by responsibility:

For most frontend teams, the important boundary is this:

• content teams manage schemas, entries, workflow, and publishing in the CMS
• frontend teams consume published data through the SDK packages

Pick the right package

For most frontend projects, start with:

npm install @contoprix/client @contoprix/types

If you are building a React app or Next.js website, you may also add:

npm install @contoprix/react @contoprix/next

Use @contoprix/cli when you need local tooling support as the SDK ecosystem grows.

Configure the client

Set up SDK configuration in one place so the rest of the app can reuse the same environment values and authentication behavior.

Typical concerns to centralize:

• base API URL
• delivery or management scope
• auth token or refresh flow
• tenant context
• website context when required

A good pattern is to create a small local module that exposes the initialized client:

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

export const contoprixClient = new ContoprixClient({
  baseUrl: process.env.NEXT_PUBLIC_CONTOPRIX_URL!,
});

If your app needs server-specific or browser-specific behavior, keep that split inside your wrapper rather than scattering it across pages.

Fetch content through the SDK

The SDK should be your first choice for:

• listing content
• reading content details
• resolving website-aware content
• reusing typed responses
• keeping frontend code insulated from raw endpoint churn

The main idea is to treat the SDK as your stable frontend contract. That gives you a cleaner upgrade path if backend shapes evolve.

When you write frontend code:

1. call the SDK from a page loader, server action, route handler, or server component where appropriate
2. normalize the returned data if your UI needs a simpler shape
3. keep UI components focused on rendering, not request details
4. use @contoprix/types when you want consistent typing across data mappers and UI models

Create pages with SDK content

Once the SDK is configured, the usual next step is to build a page that reads published content and renders it into your website UI.

A simple implementation flow looks like this:

1. choose one page or section to make content-driven
2. fetch the required content through @contoprix/client
3. map the response into a small view model
4. render the view model in reusable components
5. add empty-state and error-state handling

Keep the first page narrow. One route and one content read is enough to validate:

• auth is working
• tenant and website context are correct
• the SDK package version matches the expected backend behavior
• your UI can safely handle missing or partial content

Recommended project structure for SDK usage

A clean frontend setup usually looks like this:

src/
  lib/
    contoprix/
      client.ts
      auth.ts
      mappers.ts
      types.ts
  app/
  components/

Suggested responsibilities:

• client.ts: initialize and expose @contoprix/client
• auth.ts: token or refresh-related helpers
• mappers.ts: transform SDK responses into UI-friendly shapes
• types.ts: local re-exports or narrowed models based on @contoprix/types

This keeps page files smaller and makes future SDK version updates easier to manage.

Common mistakes for SDK consumers

• calling raw backend endpoints when an SDK method already exists
• spreading SDK imports across many unrelated UI components
• mixing auth logic into rendering components
• skipping tenant or website context setup
• building the first implementation around too many content types at once

Recommended next steps

After your first SDK-driven page is working:

1. create a shared content-fetching layer for repeated patterns
2. add typed mappers for important content shapes
3. separate server-only and client-safe helpers
4. document which SDK packages and methods your frontend relies on
5. expand gradually into more pages, global content, and reusable sections

The next best pages to read are:

• CMS Overview to understand where editors create the data you consume
• Page Builder to understand how structured sections map into UI
• API and SDK for deeper client setup and integration patterns