Strapi JavaScript SDK

Common errors

• Error: Request failed with status code 401

  cause Authentication failed due to incorrect credentials, missing token, or an expired token when accessing protected routes.
  fix Double-check your `strapi.login('identifier', 'password')` credentials. Ensure the Strapi server is running and accessible. If already logged in, the token might have expired, requiring re-authentication or a token refresh (which the SDK does not provide automatically).

• TypeError: strapi.getEntries is not a function

  cause Attempting to call methods on an uninitialized or incorrectly initialized `Strapi` object, or calling a method that doesn't exist on the `Strapi` instance.
  fix Verify that `const strapi = new Strapi('http://localhost:1337');` has been executed before calling any methods on `strapi`. Check the API section of the README to ensure the method name and parameters are correct.

• ReferenceError: FormData is not defined (in Node.js)

  cause Attempting to use `FormData` for file uploads in a Node.js environment without importing the `form-data` package.
  fix Install `form-data` (`npm install form-data`) and explicitly `const FormData = require('form-data');` at the top of your Node.js file when performing file uploads.

• Error: Network Error (axios)

  cause The SDK could not connect to the specified Strapi server URL. This might be due to an incorrect `baseURL`, the Strapi server not running, or network connectivity issues (e.g., CORS policy blocking requests from a browser).
  fix Verify that the `baseURL` passed to `new Strapi(baseURL)` is correct and the Strapi server is running. If in a browser, check the browser console for CORS errors and ensure your Strapi server is configured to allow requests from your frontend's origin.

Warnings

• breaking The `strapi-sdk-javascript` package is officially unmaintained and deprecated by the Strapi team. Using it in production is highly discouraged as it will not receive updates, security patches, or support for newer Strapi versions or features.
  Fix: Migrate your application to use a generic HTTP client (e.g., Axios, Fetch API) to interact directly with your Strapi API endpoints. Consult the Strapi API documentation for endpoint structures and request formats.
• gotcha This SDK was primarily designed for Strapi v3 (beta.x and early v3 versions). It does not natively support Strapi v4's updated API structures, new authentication flows, or features like GraphQL which were part of the SDK's roadmap but never implemented.
  Fix: If using Strapi v4, definitely do not use this SDK. Implement API interactions manually using a modern HTTP client, following Strapi v4's specific documentation.
• deprecated File upload functionality requires `form-data` in Node.js, and browser-specific `FormData` in the browser. The `upload` method's `headers` parameter for Node.js is specific to getting headers from `form-data` and can be a point of confusion if not handled correctly.
  Fix: Ensure `form-data` is explicitly installed and correctly used with `form.getHeaders()` when uploading files in Node.js. For modern API interactions, consider using libraries that abstract multipart/form-data creation more directly if not using `fetch` with native `FormData`.
• gotcha The SDK stores the JWT token locally (e.g., in localStorage in browsers). While convenient, developers must ensure proper security practices around token storage and expiration are followed, especially in single-page applications.
  Fix: Understand the security implications of client-side token storage. Implement token refresh mechanisms or secure storage strategies if not relying solely on the SDK's default behavior, though for an abandoned SDK, custom handling is more robust.

Install

• npm install strapi-sdk-javascript npm
• yarn add strapi-sdk-javascript yarn
• pnpm add strapi-sdk-javascript pnpm

Imports

• Strapi
  wrong:

  const Strapi = require('strapi-sdk-javascript');

  correct:

  import Strapi from 'strapi-sdk-javascript';

  While CommonJS `require` might work in some environments, the official documentation and examples use ESM `import`. It's recommended to use ESM for modern JavaScript projects.
• StrapiInstanceMethods

  import Strapi from 'strapi-sdk-javascript';
  const strapi = new Strapi('http://localhost:1337');
  await strapi.login('user', 'pass');

  Most interactions occur through methods on an instantiated `Strapi` object. There are no direct named exports for individual API methods.
• TypeDefinition

  import type Strapi from 'strapi-sdk-javascript';

  The package ships with TypeScript types. For type-only imports in TypeScript, use `import type` to ensure it's removed during compilation.

Quickstart

This quickstart demonstrates how to instantiate the Strapi SDK, perform local user authentication, and fetch entries from a Strapi API, including error handling. It uses environment variables for configuration.

import Strapi from 'strapi-sdk-javascript';

const STRAPI_BASE_URL = process.env.STRAPI_URL ?? 'http://localhost:1337';
const STRAPI_USERNAME = process.env.STRAPI_USERNAME ?? 'testuser';
const STRAPI_PASSWORD = process.env.STRAPI_PASSWORD ?? 'password';

async function runStrapiSdkExample() {
  console.log(`Connecting to Strapi at: ${STRAPI_BASE_URL}`);
  const strapi = new Strapi(STRAPI_BASE_URL);

  try {
    // Local authentication
    console.log('Attempting local login...');
    await strapi.login(STRAPI_USERNAME, STRAPI_PASSWORD);
    console.log('Login successful! Token stored.');

    // Fetch entries (e.g., 'posts')
    const posts = await strapi.getEntries('posts');
    console.log(`Fetched ${posts.length} posts:`, posts.map(p => p.title));

    // Example: Create an entry (assuming 'articles' is a content type)
    // const newArticle = await strapi.createEntry('articles', { title: 'SDK Test Article', content: 'Content from SDK' });
    // console.log('Created new article:', newArticle);

    // Example: Get entry count
    const postCount = await strapi.getEntryCount('posts');
    console.log(`Total posts count: ${postCount}`);

  } catch (error) {
    console.error('Error during Strapi SDK operations:', error.message);
    if (error.response) {
      console.error('Server response:', error.response.data);
    }
  }
}

runStrapiSdkExample();