Introduction

Getting Started

This guide walks you through setting up brease-next in a Next.js 15 project.

Step 1: Install the Package

Install brease-next via npm:

npm install brease-next

The package requires Next.js 15+ and React 19+. Ensure your package.json has compatible versions:

{
  "dependencies": {
    "brease-next": "^0.1.0",
    "next": "15.5.4",
    "react": "19.1.0",
    "react-dom": "19.1.0"
  },
  "devDependencies": {
    "@types/node": "^20",
    "@types/react": "^19",
    "@types/react-dom": "^19",
    "typescript": "^5"
  }
}

Step 2: Configure Environment Variables

Create a .env.local file in your project root with the following variables:

BREASE_BASE_URL=https://api.brease.io/v1
BREASE_TOKEN=your_brease_api_token
BREASE_ENV=your_environment_id
BREASE_REVALIDATION_TIME=30

Environment Variables Explained

  • BREASE_BASE_URL: The base URL for the Brease API (typically https://api.brease.io/v1)
  • BREASE_TOKEN: Your Brease API authentication token (obtain from Brease dashboard)
  • BREASE_ENV: Your Brease environment identifier (e.g., prod, staging, or UUID)
  • BREASE_REVALIDATION_TIME: Cache revalidation time in seconds (default: 30)

Step 3: Configure Next.js

Update your next.config.ts (or next.config.js) to support Brease features:

import type { NextConfig } from "next";
import { fetchRedirects, type BreaseRedirect } from "brease-next/server";

const nextConfig: NextConfig = {
  // Configure remote image patterns for Brease media
  images: {
    remotePatterns: [
      {
        protocol: 'https',
        hostname: 's3.eu-central-1.amazonaws.com',
        pathname: '/**',
      }
    ]
  },

  // Fetch redirects from Brease at build time
  async redirects() {
    const result = await fetchRedirects();

    if (!result.success) {
      console.error('Failed to fetch redirects:', result.error);
      return [];
    }

    return result.data.map((redirect: BreaseRedirect) => {
      return {
        source: redirect.source,
        destination: redirect.destination,
        permanent: (redirect.type === '301' || redirect.type === '308'),
      }
    })
  }
};

export default nextConfig;

Configuration Explained

Remote Images

The images.remotePatterns configuration allows Next.js Image component to load images from Brease's S3 bucket. Update the hostname if your Brease instance uses a different storage provider.

Dynamic Redirects

The redirects() function fetches redirect rules from Brease at build time. This allows content editors to manage redirects through the CMS.

CORS Headers

CORS headers enable the Brease editor's preview functionality. Adjust the allowed origins based on your Brease instance and deployment platform.

Step 4: Create Configuration File

Create a file to configure section mapping and context data:

// src/lib/brease-config.ts
import { ComponentType } from 'react';
import {SectionElementProps} from "brease-next";

export const sectionMap = {
  sampleSection: SampleSection as unknown as ComponentType<SectionElementProps>,
  ...
};

// Context configuration for navigations and collections
export const contextData = {
  navigations: [
    // Add your navigation UUIDs
    // { key: 'mainNavigation', id: 'nav-uuid-here' },
  ],
  collections: [
    // Add your collection UUIDs
    // { key: 'news', id: 'col-uuid-here' },
  ],
};

This configuration will be populated as you build your application (see Implementation Guide).

Step 5: Set Up Root Layout

Wrap your application with BreaseContext in your root layout:

// src/app/layout.tsx
import type { Metadata } from "next";
import { BreaseContext } from "brease-next";
import { contextData } from "@/lib/brease-config";
import "./globals.css";

export const metadata: Metadata = {
  title: "My Brease Site",
  description: "Powered by Brease CMS",
};

export default function RootLayout({
  children,
}: {
  children: React.ReactNode;
}) {
  return (
    <html lang="en">
      <body>
        <BreaseContext config={contextData}>
          {children}
        </BreaseContext>
      </body>
    </html>
  );
}

The BreaseContext component makes navigation and collection data available throughout your application via the useBrease() hook.

Configuration Checklist

  • Installed brease-next package
  • Created .env.local with Brease credentials
  • Updated tsconfig.json with proper compiler options
  • Updated next.config.ts with remote images, redirects, and CORS
  • Created src/lib/brease-config.ts with section map and context data
  • Wrapped app with BreaseContext in root layout
  • Verified environment variables are loaded

Troubleshooting Setup

Import errors

If you see module resolution errors, ensure:

  • brease-next is installed: npm list brease-next
  • Your TypeScript config has moduleResolution: "bundler"

Environment variable issues

If API calls fail, verify:

  • .env.local exists in project root
  • All required variables are set
  • Development server was restarted after adding variables

Image loading issues

If Brease images don't load:

  • Check next.config.ts has correct remotePatterns
  • Verify the hostname matches your Brease media storage
  • Check browser console for CORS errors

Next Steps

Now that your project is configured, proceed to:

Previous
Prologue
Next
API Reference