Resources

Troubleshooting

Common issues and solutions when using brease-next package.

Installation & Setup Issues

Issue: Cannot find module 'brease-next'

Symptoms:

  • Error: Cannot find module 'brease-next'
  • TypeScript errors for brease-next imports

Solutions:

  1. Install the package:

    npm install brease-next

  2. Verify installation:

    npm list brease-next

  3. Restart development server:

    # Stop the dev server (Ctrl+C)
npm run dev

  4. Clear cache if needed:

    rm -rf node_modules package-lock.json
npm install

Issue: TypeScript path alias not working

Symptoms:

  • Error: Cannot find module '@/lib/brease-config'
  • Import errors for @/ paths

Solutions:

  1. Verify tsconfig.json:

    {
  "compilerOptions": {
    "paths": {
      "@/*": ["./src/*"]
    }
  }
}

  2. Restart TypeScript server in your IDE:

    • VS Code: Cmd+Shift+P → "TypeScript: Restart TS Server"

Environment & Configuration Issues

Issue: Environment variables not loading

Symptoms:

  • Error: Failed to fetch from : Unauthorized
  • Empty or undefined environment variables

Solutions:

  1. Check file naming:

    • Use .env.local for local development
    • Use .env.production for production builds
    • Never commit .env.local to version control

  2. Verify variable names (note: BREASE_DEFAULT_LOCALE is required):

    BREASE_TOKEN=your_token_here
BREASE_ENV=your_environment_id
BREASE_DEFAULT_LOCALE=en
BREASE_REVALIDATION_TIME=30

  3. Restart development server:

    # Stop the dev server (Ctrl+C)
npm run dev

  4. Check Next.js environment variable access:

    • Only variables prefixed with NEXT_PUBLIC_ are available in client components
    • Server-side variables (without prefix) are only available in server components and API routes

Issue: Config not found in context

Symptoms:

  • Error: Cannot read properties of undefined (reading 'navigations')
  • Context data is undefined

Solutions:

  1. Verify contextData is configured:

    // src/lib/brease-config.ts
export const contextData = {
  navigations: [{ key: 'mainNavigation', id: 'nav-uuid...' }],
  collections: [{ key: 'news', id: 'col-uuid...' }],
}

  2. Check BreaseContext receives config and slug:

    // src/app/[[...slug]]/layout.tsx
import { BreaseContext } from 'brease-next';
import { contextData } from '@/lib/brease/config';

<BreaseContext config={contextData} slug={slugStr}>
  {children}
</BreaseContext>

API & Data Fetching Issues

Issue: 401 Unauthorized error

Symptoms:

  • Error: Failed to fetch from https://...: Unauthorized
  • Status: 401

Solutions:

  1. Verify token is correct:

    • Check Brease dashboard for valid API token
    • Ensure token has proper permissions

  2. Check token format:

    BREASE_TOKEN=your_actual_token  # No quotes or extra spaces

  3. Verify Authorization header in brease-next package:

    • The package automatically adds Bearer prefix
    • Ensure BREASE_TOKEN environment variable is set

Issue: 404 Not Found for pages

Symptoms:

  • Pages return 404 in production
  • result.status === 404 from fetchPage()

Solutions:

  1. Verify page exists in Brease:

    • Check Brease dashboard
    • Ensure page exists
    • Verify slug matches exactly (case-sensitive)

  2. Check environment:

    • Ensure BREASE_ENV matches the environment where pages are published

Issue: Stale content / cache not updating

Symptoms:

  • Changes in Brease don't appear on site
  • Content updates slowly or not at all

Solutions:

  1. Check revalidation time:

    BREASE_REVALIDATION_TIME=30  # Seconds

  2. Force revalidation in development:

    rm -rf .next
npm run dev

  3. For production, use Next.js revalidation:

    // In page component
export const revalidate = 30 // Seconds

Issue: Collection entries not found

Symptoms:

  • Error: Failed to load collection entry
  • Empty collection results

Solutions:

  1. Verify collection ID in config:

    // src/lib/brease-config.ts
export const contextData = {
  navigations: [],
  collections: [
    { key: 'news', id: 'col-a01c8223-4e4a-40aa-90d9-70149e87322c' },
  ],
}

  2. Verify entries are published:

    • Check Brease dashboard
    • Ensure collection has published entries

