Client SDK

Browser-side TypeScript SDK for interacting with the Nextly REST API from React and other frontend frameworks.

The Client SDK (@nextlyhq/client) provides a typed interface for the Nextly REST API from browser-side code. Use it in React components, Next.js client components, or any frontend JavaScript environment where the Direct API is not available.

Installation

npm install @nextlyhq/client

Initialization

Create a client instance with your API base URL:

lib/nextly-client.ts

import { NextlySDK } from '@nextlyhq/client';

export const sdk = new NextlySDK({
  baseURL: '/api',
});

For external applications connecting to a remote Nextly instance, pass the full URL:

const sdk = new NextlySDK({
  baseURL: 'https://example.com/api',
});

API Key Authentication

To authenticate requests with an API key, pass it in the config:

const sdk = new NextlySDK({
  baseURL: '/api',
  apiKey: 'sk_live_abc123...',
});

The API key is sent as a Bearer token in the Authorization header on every request.

Configuration

The NextlySDK constructor accepts a NextlySDKConfig object:

Option	Type	Required	Description
`baseURL`	`string`	Yes	Base URL for the Nextly REST API (e.g., `/api` or `https://example.com/api`)
`apiKey`	`string`	No	API key for Bearer token authentication

Available Methods

The SDK mirrors the Direct API method signatures, making it easy to switch between server-side and client-side data access.

find

Find multiple documents in a collection:

const result = await sdk.find({ collection: 'posts' });

findByID

Find a single document by ID:

const post = await sdk.findByID({
  collection: 'posts',
  id: 'abc-123',
});

create

Create a new document:

const newPost = await sdk.create({
  collection: 'posts',
  data: {
    title: 'Hello World',
    content: 'My first post',
    status: 'draft',
  },
});

update

Update an existing document:

const updated = await sdk.update({
  collection: 'posts',
  id: 'abc-123',
  data: { status: 'published' },
});

delete

Delete a document:

await sdk.delete({
  collection: 'posts',
  id: 'abc-123',
});

Example: React Component

A practical example using the Client SDK in a React client component:

components/PostList.tsx

'use client';

import { useEffect, useState } from 'react';
import { NextlySDK } from '@nextlyhq/client';

const sdk = new NextlySDK({ baseURL: '/api' });

interface Post {
  id: string;
  title: string;
  status: string;
  createdAt: string;
}

export function PostList() {
  const [posts, setPosts] = useState<Post[]>([]);
  const [loading, setLoading] = useState(true);

  useEffect(() => {
    async function loadPosts() {
      try {
        const result = await sdk.find({ collection: 'posts' });
        setPosts(result.docs ?? []);
      } catch (error) {
        console.error('Failed to load posts:', error);
      } finally {
        setLoading(false);
      }
    }

    loadPosts();
  }, []);

  if (loading) return <p>Loading...</p>;

  return (
    <ul>
      {posts.map((post) => (
        <li key={post.id}>{post.title}</li>
      ))}
    </ul>
  );
}

TypeScript Support

The SDK exports its configuration type for convenience:

import type { NextlySDKConfig, NextlyClientConfig } from '@nextlyhq/client';

// NextlyClientConfig is an alias for NextlySDKConfig

When working with typed collections, you can cast the results to your generated types:

import type { Post } from '@/payload-types';

const result = await sdk.find({ collection: 'posts' });
const posts = result.docs as Post[];

Server Components vs. Client SDK

Choose the right API based on where your code runs:

	Direct API	Client SDK
Environment	Server only (Node.js)	Browser / client-side
Import	`@nextlyhq/nextly`	`@nextlyhq/client`
Transport	Direct function calls (no HTTP)	HTTP requests to REST API
Access control	Bypassed by default	Always enforced via auth
Use case	Server Components, Server Actions, API Routes	React client components, SPAs, mobile apps

Prefer the Direct API whenever possible. It is faster (no HTTP overhead), runs in a trusted context, and provides full type safety with generated types. Use the Client SDK only when you need to access data from browser-side code.

Fetching Data in Server Components

For Next.js Server Components, use the Direct API instead of the Client SDK:

app/posts/page.tsx (Server Component)

import { getNextly } from '@nextlyhq/nextly';

export default async function PostsPage() {
  const nextly = getNextly();
  const posts = await nextly.find({
    collection: 'posts',
    where: { status: { equals: 'published' } },
    sort: '-createdAt',
    limit: 10,
  });

  return (
    <ul>
      {posts.docs.map((post) => (
        <li key={post.id}>{post.title}</li>
      ))}
    </ul>
  );
}

Next Steps

Direct API -- Server-side API with zero HTTP overhead
REST API -- Full HTTP endpoint reference that the Client SDK calls under the hood
Authentication -- API key authentication for client-side requests
Collections -- Define the content types the SDK operates on

Client SDK

On this page