Debug Logging in Content SDK Apps — A Developer’s Guide

When building headless applications with Sitecore Content SDK, debugging becomes crucial especially as your component structure and data dependencies grow. Instead of writing console.log everywhere, the Content SDK provides a much cleaner and controlled approach to logging.

The SDK uses the popular debug module for displaying debugging information. This allows developers to enable or disable logging dynamically using environment variables, making it easier to troubleshoot issues without modifying code.

Debug logging is disabled by default, keeping terminal noise to a minimum during normal development. Once you need insights into what the Content SDK is doing—just turn it on!

Enabling Debug Logs

  1. Use the DEBUG environment variable to control what logs are shown.
  2. When logging is enabled and you run your application, all triggered instances of debug() relevant to the namespaces you choose to include will be displayed in your console.
  3. To enable all logs, set the DEBUG environment variable to content-sdk:* DEBUG=content-sdk:*
  4. To enable specific namespaces only, set the DEBUG environment variable like DEBUG=content-sdk:layout

to only log layout-service-related debug messages.

  1. To enable multiple namespaces, You can also combine multiple namespaces like DEBUG=content-sdk:layout,content-sdk:dictionary
  2. Or exclude some namespaces like DEBUG=content-sdk:*,-content-sdk:layout This shows all except layout logs.

Namespaces / Categories

The Content SDK defines a set of namespaces for debug logs. Some of the key ones:

Namespace

What It Logs

content-sdk:http

HTTP request/response logging (for the fetch / request wrappers)

content-sdk:dictionary

Logs from the dictionary (localization) service

content-sdk:layout

Layout service logs (how pages/components are fetched)

content-sdk:editing

Logs related to the SitecoreAI editor (preview / editing integration)

content-sdk:sitemap

Logs from the sitemap service

content-sdk:robots

For robots.txt service

content-sdk:redirects

For redirect service / middleware in Next.js

content-sdk:errorpages

Error-page service logs

content-sdk:multisite

Multi-site service & Next.js multisite middleware

content-sdk:personalize

Personalization / A-B test service logs

content-sdk:common

Common messages across SDK

Advanced / Optional Debug Config

There are additional environment variables to tweak how debug output looks

Env Variable

Description

DEBUG_HIDE_DATE

Whether to hide timestamps in debug logs (especially for non-TTY). Default: false

DEBUG_COLORS

Enable/disable colored output. Default: true

DEBUG_DEPTH

Controls how deeply nested objects are inspected when logging. Default: 2

DEBUG_MULTILINE

Whether to pretty-print objects on multiple lines. Default: false

DEBUG_SHOW_HIDDEN

Whether to show hidden properties in objects. Default: false

Scope / When It Works

    • Debug logs are only for server-side code. According to the official docs, they don’t apply in the browser / client-side.
    • When you run production builds (or use npm run start:production), you can still enable debug logging by setting the DEBUG env var accordingly.

 Why Use Debug Logging in Content SDK

  • Troubleshooting: Useful to trace what GraphQL / layout queries are being made, and how the client is handling them.
  • Performance Analysis: Check HTTP request / response payloads and timings.
  • Debugging Middleware: If you have custom middleware (editing host, personalization, sitemap) — logs help you understand internal behavior.
  • Selective Logging: You don’t need to flood your logs. You can target specific areas (layout, dictionary, HTTP) using namespaces.

 Example Usage - To debug layout + dictionary:

  • Add to .env.local: DEBUG=content-sdk:layout,content-sdk:dictionary
  • Run the app: npm run dev
  • For production: DEBUG=content-sdk:layout,content-sdk:dictionary npm run start:production

Happy Coding!

 


Comments

Post a Comment

Popular posts from this blog

Migrating from Sitecore JSS SDK to Content SDK – Best Practices and Pitfalls

Image
The Sitecore JSS SDK has been a staple for building modern headless websites with XM Cloud and Sitecore XP. It offers deep integration with the Sitecore Layout Service, letting frontend developers render content directly based on Sitecore-managed components. Now, with the introduction of the Sitecore Content SDK, teams have a lightweight, REST-first way to fetch clean JSON data, leaving rendering entirely to the frontend. For projects focused on performance, composable architectures, or custom rendering logic, the Content SDK can be a compelling choice. If you’re considering a switch from JSS SDK to Content SDK, this guide walks you through how to migrate, best practices, and the pitfalls to avoid. Why Migrate to Content SDK? Lightweight: No dependency on Layout Service rendering. Faster payloads: Returns only the requested fields, reducing over-fetching. Flexible rendering: Total control of frontend presentation. Better for static generation: Idea...
Read more

Beginner’s Guide: Step-by-Step Local Installation for Sitecore XM Cloud

Image
Many times, we want to accomplish a task but aren’t sure where to start—the same applies to Sitecore XM Cloud local setup and installation. In this guide, I’ll Walk you through the process of setting up a Sitecore XM Cloud environment locally, step by step. Sitecore XM Cloud is the cloud-native, headless version of Sitecore Experience Manager (XM), designed for modern, omnichannel digital experiences. It separates content management (authoring) from content delivery, enabling fast, API-driven, and scalable architectures. Developers can deliver content to web, mobile, and other channels via GraphQL APIs and Experience Edge, while content authors manage items in a cloud-first environment. Even though XM Cloud is cloud-first, a local environment is essential for: Experimenting safely with content, templates, and workflows. Testing headless frontends like Angular, React, or Next.js. Debugging GraphQL queries and APIs efficiently. Validating scheduled tasks...
Read more

Setting Up Sitecore Headless with Next.js in Disconnected Mode

Image
Sitecore Headless CMS offers a flexible way to integrate with different frontend technologies. For developers working with frameworks like Next.js, Sitecore provides various ways to set up the environment, including four distinct modes: Disconnected Mode , Connected Mode , Integrated Mode , and API Mode . Each mode offers unique features for different stages of development and production needs. What Is Disconnected Mode? Disconnected Mode is designed for local development and testing without requiring a direct connection to the Sitecore platform. In this mode, data is typically retrieved from static files (like YAML or JSON), and content updates are done manually. This mode is ideal for frontend developers who want to focus on building the user interface and the site’s functionality without waiting for backend integration. In Disconnected Mode , the data flow is not dependent on the Sitecore CMS. Instead, content is stored locally in static files, which are easier to manage and qu...
Read more