Building a Single-Page Application (SPA) with Django Templates and Vanilla JavaScript

Overview of SPA Concepts and Django's Role

A Single-Page Application (SPA) is a web application that provides a fluid, desktop-like experience by loading a single HTML page and dynamically updating content without full page reloads. Instead of the server delivering a new HTML page for each navigation, the SPA loads data asynchronously (e.g. via AJAX/fetch) and updates the existing page’s DOM using JavaScript. As a result, after the initial page load, further interactions fetch content or data in the background and inject it into the page, giving a seamless experience to the user. This contrasts with traditional multi-page applications where each click triggers a full page refresh from the server.

In a typical modern SPA, frontend frameworks like React, Vue, or Angular handle routing and rendering on the client side, and the backend (like Django) often serves a JSON API. However, you can build an SPA using just Django templates on the server and vanilla JavaScript on the client, without using heavy frontend frameworks. In this approach, Django still plays a central role by serving the initial page (and potentially HTML fragments or JSON data on subsequent requests), while plain JavaScript in the browser manages UI updates and navigation logic. This allows you to leverage Django's robust template engine, routing, and ORM for server-side logic, and use JavaScript only for enhancing interactivity.

How Django fits in without modern frontend frameworks: Django can render templates and provide endpoints that return either HTML or JSON. The browser will use JavaScript to call these endpoints in the background (using fetch() or XHR) and then update parts of the page. Essentially, Django provides the content (either as data or pre-rendered HTML), and JavaScript injects it into the single page. This means you can still use familiar Django features (templating, forms, authentication) while achieving an SPA-like feel. The initial page served by Django may include a base layout (with placeholders/divs where content will go) and all necessary static files (JS, CSS). Once loaded, the JavaScript takes over to handle navigation and dynamic content updates.

Key SPA characteristics and their implementation in Django+Vanilla JS:

No full page reloads for navigation: Use JavaScript to intercept clicks and load new content via AJAX, updating the DOM instead of letting the browser do a full reload.
Client-side routing: Manage the browser URL and history using the History API (pushState/popState) to reflect the current "page" or state.
Dynamic rendering: Either fetch JSON data from Django and construct HTML in JS, or fetch server-rendered HTML fragments and insert them. We will explore both approaches.
State management: In a simple vanilla JS SPA, state can be managed with plain objects or global variables. There is no built-in state container as in React, so careful design is needed to keep track of what is displayed.
Initial load and SEO: The first page can be rendered by Django (ensuring something is visible and crawlable), or a loading screen that then populates content via JS. One advantage of using Django templates for content is that you can render meaningful initial HTML for better SEO, instead of a blank page that is filled in by JS only.

Next, let's set up the project structure to support this hybrid approach.

Project Structure and Setup

When building an SPA with Django and vanilla JS, you will organize your project much like a standard Django project, with the addition of dedicated static files (for JS/CSS) and possibly separate views/URLs for API endpoints or HTML fragments. A possible project structure could look like this:

myproject/
├── myproject/
│   ├── settings.py
│   ├── urls.py         # include app URLs
│   └── ... 
├── myapp/
│   ├── templates/
│   │   └── myapp/
│   │       ├── base.html          # Base template (SPA container)
│   │       ├── home.html          # Template for a section or page (optional)
│   │       └── partial_item_list.html  # Example partial template (HTML fragment)
│   ├── static/
│   │   └── myapp/
│   │       ├── js/
│   │       │   └── app.js        # Your main JavaScript for the SPA
│   │       └── css/
│   │           └── style.css     # Your CSS styles
│   ├── views.py        # Django views (normal and API/fragment views)
│   └── urls.py         # URL route definitions for this app
└── manage.py

Key points about this structure:

Templates: In myapp/templates/myapp/, base.html will act as the shell of the single-page app. It might include a navbar or other static elements, a content container <div> where dynamic content will be injected, and script tags to include the static JS. Other templates like home.html or partial_item_list.html can be used for server rendering content. For example, home.html might be a full page template for the home section (which could be directly rendered on initial load), whereas partial_item_list.html could be a fragment of HTML (e.g. a list of items) intended to be fetched via AJAX and inserted into the page. These templates are rendered by Django’s templating engine as needed.
Static Files: In myapp/static/myapp/, we keep our static assets. The JavaScript file app.js will contain all the client-side logic (routing, fetch calls, DOM updates), and style.css contains styles. By default, Django’s static file finder will collect these because we have a static directory in the app. Ensure django.contrib.staticfiles is in INSTALLED_APPS and STATIC_URL is configured (e.g. STATIC_URL = '/static/'). During development, Django's runserver will serve static files for you if DEBUG=True. In production, you'll typically use collectstatic to gather static files and serve them via a web server or CDN.
Views and URLs: The views.py will contain both the normal view(s) for rendering templates and API-like views for handling AJAX requests. For example:
- A view index that renders base.html (the main SPA container).
- A view items_list that returns JSON data (using JsonResponse) for a list of items.
- A view items_fragment that renders partial_item_list.html and returns that HTML (to be injected into the page).
- You might also have views for handling actions (like form submissions, if done via AJAX).
In urls.py, you'll map URLs to these views. For instance:
```
# myapp/urls.py
from django.urls import path
from . import views

urlpatterns = [
    path('', views.index, name='index'),                    # Serves the SPA container
    path('items/', views.items_page, name='items_page'),    # (Optional) Direct URL for items page
    path('api/items/', views.items_data, name='items_data'),       # JSON data endpoint
    path('fragment/items/', views.items_fragment, name='items_fragment'),  # HTML fragment endpoint
    # ... other routes ...
]
```
The above is an example: you might choose different URL schemes. Some developers prefer to have all AJAX endpoints under a common prefix like /api/ (for JSON) or /ajax/ (for HTML fragments) to distinguish them from normal page URLs.
Django Template Rendering vs Direct API: Depending on how you want to handle direct navigation vs AJAX, you might or might not create separate templates for full page rendering. For example, you could decide that all content is loaded via JS after the initial page; in that case, the index view returns base.html and no other page templates are needed (all other views return JSON or HTML fragments). Alternatively, you might want that if a user navigates directly to /items/ in their browser (not via AJAX), Django should still serve a valid page (perhaps rendering base.html and including the items list in it). In that case, items_page view could render base.html but with context that includes the items list, or include partial_item_list.html inside it. This hybrid approach ensures the app is usable even without JS or helps with SEO (since content can be served on initial page load), but it means some duplicate handling (one in JS, one in Django). For simplicity, our guide will assume the SPA primarily uses one initial page load and subsequent data via AJAX, but keep in mind this direct-access handling for completeness.