Build & Deployment Issues

Issue: Build fails with "Failed to fetch pages"

Symptoms:

  • Build error during generateStaticParams()
  • Error: Failed to fetch pages for static generation

Solutions:

  1. Check environment variables in build environment:

    • Vercel: Add variables in Project Settings → Environment Variables
    • Ensure variables are available for "Production" environment

  2. Verify network access:

    • Ensure build environment can access Brease API
    • Check firewall rules

  3. Add error handling:

    export async function generateStaticParams() {
  const result = await generateBreasePageParams()

  if (!result || result.length === 0) {
    console.warn('No pages found, returning empty params')
    return []
  }

  return result
}

Issue: Redirects not working

Symptoms:

  • Redirects from Brease don't work on site
  • Build logs show "Failed to fetch redirects"

Solutions:

  1. Check import in next.config.ts:

    // Correct:
import { fetchRedirects } from 'brease-next/server'

// Incorrect (old approach):
import { fetchRedirects } from '@/brease/server'

  2. Verify redirect format in Brease:

    • Source: /old-page
    • Destination: /new-page
    • Both should include leading slashes

  3. Check build output:

    npm run build
# Look for "Redirects" section in output

Issue: Images not loading in production

Symptoms:

  • Images work locally but not in production
  • Error: Invalid src prop

Solutions:

  1. Verify remote patterns in next.config.ts:

    images: {
  remotePatterns: [
    {
      protocol: 'https',
      hostname: 'assets.brease.io',
      pathname: '/**',
    },
  ]
}

  2. Check image URLs from Brease:

    console.log('Image path:', breaseImage.path)
// Should be full URL starting with https://assets.brease.io/

Component & Rendering Issues

Issue: Section not rendering

Symptoms:

  • Console warning: No component found for section type: {type}
  • Section missing from page

Solutions:

  1. Check section map — keys must match the section key in Brease:

    // In brease-config.ts
export const sectionMap = {
  hero: HeroSection, // Key must match Brease section key exactly
}

  2. Verify section key in Brease:

    • Check the Editor in the CMS dashboard
    • The section key (not name) is what maps to sectionMap
    • Keys are case-sensitive

  3. Add section to map:

    import NewSection from '@/sections/new-section'

export const sectionMap = {
  // ... existing sections
  newSection: NewSection, // Add new section
}

Issue: Rich text content not rendering

Symptoms:

  • HTML shows as plain text
  • Tags visible on page

Solutions:

  1. Use dangerouslySetInnerHTML:

    // Correct:
<div dangerouslySetInnerHTML={{ __html: body }} />

// Incorrect:
<div>{body}</div>  // Renders as plain text

  2. Add CSS for rich text (optional):

    <div
  className="prose prose-lg"  // Tailwind Typography
  dangerouslySetInnerHTML={{ __html: content }}
/>

Context & Hook Issues

Issue: "useBrease must be used within a BreaseContext"

Symptoms:

  • Runtime error when using useBrease() hook
  • App crashes on load

Solutions:

  1. Verify BreaseContext wraps app:

    // In src/app/layout.tsx
import { BreaseContext } from 'brease-next';
import { contextData } from '@/lib/brease-config';

export default function RootLayout({ children }) {
  return (
    <html>
      <body>
        <BreaseContext config={contextData}>
          {children}
        </BreaseContext>
      </body>
    </html>
  );
}

  2. Check component is client component:

    'use client' // Must be at top of file

import { useBrease } from 'brease-next'

Issue: Cannot destructure navigation from useBrease

Symptoms:

  • Error: Cannot read property 'mainNavigation' of undefined
  • Navigation data not accessible

Solutions:

  1. Use new destructuring pattern:

    // Correct (new pattern):
const { navigations } = useBrease()
const { mainNavigation } = navigations

// Incorrect (old pattern):
const { navigation } = useBrease()

  2. Check for undefined:

    const { navigations } = useBrease()
const { mainNavigation } = navigations

if (!mainNavigation) {
  return null // Or loading state
}

  3. Verify key matches config:

    // Config:
export const contextData = {
  navigations: [
    { key: 'mainNavigation', id: 'nav-...' }, // Key here
  ],
}

