Manage Your Strapi Content From Anywhere 🚀

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

CMS Repository - Website - SDK Roadmap

📖 Table of contents

1. Getting Started
   • Prerequisites
   • Installation
2. Creating and Configuring a Strapi Client Instance
   • Basic Configuration
   • Authentication
     • API Token Authentication
     • Custom Headers
3. API Reference
4. Resource Managers
   • .collection()
   • .single()
   • .files
5. Debug
6. Demo Projects
7. Contributing

🛠 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 client as a dependency in your project:

NPM

npm install @strapi/client

Yarn

yarn add @strapi/client

pnpm

pnpm add @strapi/client

⚙️ Creating and configuring the client Instance

Basic configuration

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

import{strapi}from'@strapi/client';constclient=strapi({baseURL: 'http://localhost:1337/api'});

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

<scriptsrc="https://cdn.jsdelivr.net/npm/@strapi/client"></script><script>constclient=strapi.strapi({baseURL: 'http://localhost:1337/api'});</script>

Authentication

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

API-Token authentication

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

constclient=strapi({// Endpoint configurationbaseURL: 'http://localhost:1337/api',// Auth configurationauth: 'your-api-token-here',});

Custom Headers

You can configure custom headers to be included with every request made by the client:

constclient=strapi({baseURL: 'http://localhost:1337/api',auth: 'your-api-token-here',headers: {'X-Custom-Header': 'value','Accept-Language': 'en-US',},});

Custom headers specified in the client configuration are applied to all requests

Example: Using Custom Headers

// Initialize client with custom headersconstclient=strapi({baseURL: 'http://localhost:1337/api',headers: {'X-Request-ID': '12345','Accept-Language': 'en-US',},});// Headers will be included in all requestsconstarticles=awaitclient.collection('articles').find();

📚 API Reference

The Strapi client library 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(): get a manager instance for handling collection-type resources.
• single(): get a manager instance for handling single-type resources.
• files: access the files manager instance for handling common files operations.

📁 Resource Managers

.collection(resource, [options])

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

Params

• resource: string - plural name of your collection type, as defined in the Strapi model
• [options]: object - additional options to pass to the collection type manager
  • [path]: string - optional root path override for the manager's queries

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:

constarticles=client.collection('articles');// Fetch all english articles sorted by titleconstallArticles=awaitarticles.find({locale: 'en',sort: 'title',});// Fetch a single articleconstsingleArticle=awaitarticles.findOne('article-document-id');// Create a new articleconstnewArticle=awaitarticles.create({title: 'New Article',content: '...'});// Update an existing articleconstupdatedArticle=awaitarticles.update('article-document-id',{title: 'Updated Title'});// Delete an articleawaitarticles.delete('article-id');

Working with Users (Users-Permissions Plugin)

The client automatically detects and handles special Strapi content-types like users from the users-permissions plugin. You can work with them seamlessly:

// Auto-detected as users-permissions - no configuration needed!constusers=client.collection('users');// Create a new userawaitusers.create({username: 'john',email: 'john@example.com',password: 'SecurePass123!',role: 1,});// Find usersconstallUsers=awaitusers.find();// Update a userawaitusers.update('user-id',{username: 'john_updated'});

Note: The users-permissions plugin has a different API contract than regular content-types. The client automatically handles this by not wrapping the payload in a data object.

Custom Path

You can also customize the root path for requests by providing a value for the path option:

constarticles=client.collection('articles',{path: '/my-custom-path'});

.single(resource, [options])

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

Params

• resource: string - singular name of your single type, as defined in the Strapi model
• [options]: object - additional options to pass to the single type manager
  • [path]: string - optional root path override for the manager's queries

Available Methods:

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

Examples:

consthomepage=client.single('homepage');// Fetch the default version of the homepageconstdefaultHomepage=awaithomepage.find();// Fetch the spanish version of the homepageconstspanishHomepage=awaithomepage.find({locale: 'es'});// Update the homepage draft contentconstupdatedHomepage=awaithomepage.update({title: 'Updated Homepage Title'},{status: 'draft'});// Delete the homepage contentawaithomepage.delete();

You can also customize the root path for requests by providing a value for the path option:

consthomepage=client.single('homepage',{path: '/my-custom-path'});

.files

The files property provides access to the Strapi Media Library through the Upload plugin. It allows you to retrieve files metadata without directly interacting with the REST API manually.

Methods

• find(params?: FileQueryParams): Promise<FileListResponse> - Retrieves a list of file metadata based on optional query parameters
• findOne(fileId: number): Promise<FileResponse> - Retrieves the metadata for a single file by its ID
• update(fileId: number, fileInfo: FileUpdateData): Promise<FileResponse> - Updates metadata for an existing file
• delete(fileId: number): Promise<void> - Deletes a file by its ID

Examples

Finding all files

// Initialize the clientconstclient=strapi({baseURL: 'http://localhost:1337/api',auth: 'your-api-token',});// Find all file metadataconstallFiles=awaitclient.files.find();console.log(allFiles);// Find file metadata with filtering and sortingconstimageFiles=awaitclient.files.find({filters: {mime: {$contains: 'image'},// Only get image filesname: {$contains: 'avatar'},// Only get files with 'avatar' in the name},sort: ['name:asc'],// Sort by name in ascending order});

Finding a Single File

// Initialize the clientconstclient=strapi({baseURL: 'http://localhost:1337/api',auth: 'your-api-token',});// Find file metadata by IDconstfile=awaitclient.files.findOne(1);console.log(file.name);// The file nameconsole.log(file.url);// The file URLconsole.log(file.mime);// The file MIME type

Updating File Metadata

// Initialize the clientconstclient=strapi({baseURL: 'http://localhost:1337/api',auth: 'your-api-token',});// Update file metadataconstupdatedFile=awaitclient.files.update(1,{name: 'New file name',alternativeText: 'Descriptive alt text for accessibility',caption: 'A caption for the file',});console.log(updatedFile.name);// Updated file nameconsole.log(updatedFile.alternativeText);// Updated alt text

Deleting a File

// Initialize the clientconstclient=strapi({baseURL: 'http://localhost:1337/api',auth: 'your-api-token',});// Delete a file by IDconstdeletedFile=awaitclient.files.delete(1);console.log('File deleted successfully');console.log('Deleted file ID:',deletedFile.id);console.log('Deleted file name:',deletedFile.name);

🐛 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=strapi:http
# Turn off logsunset 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.
• strapi:module: enable logs for a specific module.
• strapi:module1,sdk:module2: enable logs for multiple modules.
• strapi:*: match all namespaces under strapi.
• strapi:*,-strapi:module2: enable all logs except those from strapi:module2.

Namespaces

Below is a list of available namespaces to use:

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

🚀 Demo Projects

This repository includes demo projects located in the /demo directory to help you get started with using the client. The actual Strapi app is located in the .strapi-app directory.

Demo Structure

• .strapi-app: the main Strapi app used for the demo projects.
• demo/node-typescript: a Node.js project using TypeScript.
• demo/node-javascript: a Node.js project using JavaScript.
• demo/next-server-components: a Next.js project using TypeScript and server components.
• demo/react-vite: a React project using Vite and TypeScript

Using Demo Commands

The repository supports running demo-related commands directly using the format pnpm demo <command>.

To display the entire list of available commands, use pnpm demo help

Comprehensive Setup:

• pnpm demo setup
  A complete setup command that installs dependencies, sets up the environment, builds the projects, and seeds the database with initial data for the demo app.

  It is a one-stop command for preparing everything.

  pnpm demo setup

Development:

• pnpm demo app:start
  Starts the Strapi demo app in development mode. This is useful for testing and making changes to the Strapi backend.

  pnpm demo app:start

Database Seeding:

• pnpm demo app:seed
  Seeds the Strapi app with sample data. Use this when you want to populate your Strapi app with default content.

  pnpm demo app:seed

• pnpm demo app:seed:clean
  Cleans the existing database and re-seeds the Strapi demo app. This is helpful if you want to reset the demo data to its initial state.

  pnpm demo app:seed:clean

Build and Install:

• pnpm demo build
  Builds the main Strapi app and all demo projects.

  Use this to prepare the projects for use, ensuring all components are compiled and ready.

  pnpm demo build

• pnpm demo install
  Installs dependencies for the main Strapi app and all demo applications.

  This command ensures that all required packages are downloaded and ready to go.

  pnpm demo install

Environment Setup:

• pnpm demo app:env:setup
  Sets up the .env file for the main Strapi app by copying the example .env.example file if no .env file exists.

  This ensures the environment is configured appropriately.

  pnpm demo app:env:setup

---

Adding New Projects

New projects added to the /demo directory are automatically picked up by the demo scripts. Thus, no explicit configuration updates are required for these commands to work with new demo directories.

Note: if a project needs to be built to be used, add a build script to its package.json so that the demo scripts automatically run it.

---

Future Plans

We plan to expand the demo projects to include:

• A basic HTML project
• A Vue.js project (with or without server components)
• A Svelte project