Author: Likem Dunyo

Introduction

Django is a powerful backend framework, and React is a go-to for dynamic frontends. Combining the two creates a robust full-stack experience, but how you combine them matters. Many teams start by embedding React into Django templates, using Django to serve HTML and React's JS bundle. While this works well for small apps or rapid prototyping, this tight coupling becomes an obstacle as your app grows. Navigation logic gets tangled between Django and React. CI/CD pipelines clash. And worse, your frontend isn’t truly “frontend-first.”

In this post, we’ll walk through how we, at Bruce, decoupled our application into a standalone React SPA and Django API, using Clerk for modern, drop-in authentication.

The Coupled State: Django Rendering React

In many Django + React projects, the setup starts simple:

• Django templates serve a page with a <div id=”root”></div> where React mounts, and <script src=”{% static ‘<path-to-static-js-bundled-file>’ %}”> which includes the static JS bundle built with npm run build and served via Django’s “static/” directory.

• Django handles routing and authentication.

Coupling Points

• Page Routing: Our application’s navigation was built with Django and Bootstrap. Routing in Django is handled entirely on the server side. Each navigation to a new route requires a full page reload as the server sends a new HTML document to the browser.

• Authentication and User Sessions: Authentication in our application was implemented using Django Auth. Login, Registration and Logout patterns and UI were defined by Django.

• Templating: Each route in the application had its own Django template. React components were injected into templates where required.

Why a Coupled Setup Becomes a Problem

1. Conflicting Responsibilities

When React is treated like a widget inside Django, your frontend cannot own routing, state or context. Navigation refreshes the entire page, and Django decides what users can see.

2. CI/CD Complexity

Frontend and backend are deployed as one. Want to ship a UI fix quickly? You’ll need to rebuild your Django and React apps, and update the path to the bundled JS file in the entrypoint Django template. This is a major pain point in deployment as it slows deployment down and negatively affects the development experience.

3. Performance and User Experience

Full page reloads for every route slows navigation down and harms the overall user experience. Additionally, a coupled app takes the choice of using offline-first or PWA capabilities away from the developer.

Decoupling React from Django

The goal of the decoupling process was to make React the self-contained frontend app, and Django the headless API backend. The following steps outlined what we did to achieve that.

1. Replace Django Auth with Clerk

The authentication system of our application was rebuilt with Clerk. New pages for Registration and Login were built with React and Clerk’s SignIn and SignUp pre-built React components. 

In the backend Django’s session middleware was removed, and each API request’s authorization token was verified using Clerk JWT verification method. For more on how to integrate clerk with Django backend this post is very helpful.

2. Update API Calls in React

Make API requests to Django endpoints with Clerk JWT attached. Clerk uses short-lived tokens, therefore we retrieve a new JWT in Axios’ request interceptor to make sure we attach a valid token to each API request.

3. Migrate routing to react

To migrate routing to React we rebuilt our navigation component, utilizing the NavLink component from react-router-dom for each navigation item. Now all navigation is handled client-side, and Django only serves data through APIs.

Benefits of Decoupling

• Frontend and backend can be deployed independently

• React controls UI, state, routing, and performance optimizations

• Faster UI updates and better CI/CD

• Clear separation of concerns (SPA + API)

Conclusion

Decoupling your Django + React app isn’t just about separating files, it’s about unlocking the full potential of both frameworks. By:

• Moving navigation and state to React

• Replacing Django’s template/rendering system with a pure API layer

...you’re building toward a modern, scalable and developer-friendly architecture.

If you’re starting a project now, this separation is essential. If you're working on an existing codebase, it’s worth considering a refactor.

Likem Dunyo worked at Bruce as a Summer 2025 Software Engineering Intern. You can connect with him on LinkedIn to follow his work and future projects.