// Usage:
const { mainNavigation } = navigations // Must match key

Type & TypeScript Issues

Issue: Type errors with section props

Symptoms:

  • TypeScript error: Property 'title' does not exist
  • Section component has type errors

Solutions:

  1. Define proper interface:

    import type { BreaseMedia } from 'brease-next'

interface HeroSectionProps {
  title: string
  body: string
  heroMedia: BreaseMedia
}

export default function HeroSection({
  title,
  body,
  heroMedia,
}: HeroSectionProps) {
  // ...
}

  2. Make fields optional if they might not exist:

    interface HeroSectionProps {
  title: string
  subtitle?: string // Optional
  heroMedia?: BreaseMedia // Optional
}

Issue: Collection element type errors

Symptoms:

  • Error: Type 'unknown' is not assignable to...
  • Can't access collection entry fields

Solutions:

  1. Cast collection elements:

    const title = entry.elements.title as string
const content = entry.elements.content as string
const image = entry.elements.featuredImage as BreaseMedia

  2. Create type for collection:

    interface BlogPostElements {
  title: string
  content: string
  excerpt: string
  featuredImage: BreaseMedia
  publishedAt: string
}

// Use in component:
const elements = entry.elements as unknown as BlogPostElements
const title = elements.title

Image & Media Issues

Issue: Images not optimized

Symptoms:

  • Large image file sizes
  • Slow page load times

Solutions:

  1. Use BreaseImage component:

    import { BreaseImage } from 'brease-next';

<BreaseImage breaseImage={media} />  // Automatically optimized

  2. Add responsive sizes:

    <Image
  src={media.path}
  alt={media.alt}
  width={media.width}
  height={media.height}
  sizes="(max-width: 768px) 100vw, (max-width: 1200px) 50vw, 33vw"
/>

  3. Use priority for above-fold images:

    <Image
  src={media.path}
  alt={media.alt}
  width={media.width}
  height={media.height}
  priority  // Loads immediately
/>

Issue: Missing alt text warning

Symptoms:

  • Console warning: Image elements must have an alt prop

Solutions:

  1. BreaseImage handles this automatically:

    // Fallback chain: breaseImage.alt → breaseImage.name → 'Image alt.'
<BreaseImage breaseImage={media} />

  2. For custom Image usage:

    <Image
  src={media.path}
  alt={media.alt || media.name || 'Descriptive alt text'}
  width={media.width}
  height={media.height}
/>

Symptoms:

  • Navigation items don't link anywhere
  • Clicking navigation does nothing

Solutions:

  1. Use BreaseLink component — handles internal/external links automatically:

    import { BreaseLink } from 'brease-next'

{mainNavigation.items.map((item) => (
  <BreaseLink key={item.uuid} linkData={item}>
    {item.label}
  </BreaseLink>
))}

  2. Verify navigation UUID in config:

    // In brease-config.ts
export const contextData = {
  navigations: [{ key: 'mainNavigation', id: 'nav-correct-uuid-here' }],
}

Issue: 404 on refresh for dynamic routes

Symptoms:

  • Pages work when navigating via Link
  • Pages 404 when refreshing or direct URL access

Solutions:

  1. Ensure generateStaticParams is called:

    export async function generateStaticParams() {
  return generateBreasePageParams()
}

  2. Check build output:

    npm run build
# Look for list of generated static pages

  3. Use catch-all route [[...slug]] instead of [subpageSlug]:

    src/app/
└── [[...slug]]/
    ├── layout.tsx  # BreaseContext wrapper
    └── page.tsx    # Page rendering

Performance Issues

Issue: Slow page loads

Symptoms:

  • Pages take long to load
  • High Time to First Byte (TTFB)

Solutions:

  1. Implement static generation:

    export const dynamic = 'force-static'
export async function generateStaticParams() {
  return generateBreasePageParams()
}

  2. Reduce revalidation time:

    BREASE_REVALIDATION_TIME=3600  # 1 hour instead of 30 seconds

  3. Optimize images:

    • Use BreaseImage component
    • Add appropriate sizes
    • Use priority for above-fold images

Issue: Large bundle size

Symptoms:

  • Slow initial page load
  • Large JavaScript download

Solutions:

  1. Use dynamic imports for heavy components:

    import dynamic from 'next/dynamic';

