Troubleshooting

As larger projects get more complex, it can be hard to debug issues. Django Components provides a number of tools and approaches that can help you with that.

Component and slot highlighting¤

Django Components provides a visual debugging feature that helps you understand the structure and boundaries of your components and slots. When enabled, it adds a colored border and a label around each component and slot on your rendered page.

To enable component and slot highlighting, set debug_highlight_components and/or debug_highlight_slots to True in your settings.py file:

from django_components import ComponentsSettings

COMPONENTS = ComponentsSettings(
    debug_highlight_components=True,
    debug_highlight_slots=True,
)

Components will be highlighted with a blue border and label:

While the slots will be highlighted with a red border and label:

Component path in errors¤

When an error occurs, the error message will show the path to the component that caused the error. E.g.

KeyError: "An error occured while rendering components MyPage > MyLayout > MyComponent > Childomponent(slot:content)

The error message contains also the slot paths, so if you have a template like this:

{% component "my_page" %}
    {% slot "content" %}
        {% component "table" %}
            {% slot "header" %}
                {% component "table_header" %}
                    ...  {# ERROR HERE #}
                {% endcomponent %}
            {% endslot %}
        {% endcomponent %}
    {% endslot %}
{% endcomponent %}

Then the error message will show the path to the component that caused the error:

KeyError: "An error occured while rendering components my_page > layout > layout(slot:content) > my_page(slot:content) > table > table(slot:header) > table_header > table_header(slot:content)

Debug and trace logging¤

Django components supports logging with Django.

To configure logging for Django components, set the django_components logger in LOGGING in settings.py (below).

Also see the settings.py file in sampleproject for a real-life example.

import logging
import sys

LOGGING = {
    'version': 1,
    'disable_existing_loggers': False,
    "handlers": {
        "console": {
            'class': 'logging.StreamHandler',
            'stream': sys.stdout,
        },
    },
    "loggers": {
        "django_components": {
            "level": logging.DEBUG,
            "handlers": ["console"],
        },
    },
}

LOGGING = {
    "loggers": {
        "django_components": {
            "level": 5,
            "handlers": ["console"],
        },
    },
}

Logger levels¤

As of v0.126, django-components primarily uses these logger levels:

• DEBUG: Report on loading associated HTML / JS / CSS files, autodiscovery, etc.
• TRACE: Detailed interaction of components and slots. Logs when template tags, components, and slots are started / ended rendering, and when a slot is filled.

Slot origin¤

When you pass a slot fill to a Component, the component and slot names is remebered on the slot object.

Thus, you can check where a slot was filled from by printing it out:

class MyComponent(Component):
    def on_render_before(self):
        print(self.input.slots)

might print:

{
    'content': <Slot component_name='layout' slot_name='content'>,
    'header': <Slot component_name='my_page' slot_name='header'>,
    'left_panel': <Slot component_name='layout' slot_name='left_panel'>,
}

Agentic debugging¤

All the features above make django-components to work really well with coding AI agents like Github Copilot or CursorAI.

To debug component rendering with LLMs, you want to provide the LLM with:

1. The components source code
2. The rendered output
3. As much additional context as possible

Your codebase already contains the components source code, but not the latter two.

Providing rendered output¤

To provide the LLM with the rendered output, you can simply export the rendered output to a file.

rendered = ProjectPage.render(...)
with open("result.html", "w") as f:
    f.write(rendered)

If you're using render_to_response, access the output from the HttpResponse object:

response = ProjectPage.render_to_response(...)
with open("result.html", "wb") as f:
    f.write(response.content)

Providing contextual logs¤

Next, we provide the agent with info on HOW we got the result that we have. We do so by providing the agent with the trace-level logs.

In your settings.py, configure the trace-level logs to be written to the django_components.log file:

LOGGING = {
    "version": 1,
    "disable_existing_loggers": False,
    "handlers": {
        "file": {
            "class": "logging.FileHandler",
            "filename": "django_components.log",
            "mode": "w",  # Overwrite the file each time
        },
    },
    "loggers": {
        "django_components": {
            "level": 5,
            "handlers": ["file"],
        },
    },
}

Prompting the agent¤

Now, you can prompt the agent and include the trace log and the rendered output to guide the agent with debugging.

I have a django-components (DJC) project. DJC is like if Vue or React component-based web development but made for Django ecosystem.

In the view project_view, I am rendering the ProjectPage component. However, the output is not as expected. The output is missing the tabs.

You have access to the full log trace in django_components.log.

You can also see the rendered output in result.html.

With this information, help me debug the issue.

First, tell me what kind of info you would be looking for in the logs, and why (how it relates to understanding the cause of the bug).

Then tell me if that info was there, and what the implications are.

Finally, tell me what you would do to fix the issue.