Strapi Client

The Strapi Client library simplifies interactions with your Strapi back end, providing a way to fetch, create, update, and delete content. This guide walks you through setting up the Strapi Client, configuring authentication, and using its key features effectively.

Getting Started

Prerequisites

• A Strapi project has been created and is running. If you haven't set one up yet, follow the Quick Start Guide to create one.
• You know the URL of the Content API of your Strapi instance (e.g., http://localhost:1337/api).

Installation

To use the Strapi Client in your project, install it as a dependency using your preferred package manager:

Yarn

yarn add @strapi/client

NPM

npm install @strapi/client

pnpm

  pnpm add @strapi/client

Basic configuration

To start interacting with your Strapi back end, initialize the Strapi Client and set the base API URL:

import { strapi } from '@strapi/client';

const client = strapi({ baseURL: 'http://localhost:1337/api' });

If you're using the Strapi Client in a browser environment, you can include it using a <script> tag:

./src/api/[apiName]/routes/[routerName].ts (e.g './src/api/restaurant/routes/restaurant.ts')

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

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

Authentication

The Strapi Client supports different authentication strategies to access protected resources in your Strapi back end.

If your Strapi instance uses API tokens, configure the Strapi Client as follows:

const client = strapi({
  baseURL: 'http://localhost:1337/api',
  auth: 'your-api-token-here',
});

This allows your requests to include the necessary authentication credentials automatically.

API Reference

The Strapi Client provides the following key properties and methods for interacting with your Strapi back end:

Parameter	Description
baseURL	The base API URL of your Strapi back end.
fetch()	A utility method for making generic API requests similar to the native fetch API.
collection()	Manages collection-type resources (e.g., blog posts, products).
single()	Manages single-type resources (e.g., homepage settings, global configurations).

General purpose fetch

The Strapi Client provides access to the underlying JavaScript fetch function to make direct API requests. The request is always relative to the base URL provided during client initialization:

const result = await client.fetch('articles', { method: 'GET' });

Working with collection types

Collection types in Strapi are entities with multiple entries (e.g., a blog with many posts). The Strapi Client provides a collection() method to interact with these resources, with the following methods available:

Parameter	Description
find(queryParams?)	Fetch multiple documents with optional filtering, sorting, or pagination.
findOne(documentID, queryParams?)	Retrieve a single document by its unique ID.
create(data, queryParams?)	Create a new document in the collection.
update(documentID, data, queryParams?)	Update an existing document.
delete(documentID, queryParams?)	Update an existing document.

Usage examples:

const articles = client.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');

Working with single types

Single types in Strapi represent unique content entries that exist only once (e.g., the homepage settings or site-wide configurations). The Strapi Client provides a single() method to interact with these resources, with the following methods available:

Parameter	Description
find(queryParams?)	Fetch the document.
update(documentID, data, queryParams?)	Update the document.
delete(queryParams?)	Remove the document.

Usage examples:

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

// Fetch the default homepage content
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();

Working with files NewThis content is new.

The Strapi Client provides access to the Media Library via the files property. This allows you to retrieve and manage file metadata without directly interacting with the REST API.

The following methods are available for working with files:

Method	Description
find(params?)	Retrieves a list of file metadata based on optional query parameters
findOne(fileId)	Retrieves the metadata for a single file by its ID
update(fileId, fileInfo)	Updates metadata for an existing file
delete(fileId)	Deletes a file by its ID

Usage examples:

// Initialize the client
const client = strapi({
  baseURL: 'http://localhost:1337/api',
  auth: 'your-api-token',
});

// Find all file metadata
const allFiles = await client.files.find();
console.log(allFiles);

// Find file metadata with filtering and sorting
const imageFiles = await client.files.find({
  filters: {
    mime: { $contains: 'image' }, // Only get image files
    name: { $contains: 'avatar' }, // Only get files with 'avatar' in the name
  },
  sort: ['name:asc'], // Sort by name in ascending order
});

// Find file metadata by ID
const file = await client.files.findOne(1);
console.log(file.name); // The file name
console.log(file.url); // The file URL
console.log(file.mime); // The file MIME type

// Update file metadata
const updatedFile = await client.files.update(1, {
  name: 'New file name',
  alternativeText: 'Descriptive alt text for accessibility',
  caption: 'A caption for the file',
});

// Delete a file by ID
const deletedFile = await client.files.delete(1);
console.log('File deleted successfully');
console.log('Deleted file ID:', deletedFile.id);
console.log('Deleted file name:', deletedFile.name);

Additional information

More details about the Strapi Strapi Client might be found in the package's README.