> ## Documentation Index
> Fetch the complete documentation index at: https://buttercms.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# JavaScript SDK
> The ButterCMS JavaScript SDK is isomorphic — use it in the browser or Node.js — with built-in TypeScript definitions for autocompletion and type safety.
## Installation
```bash theme={null}
npm install buttercms --save
```
```bash theme={null}
yarn add buttercms
```
```bash theme={null}
pnpm add buttercms
```
```html theme={null}
```
**Requirements:** Node.js version 20 or greater for server-side usage.
## Initialization
Initialize the SDK with your Read API token from the [ButterCMS Settings](https://buttercms.com/settings/).
```javascript theme={null}
import Butter from "buttercms";
const butter = Butter("your_api_token");
```
```javascript theme={null}
const Butter = require("buttercms");
const butter = Butter("your_api_token");
```
```javascript theme={null}
// After including the CDN script
const butter = Butter("your_api_token");
```
## Configuration options
You can customize the SDK behavior by passing an options object:
```javascript theme={null}
const butter = Butter("your_api_token", {
testMode: true, // Enable preview mode for draft content
timeout: 5000, // Request timeout in milliseconds (default: 3000)
cache: "only-if-cached", // Cache strategy (default: "default")
onRequest: (resource, config) => {
// Pre-request hook - modify headers or params
},
onResponse: (response, config) => {
// Post-response hook - process responses
},
onError: (errors, config) => {
// Error handling hook
}
});
```
| Option | Type | Default | Description |
| ------------ | -------- | ----------- | ------------------------------------------- |
| `testMode` | boolean | `false` | Enable preview mode to access draft content |
| `timeout` | number | `3000` | Request timeout in milliseconds |
| `cache` | string | `"default"` | Cache strategy for requests |
| `onRequest` | function | - | Hook called before each request |
| `onResponse` | function | - | Hook called after each response |
| `onError` | function | - | Hook called on errors |
## API methods
All methods return Promises and support both `.then()/.catch()` and `async/await` patterns.
### Pages
Retrieve and search pages created in the ButterCMS dashboard.
```javascript theme={null}
// Retrieve a single page
const page = await butter.page.retrieve("page_type", "page_slug", {
locale: "en",
preview: 1, // Include draft content
levels: 2 // Depth of nested references
});
console.log(page.data);
// List all pages of a type
const pages = await butter.page.list("page_type", {
page: 1,
page_size: 10,
locale: "en",
order: "-published" // Sort by published date descending
});
console.log(pages.data);
// Search pages
const results = await butter.page.search("search query", {
page: 1,
page_size: 10
});
```
### Collections
Fetch content from Collections (structured data tables).
```javascript theme={null}
// Retrieve collection content
const content = await butter.content.retrieve(["faq", "navigation"], {
locale: "en",
levels: 2
});
console.log(content.data.faq);
console.log(content.data.navigation);
```
### Blog Posts
Access the built-in Blog Engine for posts, categories, tags, and authors.
```javascript theme={null}
// List blog posts
const posts = await butter.post.list({
page: 1,
page_size: 10,
exclude_body: true, // Exclude body for faster response
category_slug: "news",
tag_slug: "featured"
});
// Retrieve a single post
const post = await butter.post.retrieve("post-slug");
console.log(post.data.title);
console.log(post.data.body);
// Search posts
const searchResults = await butter.post.search("search query", {
page: 1,
page_size: 10
});
```
### Authors
```javascript theme={null}
// List all authors
const authors = await butter.author.list({
include: "recent_posts"
});
// Retrieve a single author
const author = await butter.author.retrieve("jennifer-smith", {
include: "recent_posts"
});
```
### Categories
```javascript theme={null}
// List all categories
const categories = await butter.category.list({
include: "recent_posts"
});
// Retrieve a single category
const category = await butter.category.retrieve("news", {
include: "recent_posts"
});
```
### Tags
```javascript theme={null}
// List all tags
const tags = await butter.tag.list({
include: "recent_posts"
});
// Retrieve a single tag
const tag = await butter.tag.retrieve("featured", {
include: "recent_posts"
});
```
### Feeds
Retrieve RSS, Atom, and Sitemap feeds.
```javascript theme={null}
// Get RSS feed
const rss = await butter.feed.retrieve("rss");
// Get Atom feed
const atom = await butter.feed.retrieve("atom");
// Get Sitemap
const sitemap = await butter.feed.retrieve("sitemap");
```
## Query parameters reference
| Parameter | Applies To | Description |
| --------------- | ------------------------- | ------------------------------------- |
| `page` | Posts, Pages | Page number for pagination |
| `page_size` | Posts, Pages | Number of items per page |
| `exclude_body` | Posts | Exclude post body for faster response |
| `author_slug` | Posts | Filter posts by author |
| `category_slug` | Posts | Filter posts by category |
| `tag_slug` | Posts | Filter posts by tag |
| `include` | Authors, Categories, Tags | Include `recent_posts` with response |
| `locale` | Pages, Collections | Locale code for localized content |
| `preview` | Pages | Set to `1` to include draft content |
| `levels` | Pages | Depth of nested references (1–3) |
## Request cancellation
Cancel pending requests when needed (useful for React cleanup):
```javascript theme={null}
// Cancel all pending post requests
butter.post.cancelRequest();
// Cancel all pending page requests
butter.page.cancelRequest();
```
## Complete example
```javascript theme={null}
import Butter from "buttercms";
const butter = Butter(process.env.BUTTER_API_TOKEN);
async function fetchHomePage() {
try {
// Fetch the home page
const page = await butter.page.retrieve("landing_page", "home", {
locale: "en"
});
// Fetch navigation from collection
const navigation = await butter.content.retrieve(["main_navigation"]);
// Fetch recent blog posts
const posts = await butter.post.list({
page: 1,
page_size: 3,
exclude_body: true
});
return {
page: page.data,
navigation: navigation.data.main_navigation,
recentPosts: posts.data
};
} catch (error) {
console.error("Error fetching content:", error);
throw error;
}
}
// Usage
fetchHomePage().then(data => {
console.log("Home page:", data.page);
console.log("Navigation:", data.navigation);
console.log("Recent posts:", data.recentPosts);
});
```
## Resources
View source code, report issues, and contribute
Package details and version history