ButterCMS JavaScript Client

Common errors

• ReferenceError: require is not defined in ES module scope

  cause Attempting to use `require()` syntax in an ES Module context, which is the default for Node.js 20+ applications or projects explicitly configured as 'type: module'.
  fix Change your import statement from `const Butter = require('buttercms');` to `import Butter from 'buttercms';`. Ensure your `package.json` either has `"type": "module"` or your file uses a `.mjs` extension.

• Error: Invalid API Token

  cause The API token provided during client initialization is either missing, incorrect, or expired.
  fix Verify that your ButterCMS API token is correct and active. Ensure it's passed as the first argument to the `Butter()` function. Avoid hardcoding tokens directly in code; use environment variables (e.g., `process.env.BUTTER_API_TOKEN`).

• TypeError: butter.post.list is not a function

  cause The `butter` client instance was not initialized correctly, or the API call chain (e.g., `post.list`) is incorrect.
  fix Double-check that `const butter = Butter('your_api_token');` is called correctly and returns a valid client object. Refer to the ButterCMS API documentation for the correct resource and method calls (e.g., `butter.post.list`, `butter.page.retrieve`).

Warnings

• breaking Version 3.0.0 introduced a breaking change by upgrading to Node.js 20, making it the minimum required Node.js version. Projects using older Node.js versions must upgrade.
  Fix: Ensure your project's Node.js environment is version 20.18.0 or higher. Update `engines` in `package.json` and your CI/CD pipelines accordingly.
• breaking ButterCMS-JS version 2 (and consequently v3) transitioned from third-party HTTP clients to the native `fetch` API. This is a breaking change for anyone migrating from version 1, as custom Axios configurations or interceptors might no longer work as expected.
  Fix: Remove dependencies on external `fetch` polyfills or libraries like Axios. Review and update any custom HTTP request logic that relied on the previous client implementation to use native `fetch` patterns or the library's provided methods.
• deprecated Support for ButterCMS-JS version 2 will end in May 2025, aligning with the Node.js v18 sunset. Users are strongly encouraged to migrate to version 3 to ensure continued support and compatibility.
  Fix: Upgrade to ButterCMS-JS version 3.x.x, ensuring your Node.js environment meets the v20 requirement.
• gotcha When migrating from CommonJS (`require`) to ES Modules (`import`), developers might encounter 'ReferenceError: require is not defined in ES module scope' errors or unexpected behavior due to Node.js's module resolution differences. Version 3 is ESM-first.
  Fix: Ensure your project is configured for ES Modules (e.g., `"type": "module"` in `package.json`) and use `import Butter from 'buttercms';`. If you must use CommonJS, you might need to use dynamic imports or a transpilation step.
• gotcha To fetch unpublished or draft content, you must explicitly enable `testMode` during client initialization. Failing to do so will result in only published content being returned.
  Fix: Initialize the client with `const butter = Butter("your_api_token", { testMode: true });` or use an environment variable like `process.env.BUTTER_PREVIEW_MODE` to control it dynamically.

Install

• npm install buttercms npm
• yarn add buttercms yarn
• pnpm add buttercms pnpm

Imports

• Butter
  wrong:

  const Butter = require('buttercms');

  correct:

  import Butter from 'buttercms';

  Since v3.0.0, the package is primarily designed for ES Modules. Using `require()` will likely lead to errors in ES Module contexts.
• Butter (browser global)

  <script src="https://cdn.jsdelivr.net/npm/buttercms@3.0.3/dist/butter.min.js"></script>
  <script>
    const butter = Butter("your_api_token");
  </script>

  When included via CDN, the `Butter` object is available globally in the browser.
• ButterClient
  wrong:

  import { Butter } from 'buttercms'; // Incorrect named import for the default export

  correct:

  import Butter, { ButterClient } from 'buttercms';
  const butter: ButterClient = Butter(apiToken);

  The main `Butter` function is a default export. `ButterClient` is a type definition for the client instance, useful for explicit type annotations in TypeScript.

Quickstart

This quickstart initializes the ButterCMS client and demonstrates fetching blog posts, a specific page, and content from a collection using async/await.

import Butter from "buttercms";

// Initialize ButterCMS client with your API token.
// It's highly recommended to use environment variables for API tokens.
const BUTTER_API_TOKEN = process.env.BUTTER_API_TOKEN ?? 'YOUR_SECRET_API_TOKEN_HERE';
const butter = Butter(BUTTER_API_TOKEN, {
  // Enable testMode for previewing unpublished content in development or staging.
  testMode: process.env.NODE_ENV === 'development' || process.env.BUTTER_PREVIEW_MODE === 'true'
});

async function fetchButterCMSContent() {
  try {
    // Fetch a list of blog posts
    const postsResponse = await butter.post.list({ page: 1, page_size: 5 });
    console.log("Latest Blog Posts:", postsResponse.data.data.map(p => p.title));

    // Fetch a specific page by type and slug, e.g., 'about-us' page with slug 'company-overview'
    const pageResponse = await butter.page.retrieve("about-us", "company-overview");
    console.log(`Page 'about-us/company-overview' SEO Title:`, pageResponse.data.data.seo.title);

    // Fetch content from a collection, e.g., 'faq' collection
    const collectionResponse = await butter.content.retrieve(['faq'], { locale: 'en' });
    console.log(`First FAQ item from 'faq' collection:`, collectionResponse.data.data.faq[0].question);

  } catch (error) {
    console.error("Failed to fetch ButterCMS content:", error);
    if (error instanceof Error) {
        console.error("Error details:", error.message);
    }
  }
}

fetchButterCMSContent();