Skip to main content

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.

For an overview of what environments are and how to request them, see Multisite Overview.

​
Environment variables

Each ButterCMS environment has its own unique API token. Configure your application to use the correct token per environment: 
# .env.development
BUTTER_API_TOKEN=dev_token_abc123

# .env.staging
BUTTER_API_TOKEN=staging_token_def456

# .env.production
BUTTER_API_TOKEN=prod_token_ghi789

​
Application code

// config/butter.js
const Butter = require('buttercms');

const butter = Butter(process.env.BUTTER_API_TOKEN);

export default butter;

​
Framework-specific examples

Next.js 
// next.config.js
module.exports = {
  env: {
    BUTTER_API_TOKEN: process.env.BUTTER_API_TOKEN,
  },
};
React (Create React App) 
// Uses REACT_APP_ prefix
const butter = Butter(process.env.REACT_APP_BUTTER_API_TOKEN);
Node.js Express 
// Load based on NODE_ENV
require('dotenv').config({
  path: `.env.${process.env.NODE_ENV}`
});
const butter = Butter(process.env.BUTTER_API_TOKEN);

​
Draft mode for staging

Add the preview=1 parameter to your API calls in the staging environment to include unpublished draft content: 
// Staging environment - include drafts
const response = await butter.page.retrieve('*', 'landing-page', {
  preview: 1
});

// Production environment - published only
const response = await butter.page.retrieve('*', 'landing-page');

​
Environment-based configuration

// utils/butter.js
const isDevelopment = process.env.NODE_ENV !== 'production';

export async function getPage(pageType, slug) {
  const params = {};

  // Include drafts in non-production environments
  if (isDevelopment) {
    params.preview = 1;
  }

  return butter.page.retrieve(pageType, slug, params);
}

​
Staging workflow

A typical staging workflow using draft mode:
  1. Create or edit content and click Save Draft (not Publish)
  2. Go to your staging site (e.g., https://staging.yoursite.com)
  3. Navigate to the specific page to preview the change
  4. Your team verifies the change looks correct on staging
  5. Once approved, publish the content to make it live in production