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. Examples

🛠 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 = 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();

💡 Examples

Here’s how to combine .collection() and .single() methods in a real-world scenario:

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

async function main() {
  // Work with collections
  const articles = sdk.collection('articles');
  const newArticle = await articles.create({ title: 'Hello World', content: '...' });
  console.log('Created Article:', newArticle);

  const allArticles = await articles.find({ sort: 'createdAt:desc' });
  console.log('All Articles:', allArticles);

  // Work with single types
  const homepage = sdk.single('homepage');
  const homepageContent = await homepage.find();
  console.log('Homepage Content:', homepageContent);

  const updatedHomepage = await homepage.update({ title: 'Welcome to the New Homepage' });
  console.log('Updated Homepage:', updatedHomepage);
}

main();