With the project structure in place, let's walk through specific aspects: client-side routing, dynamic content loading strategies, security (CSRF/auth), and static file management.

Routing with Vanilla JavaScript (Using the History API)

In a multi-page Django app, the server-side URLs (as defined in urls.py) determine navigation: each link click sends a new request to the server, which returns a new page. In an SPA, we want to handle navigation client-side to avoid full reloads. This means capturing user interactions (like clicking a link or a menu item) and updating the content via JavaScript, while also updating the URL in the browser so that the back/forward buttons and direct linking still work.

Intercepting Navigation Events: One common pattern is to prevent the default action of anchor (<a>) tags or buttons and call a JavaScript function instead. For example, suppose your base.html has a navigation bar:

<ul id="nav">
  <li><a href="/" data-page="home">Home</a></li>
  <li><a href="/items/" data-page="items">Items</a></li>
</ul>
<div id="content"><!-- dynamic content will be injected here --></div>

Here each link has an href (for graceful fallback) and a data-page attribute indicating what page/section it represents. We can use JavaScript to intercept clicks on these links:

document.addEventListener('DOMContentLoaded', function() {
  // Intercept clicks on nav links
  document.querySelectorAll('#nav a').forEach(link => {
    link.onclick = function(event) {
      event.preventDefault();  // Stop browser from following the link
      const page = this.dataset.page;
      loadPage(page);
    };
  });
});

In the above snippet, when a nav link is clicked, we prevent the default navigation and call loadPage(page) (you would define loadPage to handle fetching content for that page). We use data-page to decide what content to load, but one could also parse this.href or use the URL path directly.

Using the History API: The History API allows us to manipulate the browser's URL and history without a full page reload. Specifically, history.pushState(stateObj, title, url) adds a new entry to the browser’s history stack, letting us change the URL in the address bar to url and associate a state object with it. We use this after dynamically loading content so that the URL matches the current content. Likewise, we handle the window.onpopstate event to detect when the user navigates via browser back/forward buttons, so we can load the appropriate content for the state they went back to.

For example, a simple routing implementation:

function loadPage(page) {
  // Determine the URL and data source based on page identifier
  let url, fetchUrl;
  if (page === 'home') {
    url = '/';  // URL to show in address bar
    fetchUrl = '/fragment/home/';  // hypothetical endpoint for home content
  } else if (page === 'items') {
    url = '/items/'; 
    fetchUrl = '/fragment/items/';  // endpoint that returns HTML fragment or JSON for items
  } else {
    // default fallback
    url = '/';
    fetchUrl = '/fragment/home/';
  }

  // Fetch new content (assuming server returns an HTML snippet for the page)
  fetch(fetchUrl)
    .then(response => response.text())
    .then(html => {
      document.querySelector('#content').innerHTML = html;
      // Update the browser history and URL
      history.pushState({ page: page }, "", url);
    })
    .catch(err => console.error("Failed to load page", err));
}

// Handle back/forward navigation
window.onpopstate = function(event) {
  if (event.state && event.state.page) {
    // Reload the content for the previous state
    loadPage(event.state.page);
  }
};

In this code:

We map a page identifier to an AJAX URL (fetchUrl) and a browser URL (url). Here, for simplicity, we imagine endpoints /fragment/home/ and /fragment/items/ that return HTML fragments for those sections (we'll discuss such endpoints in the next section).
After successfully fetching the content, we inject it into the #content div.
We then call history.pushState({ page: page }, "", url) to add a new history entry. The state object { page: page } helps us know what page to load when the user navigates back to this state. The third argument url updates the address bar (e.g., switching it to “/items/” when items are loaded, so the user can bookmark or reload and get that page).
We also set up window.onpopstate to listen for back/forward events. When the user clicks the back button, the browser will revert to the previous history state and fire this event, passing the state object we pushed. In our handler, we check event.state.page and call loadPage for that page, ensuring the content goes back to what it was.

PushState vs. ReplaceState: Note that pushState adds a new history entry. There is also history.replaceState(state, title, url) which replaces the current history entry. You would use replaceState for example on initial load if you want to set a state without adding a new entry, or when updating state without wanting the back button to go through intermediate states. In many SPA scenarios, pushState is used for new navigations initiated by the user, so that each is recordable, whereas replaceState might be used to adjust state (e.g., after an initial page load, to store some initial state).

Defining Routes and Direct URL Access: In a larger app, you might maintain a client-side route table (mapping URL paths to functions or content loads). For our vanilla approach, a simple if/else or switch in loadPage may suffice, especially if there are not too many distinct pages. If a user directly navigates to a URL (e.g., they refresh the browser on /items/ or paste that link), by default the browser will request that from Django. If we want the app to handle that similarly, our Django view for /items/ could either:

Return the same base.html with the SPA code, and perhaps embed the initial content for "items" (so the page loads directly in the correct state).
Or redirect to the main page and let the JS load the content. But a redirect could be noticeable.

A common solution is to have Django serve the base template for any unknown route (catch-all URL dispatcher) and let the JS decide what to render based on window.location. That requires some coordination, and you might need to encode what page to show. For example, the base template's script could read the current URL and call loadPage() accordingly on initial load. This is an advanced topic, but worth noting: to support deep linking, ensure your app either server-renders those links or your JS can handle loading the correct content if the page is loaded at a given URL.

Now that we can navigate without page reloads, let's discuss how to fetch and render content dynamically.

Dynamic Content Rendering

Dynamic content is the heart of an SPA – updating parts of the page with new data or views in response to user actions or navigation. With Django and vanilla JS, there are two primary strategies:

Fetch JSON data from Django and render it using JavaScript. This treats Django views as API endpoints (returning JSON) and uses JS to construct HTML from that data.
Fetch HTML fragments rendered by Django and inject them into the DOM. This offloads the templating work to Django (server-side), and the frontend simply inserts already-made HTML into the page.

Each approach has its merits, and you can even use both in one application depending on context. We'll explore both.

Fetching JSON Data from Django and Rendering with JavaScript

In this approach, Django provides data through endpoints (often under /api/ or similar) typically using JsonResponse or Django REST Framework. The JavaScript will call these endpoints, get JSON, and then create or update HTML elements accordingly.

Django View (JSON): You can use Django's built-in JsonResponse to return JSON easily. For example, let's say we have a simple model Item and we want to display a list of items:

# views.py
from django.http import JsonResponse
from .models import Item

def items_data(request):
    # Ensure this view is restricted or sanitized as needed (e.g., require login or filter data)
    items = Item.objects.all().values('id', 'name', 'description')  # Queryset of dicts
    # Convert QuerySet to list and return as JSON
    return JsonResponse(list(items), safe=False)

This view, mapped to /api/items/ in urls.py, returns a JSON array of items, e.g.:

[
    {"id": 1, "name": "Item A", "description": "First item"},
    {"id": 2, "name": "Item B", "description": "Second item"},
    ...
]

(Note: We passed safe=False to JsonResponse because by default it expects a dict; a list is considered unsafe unless explicitly allowed.)

You could also manually build a dict if you need to include additional data or a custom structure, for example:

data = {"items": list(items)}
return JsonResponse(data)

which would return {"items": [ {...}, {...} ]}.

JavaScript Fetch and Render (JSON): On the client side, you fetch this data and then populate the DOM. For example, continuing with our items example:

function loadItems() {
  fetch("/api/items/")
    .then(response => response.json())  // parse JSON from response
    .then(data => {
      // `data` is an array of item objects
      const container = document.querySelector("#content");
      container.innerHTML = "<h2>Items</h2>";  // maybe add a header
      const list = document.createElement("ul");
      data.forEach(item => {
        const li = document.createElement("li");
        li.textContent = item.name + ": " + item.description;
        list.appendChild(li);
      });
      container.appendChild(list);
    })
    .catch(err => console.error("Failed to load items data:", err));
}

If we integrate this with our routing, we might call loadItems() inside loadPage('items') instead of fetching an HTML fragment. For instance, loadPage could detect that page === 'items' and choose to call an appropriate function that uses JSON.

This approach gives us a lot of flexibility on the frontend. We can manipulate the data, maybe store it, update pieces of it without re-fetching, etc. However, generating HTML strings or using DOM methods like above can become verbose for large templates. We can improve it by using template literals or small client-side templating techniques. For example:

.then(data => {
  const container = document.querySelector("#content");
  container.innerHTML = `<h2>Items</h2>
    <ul>
      ${ data.map(item => `<li>${item.name}: ${item.description}</li>`).join("") }
    </ul>`;
});

This uses a template string to build all list items at once. For more complex HTML, you might break it into smaller pieces or use methods to create and append nodes, depending on readability and security (beware of inserting raw data that might contain HTML - use proper escaping or textContent as in the earlier example to avoid XSS).

If your app has forms or needs to send data back to the server, you can also use JSON fetch for POST requests (e.g., sending a JSON payload to create a new object, which Django view processes and returns some JSON response). Just remember to handle CSRF tokens for unsafe HTTP methods (more on that soon).

Loading HTML Fragments Rendered by Django

This approach leans on Django’s server-side rendering for HTML. The idea is to have Django return a chunk of HTML (usually a rendered template snippet) in response to an AJAX request, and the frontend simply inserts that HTML into the page. This is conceptually simpler since Django’s templating language can handle presenting the data, and the frontend logic just swaps DOM content.

Django View (HTML fragment): We create a view that renders a template and returns it. For example, an items_fragment view:

from django.template.loader import render_to_string
from django.http import HttpResponse

def items_fragment(request):
    items = Item.objects.all()
    # Render the fragment template to a string
    html = render_to_string("myapp/partial_item_list.html", {"items": items})
    return HttpResponse(html)

Here partial_item_list.html might look like:

<!-- partial_item_list.html -->
<h2>Items</h2>
<ul>
  {% for item in items %}
    <li>{{ item.name }}: {{ item.description }}</li>
  {% endfor %}
</ul>

The view returns an HttpResponse with that HTML content. (We could also return JsonResponse({"html": html}) wrapping it in JSON, but typically just raw HTML is fine for fragments.)

Alternatively, you can use Django's render function and return it, which implicitly returns an HttpResponse. However, using render_to_string as above avoids needing an actual HttpResponse until the end, and it can be convenient if you want to possibly return JSON with multiple fragments. For simplicity, returning plain HTML works.

JavaScript Fetch and Insert (HTML): On the client, fetching and inserting this is straightforward:

function loadItemsFragment() {
  fetch("/fragment/items/")
    .then(response => response.text())  // get the response as text (HTML)
    .then(html => {
      document.querySelector("#content").innerHTML = html;
    })
    .catch(err => console.error("Failed to load items fragment:", err));
}

This replaces the #content innerHTML with whatever HTML the server produced. You can see how this approach offloads the presentation logic to Django – if you need to change how items are displayed, you can edit the Django template rather than the JS.

This pattern (server renders HTML, client inserts it) is essentially what libraries like HTMX or Turbo Frames do for you in a more structured way. But with vanilla JS, it's still quite doable. Just be cautious to only insert content from trusted sources (in this case, your own server) to avoid injecting malicious HTML. Also, large fragments might flicker if you replace big sections; you can mitigate by finer-grained updates if needed (e.g., replace a list inner HTML but not the whole page container, etc.).

Comparing the Two Approaches:

JSON + JS-rendering: More control on the client side. You can reuse data for multiple purposes (e.g., store in JS memory, filter or sort without another request). But requires writing JavaScript to create HTML, which can get complex. Good if you have interactive components or need to manipulate data before display.
HTML fragments: Less client code – just fetch and insert. Keeps the rendering logic in Django templates (which is great if you're comfortable with Django template language and want to ensure consistent rendering between full page loads and AJAX loads). However, the client cannot easily reuse the data for other purposes unless you embed it in the HTML (or fetch JSON separately). Also, if many small interactions require server round-trips to get HTML, it might be less snappy than updating the DOM directly with known data.

You can mix these methods. For example, maybe for a complex form you'd fetch an HTML form fragment. But for something like “mark notification as read” you might just send a POST and update the UI via JS without needing the server to render anything new (the server could just return success). The choice often depends on the complexity of the UI and the logic.

Example integration: In our loadPage logic earlier, we used fetchUrl that pointed to /fragment/items/ and we directly inserted HTML. We could instead decide loadPage('items') should call loadItems() which does a JSON fetch and builds the list. The decision could be based on the nature of the content:

If it's largely static content or easily represented in HTML (like a list of items, or a block of article text), fetching an HTML fragment is convenient.
If the content is something we might need to manipulate on the client (like maybe a list where we allow resorting, or filtering, or editing inline), fetching JSON might be better so we have the raw data.

In summary, Django gives us flexibility: either serve data or ready-made HTML. Both approaches still avoid a full page refresh. We’ve essentially built a mini API (for JSON or HTML) alongside our Django templates.

Next, we must address an important aspect: making sure our AJAX interactions are secure and properly authenticated, especially when modifying data.

CSRF Protection and Authentication

Whenever you make AJAX POST/PUT/DELETE requests to Django (or any state-changing request), you must handle Cross-Site Request Forgery (CSRF) protection. Django’s CSRF middleware is on by default and will prevent any POST not containing a valid token. This means that your JavaScript code needs to send the CSRF token with AJAX requests. Similarly, if your SPA needs user authentication, you’ll typically rely on Django’s session auth (cookies) or you might use a token-based scheme for API endpoints.

CSRF in Django AJAX: Django provides the CSRF token in a cookie (by default named csrftoken) for AJAX use, and in a hidden form field for regular forms. The general steps to use it in JS are:

Obtain the CSRF token. The Django docs show a helper function to read the csrftoken cookie. For example:
```
function getCookie(name) {
  let cookieValue = null;
  if (document.cookie && document.cookie !== '') {
    const cookies = document.cookie.split(';');
    for (let cookie of cookies) {
      cookie = cookie.trim();
      if (cookie.startsWith(name + '=')) {
        cookieValue = decodeURIComponent(cookie.substring(name.length + 1));
        break;
      }
    }
  }
  return cookieValue;
}
const csrftoken = getCookie('csrftoken');
```
This will retrieve the CSRF token string from the cookie. (Ensure CsrfViewMiddleware is active and you have {% csrf_token %} in some initial form or template so that the cookie is set.)

Alternatively, if CSRF_COOKIE_HTTPONLY is False (default), you can read the cookie. If it's True, you cannot read it via JS, and instead you would include a token in the page (e.g., as a JS variable or in a meta tag by rendering {{ csrf_token }} in a script tag on the page). For simplicity, using the cookie as above is common.
Send the token in request headers for AJAX. Django expects the token in a header X-CSRFToken for AJAX requests. If you're using the Fetch API, you can set this header:
```
fetch("/some/protected/url/", {
  method: "POST",
  headers: {
    "X-CSRFToken": csrftoken,          // include the token
    "Content-Type": "application/json" // or other content type as needed
  },
  body: JSON.stringify(data),
  credentials: "same-origin"          // include cookies
})
.then(response => ...)
```
The above sets the header and also credentials: "same-origin" which ensures the browser sends the session cookie along with the request (needed if you're using session authentication; by default, fetch won't send cookies unless credentials is set to "same-origin" or "include"). The Django docs illustrate using the Request API for fetch in a similar way. Many JS libraries (like jQuery, Axios) handle CSRF tokens by reading the cookie and setting the header automatically, but with vanilla fetch we handle it manually.
On the server side, ensure your view is CSRF-protected (it is by default if middleware is on). If you forget to include the token or header, Django will respond with 403 Forbidden (CSRF failed) for unsafe methods.

Session Authentication vs Token Authentication: With a monolithic Django app (backend and frontend served from the same origin), it's simplest to use Django’s session authentication:

The user logs in via a Django view (e.g., Django’s login view or a custom login). This sets a session cookie.
All subsequent AJAX requests include that session cookie (automatically, since it's same-site), and Django knows the user (request.user).
Just remember to include CSRF token for any POST/PUT/DELETE.
This way, your SPA can use Django’s @login_required on views or check request.user as usual. No extra work for auth tokens, as you rely on cookies.

If your SPA were separate from the backend (different domain or you want a more API-centric approach), you might instead use token-based auth (like JWT or token in header). In that scenario, you would:

Have the user authenticate (maybe via a login API that returns a token or sets a cookie).
Store the token (if JWT, in memory or localStorage carefully; or if using a token cookie, set HttpOnly).
Send the token in an Authorization header (Authorization: Bearer <token> or another scheme) on requests. Django REST Framework supports this via authentication classes.
When using token auth with an API, you typically disable CSRF for those API endpoints (Django's CSRF is tied to the session auth method). If you go full API and treat the frontend as an external client, you might use Django REST framework with token auth and not worry about CSRF, or issue CSRF tokens via API if needed.

For this guide, we assume the simpler case: the SPA is served by Django, uses Django sessions, and thus we'll use CSRF tokens for any state-changing requests. In our examples above, GET requests (fetching data or HTML) are safe and don't require CSRF token. If we implement a feature like adding a new item or submitting a form via AJAX POST, we must include the CSRF header as shown. Django’s documentation provides a thorough explanation of using CSRF tokens in JavaScript requests.

Example (AJAX POST with CSRF): Suppose we have a form to add a new item via the SPA:

We have a Django view /api/items/add/ that expects a POST with JSON {"name": "...", "description": "..."} and creates an item.

JavaScript gathers the form data and does:

fetch("/api/items/add/", {
  method: "POST",
  headers: {
    "X-CSRFToken": csrftoken,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({ name: nameField.value, description: descField.value }),
  credentials: "same-origin"
})
.then(res => res.json())
.then(data => {
  if (data.success) {
     // maybe update the UI with the new item
  } else {
     // show errors
  }
});

The Django view would create the item and likely return some JSON, e.g. {"success": true, "item": {"id": ..., "name": ...}} or errors.

CORS Consideration: If your setup ever calls cross-domain (e.g., your static files served on a different domain or API on a subdomain), you'll have to handle Cross-Origin Resource Sharing and ensure the CSRF cookie and header are properly handled (generally, it's easier to keep same domain for SPA calls). We won’t delve into CORS here as we assume one integrated app, but keep it in mind if separating front and back.

Now that our front-end can communicate securely with the backend, let's ensure we manage static files properly for our JS and CSS.

Static Files Management (JavaScript, CSS, etc.)

Managing static files in this Django+JS SPA scenario is fundamentally the same as any Django project, with a few considerations due to heavy JS usage:

Location and Referencing: As shown in the structure, we keep JavaScript and CSS in the static/ directory of an app (or a global static directory). Each file should be referenced in templates using the {% static %} template tag to build the correct URL. For example, in base.html:
```
{% load static %}
<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <title>My Django SPA</title>
    <link rel="stylesheet" href="{% static 'myapp/css/style.css' %}">
    <script defer src="{% static 'myapp/js/app.js' %}"></script>
</head>
<body>
    
    <div id="content">{% include "myapp/home.html" %}</div>
</body>
</html>
```
In the above snippet, we include the CSS and the main JS (app.js). We also (optionally) included "myapp/home.html" into the content div for the initial load (so that the home page has content even before any AJAX calls). This is a nice touch for initial page load performance and SEO – the user immediately sees the home content, and our JS can still take over for subsequent navigation. If JavaScript is disabled, at least the home content shows (though navigating to other pages would require full reloads).
Collecting Static Files: During development, you typically don't worry about running collectstatic because runserver will serve files. In production, however, you should run python manage.py collectstatic to gather all static files into one location (as configured by STATIC_ROOT) and serve them with a proper web server or CDN. Ensure STATIC_URL is set (like /static/) and your web server is set up to serve that path. The Django docs on deploying static files cover this in detail.
Cache Busting: If you update your JS or CSS, browsers might cache them. Django's static file storage can be configured to use hashed file names (via ManifestStaticFilesStorage or similar) so that file names change when contents change. This is recommended for production so that clients always get the latest assets. Alternatively, manage versions manually or set appropriate cache headers.
Organization: For larger projects, you might split your JS into multiple modules or files. With vanilla JS, if you want to keep things simple, you could include multiple script files in the base template (just be mindful of load order if they depend on each other). Or you could use ES6 modules and a build step (though that introduces tooling, which we’re trying to minimize). If you do use a bundler or compiler (like Webpack, Parcel, etc.) to bundle your vanilla JS, that moves a bit towards a more complex setup, but can still be done without adopting a framework. Many people writing vanilla JS will use some modern syntax that requires a build (like import/export, or JSX-like templating with lit-html, etc.), but it's optional. Our guide sticks to plain JS that can run as-is in the browser.
CSS and assets: Similarly, manage your CSS in static files. If your SPA dynamically swaps content, you might want to ensure your CSS covers those sections (if using BEM or scoped styles, etc.). Also, images or other assets should be placed in static and referenced with {% static %} in templates or CSS.

In summary, static files in this Django SPA approach are treated just like any Django project. The difference is you might have a larger amount of JavaScript code than a typical server-rendered app, since the JS is handling routing and rendering logic. It's a good practice to keep your JS organized (for example, in modules or with clear comments and structure) as it grows.

Pros and Cons of Django+Vanilla JS SPA vs. a Full SPA Framework

Finally, it's important to consider the benefits and drawbacks of building an SPA in this manner compared to using a modern front-end framework (React, Vue, Angular, etc.) or even compared to a traditional multi-page application. Here’s a breakdown:

Pros of using Django templates + Vanilla JS for an SPA:

Simplicity and Familiarity: You can leverage Django’s templating and Python code for rendering content, which is great if you’re more comfortable in Python than in complex JavaScript frameworks. There’s no complex build setup or learning curve of a new framework – it’s just Django and basic JS.
Less Overhead: There is no large frontend library runtime. The app might have a smaller footprint since you’re only sending the JavaScript you wrote, not an entire framework. This can mean faster load times and less JS to parse, especially for simple applications. (Of course, if your vanilla JS grows huge, this advantage diminishes.)
SEO and Initial Load: By using Django to render content (especially for the initial page or by providing HTML fragments), you can ensure that meaningful HTML is served to crawlers and users upfront. Full SPA frameworks often send a mostly empty HTML shell and fill in via JS, which can hurt SEO unless you implement server-side rendering. Our approach can serve pre-rendered HTML for the initial view (and even subsequent ones via fragments), making it easier for search engines to see content. You also avoid the “white screen” problem where a heavy SPA might take a few seconds to load JS before showing content.
Integrated Backend/Frontend: With Django handling both the page and API endpoints, you keep a single project for both front-end and back-end logic. This can simplify development and deployment (one codebase, one server to run). You can also easily reuse Django features like forms, internationalization (in templates), etc., and use Django's ORM and other backend powers without needing to create a separate REST API layer (unless you want to).
Fine-grained Control: You can optimize at a very granular level. You’re not constrained by a framework’s way of doing things, so for performance or specific behavior, you can write custom JS to do exactly what you need. For example, you can choose to update only a part of the page if you know only that section changed, without having to re-render a whole virtual DOM.
Gradual Enhancement: This approach can start from a normal Django app and gradually add “SPA” behavior. You could have a fully server-rendered app and then sprinkle in AJAX navigation for certain sections. It doesn’t have to be all-or-nothing. This incremental adoptability is harder with something like React (where typically you build the whole UI in React). Libraries like htmx were created to follow this incremental approach, but you can do it yourself too.

Cons and Challenges:

Increasing Complexity -> Reinventing the Wheel: As your app grows in complexity, managing state and UI updates in vanilla JS can become hard. You might find yourself essentially building your own mini-framework of utility functions to handle templating, routing, state management, etc. Many developers find that beyond a certain point, a framework (which provides structure, components, and an ecosystem) becomes worthwhile. In fact, you might end up with a highly coupled or messy codebase if not carefully organized. Frameworks are popular because they enforce patterns that scale well; with vanilla JS you must establish your own patterns.
Maintainability: Related to the above, code maintainability can suffer. Without components or clear separation of concerns, if you have a lot of DOM manipulation code scattered in different functions, it can be harder for new developers (or your future self) to understand. Debugging a large vanilla JS codebase can be tricky if you don't impose some structure.
Lack of Developer Tools: Modern frameworks come with great dev tools (e.g., React DevTools) and often hot-reload, error overlays, etc. With a vanilla JS approach, you won't automatically have those. You have the browser console and maybe your own logging. Build tools can be added for conveniences like auto-reloading or compiling newer JS syntax, but each thing you add reduces the simplicity advantage.
State Management: In an SPA, managing application state (current user, data loaded, what’s been modified, UI state like modals open, etc.) is crucial. Frameworks provide patterns (like React's state and props or Redux, etc.) to handle this systematically. With vanilla JS, you might end up with a few global variables or a custom store pattern. It can work, but it's another thing you have to design. For example, if two parts of your UI need to reflect the same state, you need to ensure your code updates both appropriately – frameworks often do this more automatically via reactivity or a virtual DOM diff.
Routing Features: The History API gives basic control, but a full routing library (like those in SPAs) handles more (like route parameters, nested routes, etc.). Implementing those features in vanilla JS is possible but adds work. If your app is simple (handful of pages), History API usage as shown is fine. If you need complex routing (with maybe authentication gating routes, or pre-fetching data on route change, etc.), a framework or at least a small routing library might help.
UI Complexity: Complex UI interactions (drag-drop, real-time updates via websockets, etc.) can be done in vanilla JS, but frameworks often provide abstraction or ecosystem libraries to ease these. Without a framework, you might use smaller libraries as needed (which is okay – using, say, Chart.js for charts or Algolia for search is no problem, because those aren't SPAs frameworks, just libraries for a feature).
Community & Examples: You will find far more tutorials, components, and community support around React/Vue/etc. When doing it yourself, you'll rely on more general web knowledge and various smaller resources. It can be very rewarding intellectually, but also challenging if you hit a roadblock that a framework would have solved.
Performance Considerations: While vanilla JS can outperform frameworks for simple tasks (since there's no overhead of diffing or huge libraries), in a larger app, frameworks often employ optimized techniques (like the virtual DOM in React doing batch updates) that naive vanilla code might not handle as efficiently. For example, updating the DOM in large chunks incorrectly could cause layout thrashing or be slower than a framework that knows how to minimize reflows. You need to be mindful of performance (e.g. updating DOM off-screen, using document fragments, etc., if dealing with large lists) which frameworks often handle for you. That said, you have the potential for very efficient code if you do it carefully.

Comparison to using full SPA frameworks: In summary, using Django+vanilla JS for an SPA is a good approach for small to medium projects or when you explicitly want to avoid the bloat of a framework and keep everything in one place. It shines when your team is backend-heavy or when SEO and initial load are important but you still want SPA-like navigation. On the other hand, if you're building a very large, interactive front-end (like a project management tool, rich text editor app, etc.), the engineering effort might be lower with a well-chosen front-end framework where such problems have known solutions. And as some developers note, you can start with vanilla and later migrate to a framework if needed (some libraries like Alpine.js or Vue can even enhance parts of a mostly static app gradually).

To quote a perspective: going full vanilla is possible, "but libraries like React, Vue, Svelte and others can make your life easier, depending on complexity and interactivity of your SPA". The key is to choose the right tool for the job.

Example: Bringing It All Together

Let's consolidate the concepts with a simplified example. Imagine we are building a simple SPA for a library of books. We have two main views: a Home page and a Books page. The Home page is mostly static welcome text, and the Books page displays a list of books and allows adding a new book (via a form).

Django URLs and Views:

# myapp/urls.py
from django.urls import path
from . import views

urlpatterns = [
    path('', views.index, name='index'),            # Serves base page (home content)
    path('books/', views.index, name='index'),      # We serve the same base for direct /books/ (handle in JS)
    path('api/books/', views.books_data, name='books_data'),        # JSON list of books
    path('api/books/add/', views.add_book, name='add_book'),        # Handle book creation (POST)
    path('fragment/books/', views.books_fragment, name='books_fragment'),  # (Optional) HTML fragment for books list
]

In the above, note we mapped /books/ to the same views.index. This means if a user directly visits /books/, we still return the SPA base page (so they get the app shell). We’ll use the URL to know we should show the Books view initially (could do this by reading window.location.pathname on load).

Now views.py:

from django.shortcuts import render
from django.http import JsonResponse, HttpResponse
from .models import Book

def index(request):
    # Render the SPA container. If desired, we could pass initial data.
    return render(request, "myapp/base.html")

def books_data(request):
    """Return JSON data for all books."""
    books = Book.objects.all().values("id", "title", "author")
    return JsonResponse(list(books), safe=False)

def books_fragment(request):
    """Return an HTML snippet for the books list."""
    books = Book.objects.all()
    return render(request, "myapp/partial_books_list.html", {"books": books})

def add_book(request):
    """API endpoint to add a new book (expects JSON POST)."""
    if request.method == "POST":
        import json
        data = json.loads(request.body.decode('utf-8'))
        title = data.get("title")
        author = data.get("author")
        # Validate data (omitted for brevity)
        book = Book.objects.create(title=title, author=author)
        # Return the new book's data as JSON
        return JsonResponse({"id": book.id, "title": book.title, "author": book.author})
    else:
        return JsonResponse({"error": "Invalid method"}, status=405)

This setup gives:

index: serves base.html (which will include the Home content by default).
books_data: returns JSON list of books.
books_fragment: returns a rendered HTML list of books.
add_book: accepts a POST with book info and returns the created book JSON (in a real app, add error handling, authentication checks, etc.).

Templates (base.html and partial):

<!-- myapp/templates/myapp/base.html -->
{% load static %}
<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <title>Library SPA</title>
  <link rel="stylesheet" href="{% static 'myapp/css/style.css' %}">
  <script defer src="{% static 'myapp/js/app.js' %}"></script>
</head>
<body>
  <nav>
    <a href="/" data-page="home" id="nav-home">Home</a> |
    <a href="/books/" data-page="books" id="nav-books">Books</a>
  </nav>
  <div id="content">
    {% include 'myapp/home.html' %}
  </div>
</body>
</html>

home.html might be a simple fragment:

<!-- myapp/templates/myapp/home.html -->
<h1>Welcome to the Library</h1>
<p>This is the home page of our Library application. Click "Books" to view the collection.</p>

partial_books_list.html for the books list and form:

<!-- myapp/templates/myapp/partial_books_list.html -->
<h1>Books</h1>
<ul id="book-list">
  {% for book in books %}
    <li>{{ book.title }} by {{ book.author }}</li>
  {% empty %}
    <li>No books in the library.</li>
  {% endfor %}
</ul>

<h3>Add a New Book</h3>
<form id="add-book-form">
  <label>Title: <input type="text" name="title" required></label><br>
  <label>Author: <input type="text" name="author" required></label><br>
  <button type="submit">Add Book</button>
</form>

This template displays a list of books and a form. (Note: We will handle the form submission via JS, so the form doesn’t need an action attribute. We include it primarily for structure; it could even be created entirely in JS if we prefer.)

JavaScript (app.js):

// Get CSRF token from cookie
function getCookie(name) {
  // (Cookie reading function as provided earlier)
  // ...
}
const csrftoken = getCookie('csrftoken');

function showHome() {
  // Simply show the embedded home content (which is already in the DOM from initial load)
  document.querySelector('#content').innerHTML = document.querySelector('#content').innerHTML;
  // (In this case, home content was included in base.html. If not, we could fetch a fragment.)
}

function showBooks() {
  // Option 1: Fetch HTML fragment
  fetch("/fragment/books/")
    .then(res => res.text())
    .then(html => {
      document.querySelector('#content').innerHTML = html;
      // After inserting the content, attach event handler for the form
      attachBookFormHandler();
    });
    
  // Option 2: Alternatively, use JSON:
  // fetch("/api/books/").then(res => res.json()).then(data => { ... construct list ... })
  // plus adding the form HTML. For brevity, we use the fragment approach here.
}

function attachBookFormHandler() {
  const form = document.querySelector('#add-book-form');
  if (!form) return;
  form.onsubmit = function(event) {
    event.preventDefault();
    const title = form.querySelector('input[name="title"]').value;
    const author = form.querySelector('input[name="author"]').value;
    // Send POST to add book
    fetch("/api/books/add/", {
      method: "POST",
      headers: {
        "X-CSRFToken": csrftoken,
        "Content-Type": "application/json"
      },
      body: JSON.stringify({ title: title, author: author }),
      credentials: "same-origin"
    })
    .then(res => res.json())
    .then(data => {
      if (data.error) {
        alert("Error: " + data.error);
      } else {
        // Update the book list with the new book
        const list = document.querySelector('#book-list');
        const li = document.createElement('li');
        li.textContent = `${data.title} by ${data.author}`;
        list.appendChild(li);
        // Clear form fields
        form.reset();
      }
    })
    .catch(err => console.error("Failed to add book:", err));
  };
}

// Router: handle navigation
function loadPage(page, push=true) {
  if (page === 'home') {
    showHome();
  } else if (page === 'books') {
    showBooks();
  }
  if (push) {
    // Update history state and URL
    const url = page === 'home' ? '/' : '/books/';
    history.pushState({ page: page }, "", url);
  }
}

// Set up event listeners on nav links
document.addEventListener('DOMContentLoaded', function() {
  document.querySelectorAll('a[data-page]').forEach(link => {
    link.onclick = function(e) {
      e.preventDefault();
      const page = this.dataset.page;
      loadPage(page);
    };
  });
  
  // If the page was loaded with a specific URL (like /books/), load that page content
  const initialPath = window.location.pathname;
  if (initialPath === '/books/') {
    loadPage('books', push=false);
  }
});

// Back/forward button handler
window.onpopstate = function(event) {
  if (event.state && event.state.page) {
    loadPage(event.state.page, push=false);
  }
};

Let's break down this app.js:

We fetch csrftoken at the top (so we can use it for any POST requests).
showHome() and showBooks() are functions to render the respective pages. showHome here is trivial because the home content was server-rendered initially. (If home content needed to be fetched later, we would do a fetch similar to showBooks.)
showBooks() uses the HTML fragment approach to get the books list and form from the server and then calls attachBookFormHandler() to bind the form's submit event to an AJAX call. We could have embedded the form event binding directly after injecting HTML, but separating it into a function clarifies the flow.
attachBookFormHandler() finds the form and overrides its submit to do an AJAX POST to /api/books/add/. On success, it updates the DOM by adding a new <li> to the list of books, and resets the form. Note how we used the CSRF token in the header here.
The router logic: loadPage(page, push=true) decides which content to load. After loading, it does history.pushState (unless push=false indicating we don't need to push a new history entry, e.g. when handling back button or initial load).
We attach click handlers to the nav links to call loadPage instead of navigating.
We also check the initial URL on page load: if the user loaded /books/ directly, we call loadPage('books', push=false) to render the books content immediately (and we pass push=false because we do not want to push a new history entry for the state we’re already in). This covers the scenario of direct linking – the Django index view delivered the base page, and now our JS kicks in to load the right section.
Finally, window.onpopstate calls loadPage for the state, again with push=false to avoid altering history while going back.

This example ties together template rendering, fragment fetching, JSON POST with CSRF, and the History API for routing. The user can navigate between Home and Books without full reloads, the URL updates accordingly, and they can even add a book via the form which updates the list dynamically. If they hit refresh on /books/, they get the base page and then the JS loads the books content.

Potential enhancements: In a real app, you would add proper error handling (display errors from form submissions, maybe disable the form while submitting, etc.), loading indicators when fetching data, and perhaps more robust routing (if many pages, a mapping or even a tiny router library could help). You might also handle 404s or unknown routes by showing a "Not found" message via JS. All that can be done in vanilla JS but requires more code.

Conclusion

Building an SPA with Django and vanilla JavaScript is a perfectly viable approach that leverages Django's strength in serving content and Python logic, combined with the flexibility of client-side scripting. We covered how to set up the project, manage client-side routing with the History API (to keep the URL in sync without reloads), and two methods of dynamic content rendering (JSON vs HTML fragments). We also addressed crucial considerations like CSRF protection for AJAX and how to use Django's session authentication seamlessly in this scenario, as well as static file management to serve our JS/CSS.

This approach is powerful for certain use cases, especially if you want to avoid the complexity of a full front-end framework or if you want to progressively enhance a server-rendered app with SPA-like features. You get fine control over what happens and can optimize as needed. However, we also discussed the trade-offs – as your app grows, managing everything with custom JS can become challenging, and one might consider introducing a framework or at least structured patterns to maintain code quality.

Ultimately, whether to go with Django+vanilla JS or a framework depends on your project’s requirements, team’s expertise, and long-term maintainability considerations. If you do choose this path, you now have a roadmap to implement an SPA: a structured Django backend, a well-organized frontend script, and careful handling of navigation and security. Good luck with building your Django-powered SPA! Enjoy the blend of server-side reliability and client-side agility in your project.