\n\n \n\n## 📖 Table of contents\n\n1. [Getting Started](#-getting-started)\n - [Prerequisites](#pre-requisites)\n - [Installation](#installation)\n2. [Creating and Configuring a Strapi Client Instance](#-creating-and-configuring-the-client-instance)\n - [Basic Configuration](#basic-configuration)\n - [Authentication](#authentication)\n - [API Token Authentication](#api-token-authentication)\n - [Custom Headers](#custom-headers)\n3. [API Reference](#-api-reference)\n4. [Resource Managers](#-resource-managers)\n - [`.collection()`](#collectionresource-options)\n - [`.single()`](#singleresource-options)\n - [`.files`](#files)\n5. [Debug](#-debug)\n6. [Demo Projects](#-demo-projects)\n7. [Contributing](./CONTRIBUTING.md)\n\n## 🛠 Getting started\n\n### Pre-Requisites\n\nBefore you begin, ensure you have the following:\n\n- A Strapi backend up and running: [quick start guide](https://docs.strapi.io/dev-docs/quick-start).\n- The API URL of your Strapi instance: for example, `http://localhost:1337/api`.\n- A recent version of [Node.js](https://nodejs.org/en/download/package-manager) installed.\n\n### Installation\n\nInstall the client as a dependency in your project:\n\n**NPM**\n\n```bash\nnpm install @strapi/client\n```\n\n**Yarn**\n\n```bash\nyarn add @strapi/client\n```\n\n**pnpm**\n\n```bash\npnpm add @strapi/client\n```\n\n## ⚙️ Creating and configuring the client Instance\n\n### Basic configuration\n\nTo interact with your Strapi backend, initialize the client with your Strapi API base URL:\n\n```typescript\nimport { strapi } from '@strapi/client';\n\nconst client = strapi({ baseURL: 'http://localhost:1337/api' });\n```\n\nAlternatively, use a `\n\n\n```\n\n### Authentication\n\nThe client library supports multiple authentication strategies for accessing authenticated content in your Strapi backend.\n\n#### API-Token authentication\n\nIf your Strapi instance uses API tokens, configure the client like this:\n\n```typescript\nconst client = strapi({\n // Endpoint configuration\n baseURL: 'http://localhost:1337/api',\n // Auth configuration\n auth: 'your-api-token-here',\n});\n```\n\n#### Custom Headers\n\nYou can configure custom headers to be included with every request made by the client:\n\n```typescript\nconst client = strapi({\n baseURL: 'http://localhost:1337/api',\n auth: 'your-api-token-here',\n headers: {\n 'X-Custom-Header': 'value',\n 'Accept-Language': 'en-US',\n },\n});\n```\n\nCustom headers specified in the client configuration are applied to all requests\n\n**Example: Using Custom Headers**\n\n```typescript\n// Initialize client with custom headers\nconst client = strapi({\n baseURL: 'http://localhost:1337/api',\n headers: {\n 'X-Request-ID': '12345',\n 'Accept-Language': 'en-US',\n },\n});\n\n// Headers will be included in all requests\nconst articles = await client.collection('articles').find();\n```\n\n## 📚 API Reference\n\nThe Strapi client library instance provides key properties and utility methods for content and API interaction:\n\n- **`baseURL`**: base URL of your Strapi backend.\n- **`fetch()`**: perform generic requests to the Strapi Content API using fetch-like syntax.\n- **`collection()`**: get a manager instance for handling collection-type resources.\n- **`single()`**: get a manager instance for handling single-type resources.\n- **`files`**: access the files manager instance for handling common files operations.\n\n## 📁 Resource Managers\n\n### `.collection(resource, [options])`\n\nThe `.collection()` method provides a manager for working with collection-type resources,\nwhich can have multiple entries.\n\n#### Params\n\n- `resource`: `string` - plural name of your collection type, as defined in the Strapi model\n- `[options]`: `object` - additional options to pass to the collection type manager\n - `[path]`: `string` - optional root path override for the manager's queries\n\n#### Available Methods:\n\n1. **`find(queryParams?)`**: fetch multiple entries.\n2. **`findOne(documentID, queryParams?)`**: fetch a single entry by its ID.\n3. **`create(data, queryParams?)`**: create a new entry.\n4. **`update(documentID, data, queryParams?)`**: update an existing entry.\n5. **`delete(documentID, queryParams?)`**: remove an entry.\n\n#### Examples:\n\n```typescript\nconst articles = client.collection('articles');\n\n// Fetch all english articles sorted by title\nconst allArticles = await articles.find({\n locale: 'en',\n sort: 'title',\n});\n\n// Fetch a single article\nconst singleArticle = await articles.findOne('article-document-id');\n\n// Create a new article\nconst newArticle = await articles.create({ title: 'New Article', content: '...' });\n\n// Update an existing article\nconst updatedArticle = await articles.update('article-document-id', { title: 'Updated Title' });\n\n// Delete an article\nawait articles.delete('article-id');\n```\n\n#### Working with Users (Users-Permissions Plugin)\n\nThe client automatically detects and handles special Strapi content-types like `users` from the users-permissions plugin. You can work with them seamlessly:\n\n```typescript\n// Auto-detected as users-permissions - no configuration needed!\nconst users = client.collection('users');\n\n// Create a new user\nawait users.create({\n username: 'john',\n email: 'john@example.com',\n password: 'SecurePass123!',\n role: 1,\n});\n\n// Find users\nconst allUsers = await users.find();\n\n// Update a user\nawait users.update('user-id', { username: 'john_updated' });\n```\n\n> **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.\n\n#### Custom Path\n\nYou can also customize the root path for requests by providing a value for the `path` option:\n\n```typescript\nconst articles = client.collection('articles', { path: '/my-custom-path' });\n```\n\n### `.single(resource, [options])`\n\nThe `.single()` method provides a manager for working with single-type resources, which have only one entry.\n\n#### Params\n\n- `resource`: `string` - singular name of your single type, as defined in the Strapi model\n- `[options]`: `object` - additional options to pass to the single type manager\n - `[path]`: `string` - optional root path override for the manager's queries\n\n#### Available Methods:\n\n1. **`find(queryParams?)`**: fetch the document.\n2. **`update(data, queryParams?)`**: update the document.\n3. **`delete(queryParams?)`**: remove the document.\n\n#### Examples:\n\n```typescript\nconst homepage = client.single('homepage');\n\n// Fetch the default version of the homepage\nconst defaultHomepage = await homepage.find();\n\n// Fetch the spanish version of the homepage\nconst spanishHomepage = await homepage.find({ locale: 'es' });\n\n// Update the homepage draft content\nconst updatedHomepage = await homepage.update(\n { title: 'Updated Homepage Title' },\n { status: 'draft' }\n);\n\n// Delete the homepage content\nawait homepage.delete();\n```\n\nYou can also customize the root path for requests by providing a value for the `path` option:\n\n```typescript\nconst homepage = client.single('homepage', { path: '/my-custom-path' });\n```\n\n### `.files`\n\nThe `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.\n\n#### Methods\n\n- `find(params?: FileQueryParams): Promise` - Retrieves a list of file metadata based on optional query parameters\n- `findOne(fileId: number): Promise` - Retrieves the metadata for a single file by its ID\n- `update(fileId: number, fileInfo: FileUpdateData): Promise` - Updates metadata for an existing file\n- `delete(fileId: number): Promise` - Deletes a file by its ID\n\n#### Examples\n\n**Finding all files**\n\n```typescript\n// Initialize the client\nconst client = strapi({\n baseURL: 'http://localhost:1337/api',\n auth: 'your-api-token',\n});\n\n// Find all file metadata\nconst allFiles = await client.files.find();\nconsole.log(allFiles);\n\n// Find file metadata with filtering and sorting\nconst imageFiles = await client.files.find({\n filters: {\n mime: { $contains: 'image' }, // Only get image files\n name: { $contains: 'avatar' }, // Only get files with 'avatar' in the name\n },\n sort: ['name:asc'], // Sort by name in ascending order\n});\n```\n\n**Finding a Single File**\n\n```typescript\n// Initialize the client\nconst client = strapi({\n baseURL: 'http://localhost:1337/api',\n auth: 'your-api-token',\n});\n\n// Find file metadata by ID\nconst file = await client.files.findOne(1);\n\nconsole.log(file.name); // The file name\nconsole.log(file.url); // The file URL\nconsole.log(file.mime); // The file MIME type\n```\n\n**Updating File Metadata**\n\n```typescript\n// Initialize the client\nconst client = strapi({\n baseURL: 'http://localhost:1337/api',\n auth: 'your-api-token',\n});\n\n// Update file metadata\nconst updatedFile = await client.files.update(1, {\n name: 'New file name',\n alternativeText: 'Descriptive alt text for accessibility',\n caption: 'A caption for the file',\n});\n\nconsole.log(updatedFile.name); // Updated file name\nconsole.log(updatedFile.alternativeText); // Updated alt text\n```\n\n**Deleting a File**\n\n```typescript\n// Initialize the client\nconst client = strapi({\n baseURL: 'http://localhost:1337/api',\n auth: 'your-api-token',\n});\n\n// Delete a file by ID\nconst deletedFile = await client.files.delete(1);\n\nconsole.log('File deleted successfully');\nconsole.log('Deleted file ID:', deletedFile.id);\nconsole.log('Deleted file name:', deletedFile.name);\n```\n\n## 🐛 Debug\n\nThis section provides guidance on enabling and managing debug logs for the SDK,\npowered by [debug](https://github.com/debug-js/debug/).\n\n### Node.js Debugging\n\nIn **Node.js bundles** (`cjs`, `esm`), debugging capabilities are always available to use.\n\nYou can turn on or off debug logs using the `DEBUG` environment variable:\n\n```bash\n# Enable logs for all namespaces\nDEBUG=*\n\n# Enable logs for a specific namespace\nDEBUG=strapi:http\n\n# Turn off logs\nunset DEBUG\n```\n\n### Browser Debugging\n\nFor **browser environments**, debug capabilities are intentionally turned off to optimize the bundle size.\n\n### Usage Overview\n\nThe `debug` tool allows you to control logs using wildcard patterns (`*`):\n\n- `*`: enable all logs.\n- `strapi:module`: enable logs for a specific module.\n- `strapi:module1,sdk:module2`: enable logs for multiple modules.\n- `strapi:*`: match all namespaces under `strapi`.\n- `strapi:*,-strapi:module2`: enable all logs except those from `strapi:module2`.\n\n### Namespaces\n\nBelow is a list of available namespaces to use:\n\n| Namespace | Description |\n| -------------------------------- | ----------------------------------------------------------------------------------------- |\n| `strapi:core` | Logs SDK initialization, configuration validation, and HTTP client setup. |\n| `strapi:validators:config` | Logs details related to SDK configuration validation. |\n| `strapi:validators:url` | Logs URL validation processes. |\n| `strapi:http` | Logs HTTP client setup, request processing, and response/error handling. |\n| `strapi:auth:factory` | Logs the registration and creation of authentication providers. |\n| `strapi:auth:manager` | Logs authentication lifecycle management. |\n| `strapi:auth:provider:api-token` | Logs operations related to API token authentication. |\n| `strapi:ct:collection` | Logs interactions with collection-type content managers. |\n| `strapi:ct:single` | Logs interactions with single-type content managers. |\n| `strapi:utils:url-helper` | Logs URL helper utility operations (e.g., appending query parameters or formatting URLs). |\n| `strapi:files` | Logs interactions with the files manager. |\n\n## 🚀 Demo Projects\n\nThis 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.\n\n### Demo Structure\n\n- **`.strapi-app`**: the main Strapi app used for the demo projects.\n- **`demo/node-typescript`**: a Node.js project using TypeScript.\n- **`demo/node-javascript`**: a Node.js project using JavaScript.\n- **`demo/next-server-components`**: a Next.js project using TypeScript and server components.\n- **`demo/react-vite`**: a React project using Vite and TypeScript\n\n### Using Demo Commands\n\nThe repository supports running demo-related commands directly using the format `pnpm demo `.\n\nTo display the entire list of available commands, use `pnpm demo help`\n\n#### Comprehensive Setup:\n\n- **`pnpm demo setup`** \n A complete setup command that installs dependencies, sets up the environment,\n builds the projects, and seeds the database with initial data for the demo app.\n\n It is a one-stop command for preparing everything.\n\n ```bash\n pnpm demo setup\n ```\n\n#### Development:\n\n- **`pnpm demo app:start`** \n Starts the Strapi demo app in development mode. This is useful for testing and making changes to the Strapi backend.\n\n ```bash\n pnpm demo app:start\n ```\n\n#### Database Seeding:\n\n- **`pnpm demo app:seed`** \n Seeds the Strapi app with sample data. Use this when you want to populate your Strapi app with default content.\n\n ```bash\n pnpm demo app:seed\n ```\n\n- **`pnpm demo app:seed:clean`** \n Cleans the existing database and re-seeds the Strapi demo app.\n This is helpful if you want to reset the demo data to its initial state.\n\n ```bash\n pnpm demo app:seed:clean\n ```\n\n#### Build and Install:\n\n- **`pnpm demo build`** \n Builds the main Strapi app and all demo projects.\n\n Use this to prepare the projects for use, ensuring all components are compiled and ready.\n\n ```bash\n pnpm demo build\n ```\n\n- **`pnpm demo install`** \n Installs dependencies for the main Strapi app and all demo applications.\n\n This command ensures that all required packages are downloaded and ready to go.\n\n ```bash\n pnpm demo install\n ```\n\n#### Environment Setup:\n\n- **`pnpm demo app:env:setup`** \n Sets up the `.env` file for the main Strapi app by copying the example `.env.example` file if no `.env` file exists.\n\n This ensures the environment is configured appropriately.\n\n ```bash\n pnpm demo app:env:setup\n ```\n\n---\n\n#### Adding New Projects\n\nNew projects added to the `/demo` directory are automatically picked up by the demo scripts.\nThus, no explicit configuration updates are required for these commands to work with new demo directories.\n\n**Note:** if a project needs to be built to be used, add a `build` script\nto its `package.json` so that the demo scripts automatically run it.\n\n---\n\n#### Future Plans\n\nWe plan to expand the demo projects to include:\n\n- A basic HTML project\n- A Vue.js project (with or without server components)\n- A Svelte project\n","readmeFilename":"README.md"}
![\"Strapi](\"https://strapi.io/assets/strapi-logo-dark.svg\"){kind=logo}
\n \n \n ![\"Strapi](\"https://strapi.io/assets/strapi-logo-light.svg\"){kind=logo}
\n \n![\"NPM](\"https://img.shields.io/npm/v/@strapi/client/latest.svg\")
\n \n \n ![\"NPM](\"https://img.shields.io/npm/dm/@strapi/client\")
![\"Tests\"](\"https://github.com/strapi/client/actions/workflows/tests.yml/badge.svg?branch=main\"){kind=icon}
\n \n \n ![\"Strapi](\"https://img.shields.io/discord/811989166782021633?label=Discord\")