const HeavySection = dynamic(() => import('@/sections/heavy-section'), {
  loading: () => <div>Loading...</div>,
});

  2. Check client components:

    • Only use 'use client' when necessary
    • Keep server components when possible

  3. Analyze bundle:

    npm install @next/bundle-analyzer
# Configure in next.config.ts

Debugging Tips

Enable verbose logging

Add logging to track data flow:

export default async function Page() {
  const result = await fetchPage('/about')

  console.log('Fetch result:', {
    success: result.success,
    status: result.status,
    ...(result.success ? { pageData: result.data } : { error: result.error }),
  })

  // ... rest of component
}

Check build output

Build output shows useful information:

npm run build

# Look for:
# - List of generated static pages
# - Redirects
# - Image optimization info
# - Route segments

Use React DevTools

Install React DevTools to inspect:

  • Component props
  • Context values
  • Render performance

Network tab

Check browser Network tab:

  • Verify API calls succeed
  • Check response data
  • Monitor cache headers

Getting Help

If you're still experiencing issues:

  1. Check environment variables - Most issues stem from incorrect configuration
  2. Review error messages carefully - They often indicate the exact problem
  3. Compare with sample project - Reference the working implementation
  4. Check Brease API directly - Use tools like Postman to test API endpoints
  5. Review Next.js docs - Many issues relate to Next.js concepts, not the package

Common Gotchas

  1. Leading slashes: Always include leading slashes in slugs (/about, not about)
  2. Server vs client: Environment variables without NEXT_PUBLIC_ only work server-side
  3. Type casting: Collection elements are untyped, always cast them
  4. Client directive: 'use client' must be first line in file
  5. Case sensitivity: Section keys and slugs are case-sensitive
  6. Build cache: Delete .next folder if changes don't appear
  7. Import paths: All imports from 'brease-next' package, not local paths
  8. Context pattern: Use navigations and collections objects with destructuring

Preventive Best Practices

  1. Always check success before accessing data:

    if (!result.success) {
  // Handle error
}

  2. Use TypeScript strictly:

    • Enable strict mode in tsconfig.json
    • Define interfaces for all section props
    • Type cast collection elements

  3. Test error states:

    • Test with invalid slugs
    • Test with missing environment variables
    • Test network failures

  4. Monitor build output:

    • Check for warnings
    • Verify expected number of pages generated
    • Confirm redirects are applied

  5. Use static generation when possible:

    • Better performance
    • Better SEO
    • Reduced API load

  6. Configure context data properly:

    • Define all navigations and collections upfront
    • Use descriptive keys that match your usage
    • Verify UUIDs are correct

Locale Issues

Issue: Wrong locale content displayed

Symptoms:

  • Content shows in default locale regardless of URL
  • Locale prefix in URL is ignored

Solutions:

  1. Set BREASE_DEFAULT_LOCALE in .env.local:

    BREASE_DEFAULT_LOCALE=en

  2. Pass the full slug to BreaseContext (including locale prefix):

    const slugStr = (slug ?? []).join('/')
// For URL /sk/about-us, slugStr = "sk/about-us"
// Locale "sk" is auto-derived from the first segment
<BreaseContext config={contextData} slug={slugStr}>

  3. Ensure locales are active in the CMS environment settings.

Issue: Language switcher shows no locales

Symptoms:

  • availableLocales from useBrease() is empty
  • Language switcher renders nothing

Solutions:

  1. Check the CMS: ensure multiple locales are added and active in the environment.
  2. Verify fetchLocales() works: test directly in a server component.
  3. Check console for errors: BreaseContext logs Failed to load locales if the fetch fails.

Preview Mode Issues

Issue: Preview iframe is blank or blocked

Symptoms:

  • CMS preview shows empty iframe
  • Browser console shows CSP/framing errors

Solutions:

  1. Add CSP headers in next.config.ts:

    async headers() {
  return [{
    source: '/:path*',
    headers: [{
      key: 'Content-Security-Policy',
      value: "frame-ancestors 'self' https://app.brease.io https://dev.brease.io",
    }],
  }]
}

  2. Set preview domain in the CMS site settings to your deployed URL.

  3. Import toolbar styles in your root layout:

    import 'brease-next/styles'
Previous
Examples
Next
Changelog