The ButterCMS JavaScript Client (current stable v3.0.3) provides a robust interface for interacting with the ButterCMS Headless CMS API within Node.js and browser environments. It simplifies fetching various content types including blog posts, pages, collections, categories, tags, and authors. The library maintains a release cadence tied closely to Node.js LTS cycles, with version 3 supporting Node.js 20, and version 4 slated for Node.js 22. A key differentiator is its shift to native `fetch` API for HTTP requests since v2, reducing external dependencies and ensuring consistent behavior across modern JavaScript environments. It ships with comprehensive TypeScript types, enabling a smooth development experience with type-checking and autocompletion. Developers can utilize a preview mode for staging content before publishing.
npm install buttercmsVerified import paths — ran on the pinned version, not inferred.
This quickstart initializes the ButterCMS client and demonstrates fetching blog posts, a specific page, and content from a collection using async/await.
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.
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.
Upgrade to ButterCMS-JS version 3.x.x, ensuring your Node.js environment meets the v20 requirement.
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.
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.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.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`).
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`).No dependency data recorded yet.