reslear/sdk-js

An SDK for easily interfacing with Strapi from your JavaScript project

Manage Your Strapi Content From Anywhere 🚀

Connect your JavaScript/TypeScript apps to a flexible and fully customizable Strapi backend with ease.

CMS Repository - Website

📖 Table of contents

1. Getting Started
   • Prerequisites
   • Installation
2. Creating and Configuring an SDK Instance
   • Basic Configuration
   • Authentication
     • API Token Authentication
3. API Reference
4. Resource Managers
   • .collection()
   • .single()
5. Debug

🛠 Getting started

Pre-Requisites

Before you begin, ensure you have the following:

• A Strapi backend up and running: quick start guide.
• The API URL of your Strapi instance: for example, http://localhost:1337/api.
• A recent version of Node.js installed.

Installation

Install the SDK as a dependency in your project:

NPM

npm install @strapi/sdk-js

Yarn

yarn add @strapi/sdk-js

pnpm

pnpm add @strapi/sdk-js

⚙️ Creating and configuring the SDK Instance

Basic configuration

To interact with your Strapi backend, initialize the SDK with your Strapi API base URL:

import { strapiSDK } from '@strapi/sdk-js';

const sdk = strapiSDK({ baseURL: 'http://localhost:1337/api' });

Alternatively, use a <script> tag in a browser environment:

<script src="https://cdn.jsdelivr.net/npm/@strapi/sdk-js"></script>

<script>
  const sdk = strapi.strapiSDK({ baseURL: 'http://localhost:1337/api' });
</script>

Authentication

The SDK supports multiple authentication strategies for accessing authenticated content in your Strapi backend.

API-Token authentication

If your Strapi instance uses API tokens, configure the SDK like this:

const sdk = strapiSDK({
  baseURL: 'http://localhost:1337/api',
  auth: {
    strategy: 'api-token',
    options: { token: 'your-api-token-here' },
  },
});

📚 API Reference

The Strapi SDK instance provides key properties and utility methods for content and API interaction:

• baseURL: base URL of your Strapi backend.
• fetch: perform generic requests to the Strapi Content API using fetch-like syntax.
• .collection(resource: string): get a manager instance for handling collection-type resources.
• .single(resource: string): get a manager instance for handling single-type resources.

📁 Resource Managers

.collection(resource)

The .collection() method provides a manager for working with collection-type resources, which can have multiple entries.

Note: the resource corresponds to the plural name of your collection type, as defined in the Strapi model.

Available Methods:

1. find(queryParams?): fetch multiple entries.
2. findOne(documentID, queryParams?): fetch a single entry by its ID.
3. create(data, queryParams?): create a new entry.
4. update(documentID, data, queryParams?): update an existing entry.
5. delete(documentID, queryParams?): remove an entry.

Examples:

const articles = sdk.collection('articles');

// Fetch all english articles sorted by title
const allArticles = await articles.find({
  locale: 'en',
  sort: 'title',
});

// Fetch a single article
const singleArticle = await articles.findOne('article-document-id');

// Create a new article
const newArticle = await articles.create({ title: 'New Article', content: '...' });

// Update an existing article
const updatedArticle = await articles.update('article-document-id', { title: 'Updated Title' });

// Delete an article
await articles.delete('article-id');

.single(resource)

The .single() method provides a manager for working with single-type resources, which have only one entry.

Note: the resource corresponds to the singular name of your collection type, as defined in the Strapi model.

Available Methods:

1. find(queryParams?): fetch the document.
2. update(data, queryParams?): update the document.
3. delete(queryParams?): remove the document.

Examples:

const homepage = sdk.single('homepage');

// Fetch the default version of the homepage
const defaultHomepage = await homepage.find();

// Fetch the spanish version of the homepage
const spanishHomepage = await homepage.find({ locale: 'es' });

// Update the homepage draft content
const updatedHomepage = await homepage.update(
  { title: 'Updated Homepage Title' },
  { status: 'draft' }
);

// Delete the homepage content
await homepage.delete();

🐛 Debug

This section provides guidance on enabling and managing debug logs for the SDK, powered by debug.

Node.js Debugging

In Node.js bundles (cjs, esm), debugging capabilities are always available to use.

You can turn on or off debug logs using the DEBUG environment variable:

# Enable logs for all namespaces
DEBUG=*

# Enable logs for a specific namespace
DEBUG=sdk:http

# Turn off logs
unset DEBUG

Browser Debugging

For browser environments, debug capabilities are intentionally turned off to optimize the bundle size.

Usage Overview

The debug tool allows you to control logs using wildcard patterns (*):

• *: enable all logs.
• sdk:module: enable logs for a specific module.
• sdk:module1,sdk:module2: enable logs for multiple modules.
• sdk:*: match all namespaces under sdk.
• sdk:*,-sdk:module2: enable all logs except those from sdk:module2.

Namespaces

Below is a list of available namespaces to use:

Namespace	Description
sdk:core	Logs SDK initialization, configuration validation, and HTTP client setup.
sdk:validators:sdk	Logs details related to SDK configuration validation.
sdk:validators:url	Logs URL validation processes.
sdk:http	Logs HTTP client setup, request processing, and response/error handling.
sdk:auth:factory	Logs the registration and creation of authentication providers.
sdk:auth:manager	Logs authentication lifecycle management.
sdk:auth:provider:api-token	Logs operations related to API token authentication.
sdk:auth:provider:users-permissions	Logs operations related to user and permissions-based authentication.
sdk:ct:collection	Logs interactions with collection-type content managers.
sdk:ct:single	Logs interactions with single-type content managers.
sdk:utils:url-helper	Logs URL helper utility operations (e.g., appending query parameters or formatting URLs).