DEV Community: Simon (Sai)

A Stack of Feature Flags [Tutorial]

Simon (Sai) — Sun, 26 Jan 2025 20:20:42 +0000

An Introduction & Getting Started

After working on another project that implemented feature flags, I decided to create a guide that shows one way of implementing feature flags for a full-stack web application using Starlette and React + React Router. This guide can serve as a foundation for adding support to feature flags to an existing project.

The purpose of this tutorial is to show you an example of possibly implementing feature flags in a full stack application. The techniques shown here demonstrate one of the many ways to implement feature flags. As with everything, there are multiple ways to solve problems

To ensure the smoothest possible experience while following along with this tutorial, we will assume that you have the following installed and ready to go

✅ NodeJS 18/20+ and NPM
✅ Python 3.10+
✅ Pipenv (or virtualenv)
✅ Git

Application Specifics

The API for this project is implemented as a Starlette web application.

The frontend is built using React 18 and React Router 6. There will be an update to React 19 and React Router 7 in the near future.

Project Overview

To get started, start by cloning the starter repository from and navigating to the directory. You should see the following high-level folder structure

https://github.com/saiforceone/fstack-feature-flags

📁 fstack-backend

📁 fstack-frontend

Setting up the backend

Navigate to the backend folder, and initialize the virtual environment using the following command

# initialize environment
pipenv shell

Next, we’ll install our dependencies using the following

# install dependencies
pipenv install

Finally, we’ll run our backend using the following command

uvicorn app:app --port 5101 --reload

--port 5101 specifies that we want to run on local port 5101 but you can change this to anything you want as long as there are no conflicts

--reload enables reload on changes

Testing the backend

Let’s do a quick test of our backend to make sure things are working. To do so, we can use a browser or http client like Postman or Insomnia and navigating to http://localhost:5101/api/notes. When we do this, we should see output that looks like the following because we don’t have any notes yet.

{
    data: null,
    message: "",
    success: false
}

Setting up the Frontend

Let’s shift our focus to getting the frontend working. We’ll start by navigating to the frontend folder and installing our dependencies with NPM.

npm i

# or
npm install

Creating our .env file

We will be making using of an environment file to store certain app-specific values. Let’s go ahead and create the following file frontend/.env and paste the following

# Base URL for the API
VITE_API_BASE_URL="http://localhost:5101/api"

We can now run our frontend by using the following command

npm run dev

For this project, we are using Tailwindcss which has already been set up for us and is ready to use.

Let’s check out our project by navigating to the following url

http://localhost:5102

We should see something that looks like the image below

This should take care of all the set up part of the project. Next, we’ll get onto the actually work of implementing feature flags on both the backend and frontend

Implementing Feature Flags

Let’s go ahead and create a new branch for repository and naming it accordingly. I’ll be naming my branch implement-feature-flags but you can call it whatever you want

git checkout -b implement-feature-flags

Defining The Feature Flag Model

In the backend/models folder, we’ll create a new file called feature_flag.py and add the following code

# File: feature_flag.py
from sqlalchemy import String, Text, Boolean
from sqlalchemy.orm import Mapped, mapped_column

from .base_model import BaseModel

class FeatureFlag(BaseModel):
    __tablename__ = 'feature_flag'

    id: Mapped[int] = mapped_column(primary_key=True, autoincrement=True)
    flag: Mapped[str] = mapped_column(String(100), nullable=False)
    description: Mapped[str] = mapped_column(Text, nullable=True)
    enabled: Mapped[bool] = mapped_column(Boolean, default=True)

    def to_dict(self):
        return {
            "flag": self.flag,
            "description": self.description,
            "enabled": self.enabled,
        }

Implementing the Feature Flag Controller

in the backend/controllers folder, we’ll create a new file called feature_flag_controller.py and add the following code

# File: feature_flags_controller.py
import sqlalchemy
from starlette.requests import Request
from starlette.responses import JSONResponse
from starlette.types import Scope, Receive, Send

from controllers.base_controller import BaseController
from models.base_model import BaseModel
from models.feature_flag import FeatureFlag
from support.db_utils import db_utils

class FeatureFlagsController(BaseController):

    def __init__(self, scope: Scope, receive: Receive, send: Send):
        super().__init__(scope, receive, send)

        self.session = db_utils.session

        # check if the table exists and creates it if necessary
        if not sqlalchemy.inspect(db_utils.engine).has_table('feature_flag'):
            BaseModel.metadata.create_all(bind=db_utils.engine, tables=[BaseModel.metadata.tables['feature_flag']])

    async def get(self, request: Request) -> JSONResponse:
        response = FeatureFlagsController._build_response()

        # try to retrieve feature flags that are enabled
        try:
            feature_flags = self.session.query(
                FeatureFlag
            ).where(FeatureFlag.enabled).all()
        except Exception as e:
            print(f"Failed to retrieve feature flags with error: {e}")
            response['message'] = 'An unexpected error occurred while retrieving feature flags'
            return JSONResponse(response, status_code=500)

        if len(feature_flags) == 0:
            response['message'] = 'No feature are available'
            return JSONResponse(response, status_code=404)

        response['data'] = [flag.to_dict() for flag in feature_flags]
        response['success'] = True
        return JSONResponse(response)

Let’s also update our controllers/__init__.py file as by adding from .feature_flags_controller import FeatureFlagsController to end of file as shown below

# File: controllers/__init__.py

from .notes_controller import NotesController
from .feature_flags_controller import FeatureFlagsController # <- add this line

Next, we’ll update our routes so that we can fetch our features

# File: routes/__init__.py
from starlette.routing import Route, Mount

from controllers import NotesController, FeatureFlagsController # <- update our import to include FeatureFlagController

app_routes: list[Route | Mount] = [
    Mount('/api', routes=[
        Route('/notes', NotesController),
        Route('/notes/{note}', NotesController),
        Route('/features', FeatureFlagsController), # <- add this line
    ]),
]

Let’s test what we have so far by navigating to http://localhost:5101/api/features and seeing what is returned.

{
    data: null,
    message: "No feature are available",
    success: false
}

This is normal since we have not yet added any features. Using a database client, we can manually add a feature or two. So feel free to do that, I’ll be adding two features, FE_INLINE_NOTE_DELETE and NOTE_DELETE but you can call them whatever you want. We should now see something that looks like the result below

{
    data: [
        {
            flag: "FE_INLINE_NOTE_DELETE",
            description: "Enables inline note deletion from the note listing"
        },
        {
            flag: "NOTE_DELETE",
            description: "Enables note deletion"
        }
    ],
    message: "",
    success: true
}

Note: we’re excluding the id and enabled fields since we don’t need to return the id of the specific feature and the feature is returned then it must be enabled.

We’ll come back to the backend to apply this to our NotesController.

Updating the Frontend to use the features

So we have a feature flags endpoint that gives us a list of enabled features, let’s see about using this on the frontend

Updating frontend type definitions

Add the following type to our frontend/@types/fstack-flags.d.ts file

export type FeatureFlag = {
  /**
   * @readonly
   *
   * A string representing the name of the flag
   *
   * @example `RENDER_NEW_UI`
   */
  readonly flag: string;

  /**
   * @readonly
   *
   * An optional description for the feature flag
   *
   * @example 'Indicates if the new UI should be used instead of the current'
   */
  readonly description?: string;
};

In the same file, we will need to update our FStackFlagsContext to include an array of feature flags


export type FStackFlagsContext = {
  /**
   * Indicates if data is loading at the app-level
   */
  dataLoading: boolean;

  /**
   * Contains feature flags retrieved from the API
   */
  featureFlags: Array<FeatureFlag>; // <- add this
};

Implementing the FeatureFlagsServices

We will need a way to retrieve features from the API. Let’s create the file frontend/services/feature-flags-service.ts and paste in the following code

// File : services/feature-flags-service.ts
import { type APIUtility, BaseAPIResponse, FeatureFlag } from "../@types/fstack-flags";

const BASE_URL = import.meta.env.VITE_API_BASE_URL;

export default class FeatureFlagsService implements APIUtility {
  readonly baseUrl: string;
  constructor() {
    this.baseUrl = `${BASE_URL}/features`;
  }

  headers(): Headers {
    return new Headers({
      'content-type': 'application/json',
    })
  }

  /**
   * @function getFeatures
   * @description retrieves the available features from the API
   * @returns {Promise<Array<FeatureFlag> | null>}
   */
  async getFeatures(): Promise<Array<FeatureFlag>|null> {
    try {
      const response = await fetch(this.baseUrl, {
        headers: this.headers(),
      })
      const jsonData = (await response.json()) as BaseAPIResponse;
      if (!jsonData.success) return null;
      return jsonData.data as FeatureFlag[];
    } catch (e) {
      console.error(`Failed to retrieve feature flags with error: ${(e as Error).message}`);
      return null;
    }
  }
}

ℹ️ As an extra step, we could add inbound validation using something like Zod to add that extra layer of safety at runtime.

Updating our context to retrieve feature flags

Now that we have our feature flags service, we will need to fetch enabled features and make them available via our context. The following code will take care of that

import { createContext, ReactNode, useCallback, useEffect, useState } from "react";
import type { FeatureFlag, FStackFlagsContext } from "../@types/fstack-flags";
import FeatureFlagsService from "../services/feature-flags-service.ts";

export const FStackFEContext = createContext<FStackFlagsContext | null>(null);

export default function FStackFeContextProvider({ children }: { children: ReactNode }): ReactNode {
  const [dataLoading, setDataLoading] = useState<boolean>(false);
  const [features, setFeatures] = useState<Array<FeatureFlag>>([]);

  const fetchFeatures = useCallback(() => {
    const _exec = async () => {
      const featureFlagsService = new FeatureFlagsService();
      const featureResponse = await featureFlagsService.getFeatures();
      if (!featureResponse) return;
      setFeatures(featureResponse);
    }

    _exec().then();
  }, []);

  useEffect(() => {
    fetchFeatures();
  }, [fetchFeatures])

  return <FStackFEContext.Provider value={{ dataLoading, featureFlags: features }}>{children}</FStackFEContext.Provider>;
}

If everything worked as expected, you should be able to see our context containing our feature flags similar to the screenshot below

Setting up conditional rendering based on a feature flag

With our feature flags being retrieved from the API and available via context, we will need a way to make use of them in our application. We will be creating a component that will handle things for us.

Let’s create our component called feature-wrapper.tsx in our components/shared directory and paste the following code

// File:  feature-wrapper.tsx
import { type ReactNode, useContext } from "react";
import { FStackFEContext } from "../../context/fstack-fe-context.tsx";
import { FStackFlagsContext } from "../../@types/fstack-flags";
import { hasFeature } from "../../helpers/feature-helpers.ts";

type FeatureWrapperProps = {
  children: ReactNode;
  requiredFeature: string;
}

/**
 * @function FeatureWrapper
 * @param {ReactNode} children the component to render if the required feature flag is present
 * @param {string} requiredFeature the flag that is required to render the wrapped component
 * @constructor
 * @return {ReactNode}
 */
export default function FeatureWrapper({ children, requiredFeature }: FeatureWrapperProps): ReactNode {
  const { featureFlags } = useContext(FStackFEContext) as FStackFlagsContext;
  const canRender = hasFeature(requiredFeature, featureFlags);
  return canRender ? children : null;
}

In order to test this out, let’s open our notes listing routes/notes/_index.tsx and update how we are displaying notes as shown below:

// add state for selected note
const [selectedNote, setSelectedNote] = useState<Note | null>(null);

// add this to delete a note
const deleteNote = useCallback(() => {
  const _exec = async () => {
    if (!selectedNote) return;
    const notesService = new NotesService();
    const deleteResult = await notesService.deleteNote(`${selectedNote.id}`);
    if (!deleteResult.success) return alert("Failed to delete note");
    fetchNotes();
  };

  _exec().then();
}, [fetchNotes, selectedNote]);

// updated note card renedered

<NoteCard
  key={`note-${note.id}`}
  note={note}
  actionElements={
    <>
      <NavLink
        className='underline text-blue-600 flex items-center gap-1'
        to={`/edit-note/${note.id}`}
      >
        <BiSolidEdit />
        Edit Note
      </NavLink>
      {/* Begin - add this block */}
      <FeatureWrapper requiredFeature='FE_INLINE_NOTE_DELETE'>
        <button
          className='flex items-center gap-1 text-red-600 underline cursor-pointer'
          onClick={() => setSelectedNote(note)}
        >
          <BiSolidTrash />
          Delete
        </button>
      </FeatureWrapper>
      {/* End - add this block */}
    </>
  }
/>

{/* add this confirm dialog as the last component in the _index.tsx component right above the closing </PageWrapper> tag*/}
{selectedNote ? (
  <ConfirmDialog
    content={
      <p className='text-lg'>
        You are about to delete the note:{" "}
        <span className='font-medium'>{selectedNote.title}</span>. Would you like to continue?
      </p>
    }
    dialogDismissAction={() => setSelectedNote(null)}
    dialogOpen={true}
    titleText='Delete Note?'
    dialogActionElements={
      <div className='flex items-center gap-2'>
        <button
          className='p-2 rounded bg-slate-800 text-white flex items-center'
          onClick={() => setSelectedNote(null)}
        >
          <BiSolidArrowToLeft />
          No, don't delete it
        </button>
        <button
          className='p-2 rounded bg-red-600 text-white flex items-center'
          onClick={() => {
            setSelectedNote(null);
            deleteNote();
          }}
        >
          <BiSolidTrash />
          Yes, delete it!
        </button>
      </div>
    }
  />
) : null}

Updating the API to facilitate feature flags

we have one thing left to do in order to complete our feature flag implementation which is implementing and using a new decorator function for feature flags. In the backend project, create the file support/require_feature_flag.py and paste the following code

import functools
import inspect
import typing
from starlette.requests import Request
from starlette.responses import JSONResponse

from models.feature_flag import FeatureFlag
from .db_utils import db_utils

def require_feature_flag(required_flag: str):

    def feature_exec_wrapper(func: typing.Callable) -> typing.Callable:
        sig = inspect.signature(func)
        for idx, parameter in enumerate(sig.parameters.values()):
            if parameter.name == "request":
                break
        else:
            raise Exception(
                f'No "request" argument on function "{func}"'
            )

        @functools.wraps(func)
        async def exec_feature_check(*args, **kwargs):

            # try to retrieve feature flags matching the required_flag            
            try:
                feature_flag = db_utils.session.query(
                    FeatureFlag
                ).where(
                    FeatureFlag.flag == required_flag, FeatureFlag.enabled == True
                ).scalar()
            except Exception as e:
                print(f"failed to retrieve feature flag with error: {e}")
                return JSONResponse({
                    'success': False,
                    'message': 'Unexpected error occurred'
                }, status_code=500)

            if feature_flag is None:
                print(f"the feature: {required_flag} was not found or is invalid")
                return JSONResponse({
                    'success': False,
                    'message': 'Invalid feature'
                }, status_code=500)

            return await func(*args, **kwargs)

        return exec_feature_check

    return feature_exec_wrapper

Next, we’ll need to update the delete method handler in our notes_controller.py to make use of our newly created decorator function. Copy and paste the code below

# update imports
from support.require_feature_flag import require_feature_flag  # <- add this import

# add decorator to delete method handler
@require_feature_flag(required_flag='NOTE_DELETE')  # <- add this above the delete method handler

With these changes in place, you should be able to enable features for both the frontend and backend part of your application. Play around with enabling and disabling feature flags and observe how the application behaves.

Where to go from here?

This tutorial is meant to give you an example of how you can implement feature flags in a fullstack web application and is not the only method. There are different ways to solve this problem, I would recommend experimentation with some of the other methods such as environment variables, hosted config files, SaaS applications, etc.

Implementing a route cache system (optional)

In this section, we will look at one possible way we can implement caching for a more robust solution. Since we’re using Starlette, we can tap into Starlette’s lifespan event to load the enabled feature flags into application state.

Let’s take a look at some documentation and see how we can implement a simple application cache that will hold our enabled features. See: https://www.starlette.io/applications/#starlette.applications.Starlette

Update the imports in our app.py file

from contextlib import asynccontextmanager

from models.feature_flag import FeatureFlag
from support.db_utils import db_utils

We’re going to implement a lifespan method inside of our app.py file as shown below

@asynccontextmanager
async def lifespan(application):
    """
    This method performs tasks for application startup and shutdown. In this case, we are caching the enabled feature
    flags on application startup, if none are found, we'll set the cached flags to an empty list
    :param application:
    :return:
    """
    try:
        enabled_features = db_utils.session.query(FeatureFlag).where(FeatureFlag.enabled).all()
        setattr(application.state, 'CACHED_FLAGS', [flag.to_dict() for flag in enabled_features])
    except Exception as e:
        print(f"failed to retrieve enabled feature flags with error: {e}. Continuing application startup...")
        setattr(application.state, 'CACHED_FLAGS', [])
    yield

app = Starlette(debug=True, middleware=middleware, routes=routes, lifespan=lifespan)

Next, we’ll update our decorator function to make use of our cached feature flags while having a fallback mode if something unexpected happens

import functools
import inspect
import typing
from starlette.requests import Request
from starlette.responses import JSONResponse

from models.feature_flag import FeatureFlag
from support.db_utils import db_utils

def require_feature_flag(required_flag: str):

    def feature_exec_wrapper(func: typing.Callable) -> typing.Callable:
        sig = inspect.signature(func)
        for idx, parameter in enumerate(sig.parameters.values()):
            if parameter.name == "request":
                break
        else:
            raise Exception(
                f'No "request" argument on function "{func}"'
            )

        @functools.wraps(func)
        async def exec_feature_check(*args, **kwargs):
            request = kwargs.get("request", args[idx] if idx < len(args) else None)  # <- retrieve the request from kwargs
            assert isinstance(request, Request)  # <- assert request is an instance of Request

            # retrieve feature flags from the application state
            cached_flags = getattr(request.app.state, 'CACHED_FLAGS', [])

            feature_flag = None

            # check the list of cached_flags
            if len(cached_flags) > 0:
                # search the cache
                for flag in cached_flags:
                    if flag['flag'] == required_flag:
                        print("cache hit!")
                        feature_flag = flag
            else:
                print("cache miss")
                # try to retrieve feature flags matching the required_flag
                try:
                    feature_flag = db_utils.session.query(
                        FeatureFlag
                    ).where(
                        FeatureFlag.flag == required_flag, FeatureFlag.enabled == True
                    ).scalar()
                except Exception as e:
                    print(f"failed to retrieve feature flag with error: {e}")
                    return JSONResponse({
                        'success': False,
                        'message': 'Unexpected error occurred'
                    }, status_code=500)

            if feature_flag is None:
                print(f"the feature: {required_flag} was not found or is invalid")
                return JSONResponse({
                    'success': False,
                    'message': 'Invalid feature'
                }, status_code=500)

            return await func(*args, **kwargs)

        return exec_feature_check

    return feature_exec_wrapper

Things to consider

For a more complete implementation, we would need to implement a way to invalidate and refresh the cached feature flags. One thing that comes to mind is using triggers or events provided by an ORM for a specific database model. In theory, when a new feature flag is added or an existing flag is updated, the cached feature flags can be refreshed and the application state will be consistent.

The require_feature_flag wrapper function could be further optimized / cleaned up

We can also implement a better logger system and other optimizations.

Anyway, this is intended as an example of how one could possibly implement feature flags for both the backend and frontend.

Build Web Fullstack Apps with DIRT: Django, Inertia, React & Tailwind CSS aka D.I.R.T Stack

Simon (Sai) — Tue, 07 Feb 2023 17:41:24 +0000

Lately, I've been digging into (🙃) the world of InertiaJs so, here’s a mini guide on how to get Tailwind CSS working in your Django + InertiaJs + React (Vite) project. Since there are so many “stacks” out there already, I figured, let’s just make one (assuming this hasn’t been done before).

A few notes to get started

The following pre-requisites would be helpful to get things going smoothly

A code editor or IDE (I’m using PyCharm)
A willingness to try things
Some knowledge of Django 🐍, React ⚛️, TypeScript & Tailwind CSS
Like most things code, this is a work-in-progress

ℹ️ PyCharm community does not have NodeJs support so you will not get code completion when we get to the React part. Also, I’ll be using a separate terminal just for the purpose of getting screenshots. Normally I use PyCharm’s terminal.

Framework & Language versions

Django v4.1 LTS
InertisJS 1.0
React 18 / Vite 4
Tailwind CSS 3

Tested Platforms

✅ MacOS

✅ Ubuntu

✳️ Windows (I'm sure this will work)

Django Project Setup

Before we get started, I’m going to give an overview of what we’re going to be using

pipenv to manage virtual environments (If you like, you can use the more classical approach of using virtualenv).
Git because it’s just a good idea

Everything else we need will be pretty standard. Since this is a mini-guide, we’re not going to worry about things like what database we’ll be using.

ℹ️ We’re going to be using pipenv. if you have not yet installed it, click here for instructions.

ℹ️ You may choose to use virtualenv if you’d like

Start by creating a new Django Project. We’ll call it dirt-tutorial

# create the directory
mkdir dirt-tutorial

# navigate to directory
cd dirt-tutorial

Activate the virtual environment

pipenv shell

Installing Django

We’re going to need to install a few dependencies on both the Python / Django side as well as the React / Vite side. To make it easier, I’m giving you all the steps you need to get started.

Install Django via pipenv

pipenv install django==4.1

ℹ️ Be sure to check to see if any security updates need to be installed for Django and update accordingly

Create the project using django-admin in the current directory

django-admin startproject dirt_tutorial .

Now would be a good time to make sure everything is working as it should.

Run the Django dev server using ./manage.py

./manage.py runserver

✳️ You can apply the unapplied migrations at this point if you would like.

We should also set up GIT at this point. So let’s go ahead and do that. I’m including a minimal .gitignore file that should suffice for our purposes.

Initialize a new repo in the current directory (📂)

git init

Create a .gitignore file and copy in the contents below. This is a minimal ignore file btw.

# Byte-compiled / optimized / DLL files
__pycache__/
*.py[cod]
*$py.class

# PyInstaller
*.manifest
*.spec

# Installer logs
pip-log.txt
pip-delete-this-directory.txt

# Django stuff:
*.log
db.sqlite3
db.sqlite3-journal

# Minimal Virtualenv
.venv

# Jetbrains
.idea

# Minimal NodeJS
dist
node_modules

Go ahead and commit your files. If you have a remote for your repo, you can push.

Inertia Setup

Now that we have a working base project, let’s start adding the pieces of the puzzle that will allow us to make use of Inertia.

Create a new branch from main, we can call it something like setup-inertia

git checkout -b setup-inertia

Install dependencies for Inertia via pipenv install

pipenv install inertia-django django-vite

Now that we have our dependencies installed, let’s make the necessary updates to the files we need.

Update settings.py to include django_vite and inertia in INSTALLED_APPS, and inertia.middleware.InertiaMiddleware in MIDDLEWARE

INSTALLED_APPS = [
    # default apps removed to save space

    # D.I.R.T Stack apps
    "django_vite", # <- add this app 
    "inertia", # <- add this app too
    # our apps
]

MIDDLEWARE = [
    # default middleware removed to save space

    # D.I.R.T Stack middleware
    "inertia.middleware.InertiaMiddleware", # <- add this
]

Create a template file ./templates/base.html. We’ll modify this a few times so you can keep it open in your editor or IDE

{% load django_vite %}
<!DOCTYPE html>
<html lang="en">
    <head>
        <meta charset="UTF-8">
        <meta name="viewport" content="width=device-width, initial-scale=1"/>
                 <!-- vite hmr -->
        {% vite_hmr_client %}
        {% vite_asset 'src/main.js' %}
        <title>D.I.R.T Stack - Django Inertia React Tailwind CSS</title>
    </head>
    <body>      
        <!-- inertia -->
        {% block inertia %}{% endblock %}
    </body>
</html>

Update the settings.py to include the following change to DIRS as shown below

TEMPLATES = [
    {
        'BACKEND': 'django.template.backends.django.DjangoTemplates',
        'DIRS': [BASE_DIR / 'templates'],  # <- update this
        # other templates removed to save space
    },
]

While we’re still in the settings.py file, let’s add the following settings to the end

# D.I.R.T Stack Settings

INERTIA_LAYOUT = 'base.html'

# We need this for django form posting
CSRF_HEADER_NAME = 'HTTP_X_XSRF_TOKEN'
CSRF_COOKIE_NAME = 'XSRF-TOKEN'

# Where ViteJS assets are built.
DJANGO_VITE_ASSETS_PATH = BASE_DIR / 'react-app' / 'dist'

# If we should use HMR or not.
DJANGO_VITE_DEV_MODE = DEBUG

# we need this to get around cors issues
DJANGO_VITE_DEV_SERVER_HOST = '127.0.0.1'

# this is the default, but I'm leaving this here, so you know what to change if you want to run on a different port
DJANGO_VITE_PORT = 3000

# Name of our static files' folder (after called python manage.py collectstatic)
STATIC_ROOT = BASE_DIR / 'static'

# Include DJANGO_VITE_ASSETS_PATH into STATICFILES_DIRS to be copied inside
# when run command python manage.py collectstatic
STATICFILES_DIRS = [DJANGO_VITE_ASSETS_PATH]

Let’s get our initial django-vite setup going

ℹ️ We will be using pnpm for this project. That being said, you may use npm or yarn if you’d like. For installation instructions for pnpm click here.

At the root of our project, let’s create our package.json

pnpm init

Install Vite 🚀 and Prettier

pnpm i -D vite prettier

Create a .prettierrc.json at the root of our project with the following content (minimal)

{
  "semi": true,
  "singleQuote": true,
  "tabWidth": 2,
  "trailingComma": "es5"
}

Create vite.config.js at the root of our project with the following content

import { resolve }  from 'path';

module.exports = {
 plugins: [],
 root: resolve('./react-app'),
 base: '/static/',
 server: {
   host: 'localhost',
   port: 3000,
   open: false,
   watch: {
     usePolling: true,
     disableGlobbing: false,
   },
 },
 resolve: {
   extensions: ['.js', '.json'],
 },
 build: {
   outDir: resolve('./react-app/dist'),
   assetsDir: '',
   manifest: true,
   emptyOutDir: true,
   target: 'es2015',
   rollupOptions: {
     input: {
       main: resolve('./react-app/src/main.js'),
     },
     output: {
       chunkFileNames: undefined,
     },
   },
 },
};

create the folder ./react-app/dist since this is where our built assets will eventually end up
create our main file ./react-app/src/main.js (we’ll rename this to main.jsx later as this will be our Inertia entry point)

alert('Hello DIRT Stack!');

We’re almost ready to get things going. Let’s update our package.json file so that we can run Vite

Update the scripts section our package.json as shown below

{
    "scripts": {
    "vite-build": "vite build",
    "vite-dev": "vite",
    "test": "echo \"Error: no test specified\" && exit 1"
  },
}

Create a views file ./dirt_tutorial/views.py with the following content

from django.shortcuts import render

def index(request):
    return render(request, template_name="base.html")

Update our main url pattern file ./dirt_tutorial/urls.py as follows

from django.contrib import admin
from django.urls import path
from dirt_tutorial import views  # <- this was added

urlpatterns = [
    path('', views.index, name='home'),  # <- this was added
    path('admin/', admin.site.urls),
]

Now we can test things out. Go ahead and start the Django dev server in a separate terminal and then start Vite.

./manage.py runserver

# in another terminal
pnpm run vite-dev

If everything worked, you should see the following results

✳️ This would be a good time to commit the changes and prepare to move on to the next section. You can also merge these changes into the main branch.

React (Vite Setup)

We’re now at the point where we can add in React and the frontend part for InertiaJS. Let’s go ahead and get set up.

Create a new branch

git checkout -b setup-react

ℹ️ If you have Vite running, now would be a good time to stop it.

Install the dependencies for React

pnpm i -D react react-dom @vitejs/plugin-react

Install the dependencies for TypeScript

pnpm i -D typescript ts-loader @types/react @types/react-dom

Install InertiaJS

pnpm i -D @inertiajs/react

Create a tsconfig.json file in the root of our project and copy the contents below

{
 "compilerOptions": {
   "target": "ESNext",
   "useDefineForClassFields": true,
   "lib": ["DOM", "DOM.Iterable", "ESNext"],
   "allowJs": false,
   "skipLibCheck": true,
   "esModuleInterop": false,
   "allowSyntheticDefaultImports": true,
   "strict": true,
   "forceConsistentCasingInFileNames": true,
   "module": "ESNext",
   "moduleResolution": "Node",
   "resolveJsonModule": true,
   "isolatedModules": true,
   "noEmit": true,
   "jsx": "react-jsx",
   "types": ["vite/client"],
 },
 "include": ["react-app/src"],
}

Update our vite.config.js file to work with React

import { resolve } from 'path';
import react from '@vitejs/plugin-react';

module.exports = {
    // this was changed
  plugins: [
    react({
      include: '**/*.disabled',
    }),
  ],
  root: resolve('./react-app'),
  base: '/static/',
  server: {
    host: 'localhost',
    port: 3000,
    open: false,
    watch: {
      usePolling: true,
      disableGlobbing: false,
    },
  },
  resolve: {
    extensions: ['.js', '.json'],
  },
  build: {
    outDir: resolve('./react-app/dist'),
    assetsDir: '',
    manifest: true,
    emptyOutDir: true,
    target: 'es2015',
    rollupOptions: {
      input: {
        main: resolve('./react-app/src/main.jsx'), // <- renamed from main.js
      },
      output: {
        chunkFileNames: undefined,
      },
    },
  },
};

Before we make our changes to main.js, we’ll need to make our index page which will be imported into our main file.

Create our Index component ./react-app/src/pages/Home/Index.tsx with the content below (or anything you want to use)

import * as React from 'react';

const Index = (): React.ReactNode => {
  return (
    <div>
      <h1>D.I.R.T Stack Tutorial</h1>
      <p>The D.I.R.T Stack consists of 4 major pieces</p>
      <ul>
        <li><strong>D</strong>jango</li>
        <li><strong>I</strong>nertia</li>
        <li><strong>R</strong>eact</li>
        <li><strong>T</strong>ailwind CSS</li>
      </ul>
    </div>
  )
}

export default Index;

Rename main.js to main.jsx and update the contents as follows

import {createRoot} from 'react-dom/client';
import {createInertiaApp} from '@inertiajs/react';

document.addEventListener('DOMContentLoaded', () => {
  createInertiaApp({
    resolve: (name) => {
      const pages = import.meta.glob('./pages/**/*.tsx', { eager: true });
      return pages[`./pages/${name}.tsx`];
    },
    setup({ el, App, props }) {
      createRoot(el).render(<App {...props} />);
    }
  }).then(() => {});
});

This should cover the React side of things, for now at least. Let’s look at setting up the Django side of things so we can have our view rendered.

Update ./dirt_tutorial/views.py as follows

# from django.shortcuts import render  # <- remove this
from inertia import inertia  # <- add this

@inertia('Home/Index')  # <- add this
def index(request):
        # return render(request, template_name="base.html")  # <- remove this
        return {}  # <- add this

Edit ./templates/base.html to point to our newly renamed main.jsx file

{% load django_vite %}
<!DOCTYPE html>
<html lang="en">
    <head>
        <meta charset="UTF-8">
        <meta name="viewport" content="width=device-width, initial-scale=1"/>
        <!-- vite hmr -->
        {% vite_hmr_client %}
        {% vite_asset 'src/main.jsx' %} <!-- rename main.js to main.jsx -->
        <title>D.I.R.T Stack - Django Inertia React Tailwind CSS</title>
    </head>
    <body>
        <!-- inertia -->
        {% block inertia %}{% endblock %}
    </body>
</html>

At this point, we can go ahead and make sure things are working.

Start both the Django dev server and Vite and navigate to http://127.0.0.1:8000

ℹ️ You should see something like the window below without any console errors. If you do, have a 🍪 or a 🍺.

Commit your changes and merge them into main.

Tailwind CSS setup

We’re at the final part of setting up the D.I.R.T Stack. So, let’s take care of all styling needs for this project.

Stop Vite and then create a new branch
Install tailwindscss and recommended dependencies along with concurrently

pnpm i -D tailwindcss postcss autoprefixer concurrently

Initialize tailwind css

pnpx tailwindcss init -p

ℹ️ Be sure to add the generated files (postcss.config.js and tailwind.config.js) to version control

Update the generated tailwind config tailwind.config.js as follows

/** @type {import('tailwindcss').Config} */
module.exports = {
  content: ['./templates/**/*.html', './react-app/src/**/*.{js,jsx,ts,tsx}'],
  theme: {
    extend: {},
  },
  plugins: [],
};

Create a static directory at the root of the project
Create our main CSS file ./static/css/main.css and add the following

@tailwind base;
@tailwind components;
@tailwind utilities;

update package.json to include a script that will run tailwindcss and vite via concurrently

"scripts": {
  "vite-build": "vite build",
  "vite-dev": "vite",
  "tailwind-dev": "tailwindcss -i ./static/css/main.css -o ./static/dist/css/app.css --watch",
  "dirt-dev": "concurrently \"npm run tailwind-dev\" \"npm run vite-dev\" ",
  "test": "echo \"Error: no test specified\" && exit 1"
},

Update our settings.py file so that we can serve our static files

# Name of our static files' folder (after called python manage.py collectstatic)
# STATIC_ROOT = BASE_DIR / 'static'  # <- remove this

# Include DJANGO_VITE_ASSETS_PATH into STATICFILES_DIRS to be copied inside
# when run command python manage.py collectstatic
STATICFILES_DIRS = [
    BASE_DIR / 'static',
    DJANGO_VITE_ASSETS_PATH
]

Update our base template ./templates/base.html to include the link to generated CSS.

{% load static %}
{% load django_vite %}
<!DOCTYPE html>
<html lang="en">
    <head>
        <meta charset="UTF-8">
        <meta name="viewport" content="width=device-width, initial-scale=1"/>
        <!-- css -->
        <link rel="stylesheet" href="{% static 'dist/css/app.css' %}" />
        <!-- vite hmr -->
        {% vite_hmr_client %}
        {% vite_asset 'src/main.jsx' %}
        <title>D.I.R.T Stack - Django Inertia React Tailwind CSS</title>
    </head>
    <body>
        <!-- inertia -->
        {% block inertia %}{% endblock %}
    </body>
</html>

run our newly added script via pnpm

pnpm run dirt-dev

✅ Should work without issues

Edit our Index component ./react-app/src/page/Home/Index.tsx to include some Tailwind CSS classes

import * as React from 'react';
const Index = (): React.ReactNode => {
  return (
    <div className="flex flex-col gap-y-4 p-2">
      <h1 className="text-blue-800 text-4xl">D.I.R.T Stack Tutorial</h1>
      <div className="bg-blue-100 border-blue-800 border-2 flex flex-col p-4 rounded">
        <p className="text-blue-800 text-lg">The D.I.R.T Stack consists of 4 major pieces</p>
      </div>
      <ul className="text-2xl">
        <li><span className="font-semibold">D</span>jango</li>
        <li><span className="font-semibold">I</span>nertia</li>
        <li><span className="font-semibold">R</span>eact</li>
        <li><span className="font-semibold">T</span>ailwind CSS</li>
      </ul>
    </div>
  )
}

export default Index;

Not bad so far, right? So, in summary here’s a rundown of what we have done so far

Setup a base Django project
Setup Inertia
Setup React with Vite
Install and configure Tailwind CSS
At this point, we can go ahead and commit our changes so that we can proceed to the next section.

Bonus: Storybook Integration (Experimental)

Now, you guys know I am a fan of tools that allow for the previewing of components as we build them.

We’ll be using Storybook which is one of my favorite tools. For more information about Storybook, click here. And with the integration of Storybook, we can call this D.I.R.T+.

⚠️ Important Note: For Storybook to work with our D.I.R.T Stack, do not use the installation instructions provided by Storybook as our project does not conform to a typical structure.

Storybook Manual Setup

To get Storybook working, a manual setup is required. The steps are below

Create a new branch for this section
Install the dependencies

# storybook manual setup

# add dependencies via PNPM or NPM or Yarn
pnpm add -D @storybook/builder-vite @storybook/react @storybook/client-api @storybook/client-logger
@storybook/addon-links @storybook/addon-essentials @storybook/addon-docs 
@storybook/addon-actions @storybook/addon-backgrounds @storybook/addon-measure 
@storybook/addon-outline @babel/core@^7.0.0

Create a Storybook config file .storybook/main.js at the root of the project and paste the following

// .storybook/main.js

module.exports = {
  stories: [
    '../react-app/src/**/*.stories.mdx',
    '../react-app/src/**/*.stories.@(js|jsx|ts|tsx)',
  ],
  addons: ['@storybook/addon-links', '@storybook/addon-essentials'],
  core: {
    builder: '@storybook/builder-vite',
  },
};

Create a preview file for Storybook ./storybook/preview.js

import "../static/dist/css/app.css";

export const parameters = {
  actions: { argTypesRegex: "^on[A-Z].*" },
  controls: {
    matchers: {
      color: /(background|color)$/i,
      date: /Date$/,
    },
  },
}

Update package.json to include a script to start Storybook.

{
    "scripts": {
        /* other scripts removed to save space. copy line below */
        "storybook": "start-storybook -p 6006"
    }
}

main.js created showing contents

ℹ️ Storybook CLI reference

Run storybook via pnpm

pnpm run storybook

ℹ️ If everything worked, then a new browser tab should open with StoryBook. At this point, since we don’t have any stories, we will be greeted with a message telling us that we don’t have any stories.

You’ll notice that Storybook isn’t too happy with us since we have no stories defined. So we’ll have to fix that. Let’s proceed.

Creating our first story

At this point, we can create stories based on components. For this, we will create a few components and the accompanying story files.

Before we do that, let’s get a few things installed.

Install headlessui via pnpm.

pnpm add -d @headlessui/react

Create a Button component ./react-app/src/components/shared/Button/Button.tsx

import * as React from 'react';
import type { FC, ButtonHTMLAttributes } from 'react';

interface ButtonProps extends ButtonHTMLAttributes<HTMLButtonElement> {
  labelText: string;
  overrideButtonClass?: string;
}

export const Button: FC<ButtonProps> = ({
  labelText,
  overrideButtonClass,
  ...props
}) => {
  return (
    <button
      className={[
        'px-4 py-2 bg-green-800 hover:bg-green-600 text-white text-lg rounded duration-200',
        overrideButtonClass,
      ].join(' ')}
      {...props}
    >
      {labelText}
    </button>
  );
};

Create the corresponding Storybook file adjacent to the Button component Button.stories.tsx

import type {ComponentMeta, ComponentStory} from '@storybook/react';
import {Button} from './Button';

export default {
  title: 'Shared/Button',
  component: Button,
} as ComponentMeta<typeof Button>;

const Template: ComponentStory<typeof Button> = args => <Button {...args} />;

export const Primary = Template.bind({});
Primary.args = {
  labelText: 'Primary Button',
}

We should see our newly created Button story file as shown below

Create a Confirm Dialog component ./react-app/src/components/shared/ConfirmDialog/ConfirmDialog.tsx

import * as React from 'react';
import type { FC } from 'react';
import { Dialog } from '@headlessui/react';
import { Button } from '../Button/Button';

interface ConfirmDialogProps {
  cancelAction: () => void;
  confirmAction: () => void;
  dialogTitle: string;
  overrideCancelText?: string;
  overrideConfirmText?: string;
  promptText: string;
  titleText: string;
  visible: boolean;
}

export const ConfirmDialog: FC<ConfirmDialogProps> = ({
  overrideConfirmText,
  overrideCancelText,
  promptText,
  titleText,
  confirmAction,
  visible,
  cancelAction,
}) => {
  return (
    <Dialog onClose={cancelAction} open={visible}>
      <div className="fixed inset-0 bg-black/30" aria-hidden="true" />
      <div className="fixed inset-0 flex items-center justify-center p-4">
        <Dialog.Panel className="mx-auto max-w-sm rounded bg-white p-4 rounded">
          <div className="flex flex-col items-center">
            <Dialog.Title className="font-normal text-2xl text-slate-600 ml-0">
              {titleText}
            </Dialog.Title>
          </div>
          <div className="mt-2">
            <p className="text-center text-lg text-slate-600">{promptText}</p>
          </div>
          <div className="flex flex-1 flex-col mt-6 items-center">
            <div className="flex gap-x-2">
              <Button
                onClick={cancelAction}
                overrideButtonClass="bg-slate-800 hover:bg-slate-500"
                labelText={overrideCancelText ? overrideCancelText : 'Cancel'}
              />
              <Button
                onClick={confirmAction}
                labelText={
                  overrideConfirmText ? overrideConfirmText : 'Confirm'
                }
              />
            </div>
          </div>
        </Dialog.Panel>
      </div>
    </Dialog>
  );
};

Create the corresponding Storybook file adjacent to Confirm Dialog component ConfirmDialog.stories.tsx

import type { ComponentMeta, ComponentStory } from '@storybook/react';
import { ConfirmDialog } from './ConfirmDialog';

export default {
  title: 'Shared/ConfirmDialog',
  component: ConfirmDialog,
} as ComponentMeta<typeof ConfirmDialog>;

const Template: ComponentStory<typeof ConfirmDialog> = (args) => (
  <ConfirmDialog {...args} />
);

export const Primary = Template.bind({});
Primary.args = {
  visible: false,
  promptText: 'You are about to do the thing, would you like to continue?',
  titleText: 'Do the thing?',
  cancelAction: () => {},
  confirmAction: () => {},
};

We should see our newly created Confirm Dialog story below

If everything worked, then we can celebrate 🎉. This concludes the D.I.R.T+ Stack setup with Storybook.

⚠️ Currently there is an issue with Storybook that requires the page to be reloaded manually. So, if you see something that looks like the screen below when adding a new story file, just reload it (for now). I’m looking for a solution to this issue.

# The error as it is.
Cannot overwrite a zero-length range – use appendLeft or prependRight instead
9:49:26 PM [vite] Internal server error: Cannot overwrite a zero-length range – use appendLeft or prependRight instead

References:

The following resources were helpful in the writing of this:

What's next?

I have things related to D.I.R.T that I'm working on (starter template, etc). Stay tuned for updates. Also, I'm going to be refining the approach and optimizing a few things

Django, InertiaJs and React (Vite) - A guide to get you started Pt. 2

Simon (Sai) — Sat, 28 Jan 2023 17:47:19 +0000

⚠️ The first part of this tutorial is based on InertiaJs prior to version 1.0. Towards the end of this tutorial, we will tackle upgrading InertiaJs.

This is Part 2 of our Django, InertiaJs & React/Vite tutorial. If you have not looked at Part 1, I would recommend that you check it out here.

ℹ️ To make it easier for you to pick up where we left off or to make sure your project is in working order before we proceed, check out the repo here. Be sure to check the readme before continuing.

In this part of the tutorial series, we are going to be looking at a few things:

Integrating TypeScript
Installing Material UI (you can use any component library you want)
Implementing the contact app
- Backend
- models, views
- Frontend
- Pages and components
Upgrading InertiaJs to 1.0

Let's get to it, shall we?

⚠️ You may see an error running the project on (MacOS) after cloning the repo that looks like zsh: permission denied: ./manage.py, you will need to change the permission on that file by using chmod.

# Review the contents of any file that you are going to make executable before making it executable
chmod +x manage.py

The manage.py file should look like what is below

#!/usr/bin/env python
"""Django's command-line utility for administrative tasks."""
import os
import sys


def main():
    """Run administrative tasks."""
    os.environ.setdefault('DJANGO_SETTINGS_MODULE', 'contact_manager.settings')
    try:
        from django.core.management import execute_from_command_line
    except ImportError as exc:
        raise ImportError(
            "Couldn't import Django. Are you sure it's installed and "
            "available on your PYTHONPATH environment variable? Did you "
            "forget to activate a virtual environment?"
        ) from exc
    execute_from_command_line(sys.argv)


if __name__ == '__main__':
    main()

Optional: Installing Prettier (It just makes sense)

Installing Prettier is optional, but still a pretty good idea 😏. So let's do that and set it up before proceeding.

Install it using the command below

npm i -D prettier

Create a prettier configuration file .prettierrc.json in the root of the project and copy and paste the content below (minimal prettier configuration)

{
  "semi": true,
  "singleQuote": true,
  "tabWidth": 2,
  "trailingComma": "es5"
}

Depending on your editor or IDE, you may need to tell it to use Prettier.

Integrating TypeScript

Now that we have a working project, let's make it even better with TypeScript. Adding TypeScript is going to make our lives easier in the long run, so let's add it now.

Create a branch from main, we'll call it part-2-ts-and-forms or anything you want

git checkout -b part-2-integrating-ts-and-forms

Install dependencies (as dev dependences) via npm

# install dev dependencies
npm i -D ts-loader typescript @types/react @types/react-dom

Initialise TypeScript with some presets

npx tsc --init

Replace the contents of the generated tsconfig.json file with what is shown below

{
 "compilerOptions": {
   "target": "ESNext",
   "useDefineForClassFields": true,
   "lib": ["DOM", "DOM.Iterable", "ESNext"],
   "allowJs": false,
   "skipLibCheck": true,
   "esModuleInterop": false,
   "allowSyntheticDefaultImports": true,
   "strict": true,
   "forceConsistentCasingInFileNames": true,
   "module": "ESNext",
   "moduleResolution": "Node",
   "resolveJsonModule": true,
   "isolatedModules": true,
   "noEmit": true,
   "jsx": "react-jsx",
   "types": ["vite/client"],
 },
 "include": ["react-app/src"],
}

Don't forget to add the tsconfig.json file to version control (if you're using git)
Change the extensions of all our .jsx files to .tsx with the exception of main.jsx
Rename react-app/src/pages/Home/index.jsx to end with .tsx
- Modify our home component to add the necessary interface as shown below

interface HomePageProps {
  contacts: string[];
}

export default function Home({ contacts }: HomePageProps) {
  return (
    <div>
      <h1>Contact List</h1>
      {Array.isArray(contacts) && contacts.length ? (
        <ul>
          {contacts.map((contact) => (
            <li key={contact}>{contact}</li>
          ))}
        </ul>
      ) : (
        <p>No contacts yet...</p>
      )}
    </div>
  );
}

ℹ️ We will replace the contents of this file with something else eventually but, for right now, we don't want TypeScript to complain

Rename react-app/src/components/Layout.jsx to end with .tsx
- Modify the layout component to add the necessary interface as shown below

import React from 'react';
import type { FC } from 'react';

interface LayoutProps {
  children: React.ReactNode;
}

const Layout: FC<LayoutProps> = ({ children }) => {
  return (
    <main>
      <div>{children}</div>
    </main>
  );
};

export default (page: React.ReactNode | React.ReactElement) => (
  <Layout>{page}</Layout>
);

Update our main.jsx component as follows

// change this line
const pages = import.meta.glob('./pages/**/*.jsx');
// to
const pages = import.meta.glob('./pages/**/*.tsx');

// change this line
const page = (await pages[`./pages/${name}.jsx`]()).default;
// to
const page = (await pages[`./pages/${name}.tsx`]()).default;

ℹ️ We will be revisiting the converting of main.jsx to TypeScript in the upgrade to InertiaJs v1.0 section

Re-run vite via npm run dev along with the Django dev server via ./manage.py runserver and navigate to http://127.0.0.1:8000 and you shouldn't see any errors in the browser console

Implementing the Contact Manager

We're now at the point where we can implement our contact manager application. Keep in mind that this is a somewhat-simplified example web application. We will be skipping authentication to keep this part short. (In a future Django/InertiaJs project, we'll build something more complicated complete with auth) We will need have a way to manage contacts and notes for each contact. Let's do some Django things.

Models
- Each model we create will have the these common fields
- Created At
- Updated At
- Model: Contact - For each contact, we will want to keep track of the following items
- First name
- Last name
- Middle Name
- Email Address
- Phone Number
Create our contact app using django admin as follows

django-admin startapp contact

If you're using git, go ahead and add all files from the contact app we just created to git
Let's also add our newly created contact app to INSTALLED_APPS so that Django can 'see' it 👀 in settings.py

INSTALLED_APPS = [
    'django.contrib.admin',
    'django.contrib.auth',
    'django.contrib.contenttypes',
    'django.contrib.sessions',
    'django.contrib.messages',
    'django.contrib.staticfiles',
    # django InertiaJS apps
    'django_vite',
    'inertia',
    # our apps
    'contact' # <- this line was added
]

Let's define our models in our model file called...well, models.py located at contact/models.py

import datetime

from django.db import models


# Create your models here.

class AppModel(models.Model):
    """
    We are using this as an abstract model so that we can define and reuse common fields across models
    """
    created_at = models.DateTimeField(default=datetime.datetime.utcnow)
    updated_at = models.DateTimeField(blank=True, null=True)

    class Meta:
        abstract = True


class Contact(AppModel):
    first_name = models.CharField(max_length=50)
    middle_name = models.CharField(blank=True, max_length=50, null=True)
    last_name = models.CharField(max_length=50)
    email_address = models.EmailField(max_length=200)
    phone_number = models.CharField(max_length=20)

    def __str__(self):
        return f'({self.id}) {self.first_name} {self.last_name}'


class ContactNote(AppModel):
    contact = models.ForeignKey('Contact', on_delete=models.CASCADE, related_name='ContactNoteOwner')
    content = models.TextField()

    def __str__(self):
        return f'({self.id}) Note for {self.contact.first_name} {self.contact.last_name}'

With our models created, we can run our migration (this will get rid of the unapplied migrations warning)

# *nix or Mac OS
./manage.py makemigrations
./manage.py migrate
# windows
manage.py makemigrations
manage.py migrate

ℹ️ While we have created a ContactNote model. I'll leave that up to you to make use of or I can do a Part 2.5 to this guide which covers that.

Django Admin

Let's detour a bit and set up our Django admin so that we can easily create some test data for our application

Create the django super user account by running the command below

./manage.py createsuperuser

Fill out the information asked in the prompts. Once done, it should say that the superuser was created successfully.

ℹ️ If you want to see all the commands available, you can just run ./manage.py

Let's make sure things are working correctly by running the django dev server and navigating to http://127.0.0.1:8000/admin. You should see something like image below

Let's register our models so that they also show up in the Django's admin interface by modifying the file contact/admin.py

from django.contrib import admin
from contact import models # There are other ways to do the model imports

# Register your models here.


@admin.register(models.Contact)
class ContactAdmin(admin.ModelAdmin):
    pass


@admin.register(models.ContactNote)
class ContactNoteAdmin(admin.ModelAdmin):
    pass

Reload the django admin interface and you should now see our models

Go ahead and create some contact and some notes via the admin interface and then we can get back to the fun stuff.
Let's make a slight change to add a nick_name field to our contact model

class Contact(AppModel):
    first_name = models.CharField(max_length=50)
    middle_name = models.CharField(blank=True, max_length=50, null=True)
    last_name = models.CharField(max_length=50)
    nickname = models.CharField(blank=True, max_length=50, null=True) # <- we added this
    email_address = models.EmailField(max_length=200, unique=True)
    phone_number = models.CharField(max_length=20, unique=True)

    def __str__(self):
        return f'({self.id}) {self.first_name} {self.last_name}'

Let's make migrations and then apply them

./manage.py makemigrations
./manage.py migrate

Let's set up our model forms which we will use later for validation by creating the file contact/forms.py

from django.forms import ModelForm
from contact.models import Contact, ContactNote

# We are letting Django's model forms do the work for us. We are only scratching the surface of what can be done with Model forms.


class ContactForm(ModelForm):
    """
    Model form used for just validating our data since we're sending data via InertiaJS
    """
    class Meta:
        model = Contact
        exclude = ['created_at', 'updated_at']


class ContactNoteForm(ModelForm):
    """
    Model form used for just validating our data since we're sending data via InertiaJS
    """
    class Meta:
        model = ContactNote
        exclude = ['created_at', 'updated_at']

ℹ️ By specifying exclude, we are telling the model form to use all fields but exclude the ones specified. For more information on Django Model Forms, click here.

Let's work on a way to get our data from our database by creating a file called dataSource.py. We are keeping things simple here to keep the focus on InertiaJs.

import datetime

from contact.models import Contact, ContactNote
from contact.forms import ContactForm, ContactNoteForm


def get_contact_summary():
    """
    Retrieves the count of contacts and contact notes
    """
    try:
        total_contacts = Contact.objects.count()
    except Exception as err:
        total_contacts = 0

    try:
        total_notes = ContactNote.objects.count()
    except Exception as err:
        total_notes = 0

    return {
        'totalContacts': total_contacts,
        'totalNotes': total_notes,
    }

# we'll add more to this later

Let's make some changes to our index view in contact_manager.views so that we can have our contact summary displayed

from inertia import inertia

from contact.dataSource import get_contact_summary


@inertia('Home/Index')
def index(request):
    return {
        'summary': get_contact_summary()
    }

Next, we'll modify the corresponding component to show our summary and to make sure things are working. I opted to rewrite the component, but it still works the same way

import { FC } from 'react';

interface HomePageProps {
  summary: {
    totalContacts: number;
    totalNotes: number;
  };
}

const HomeIndex: FC<HomePageProps> = ({ summary }) => {
  return (
    <div>
      <h1>Contact Summary</h1>
      <div>
        <div>
          <h2>{summary.totalContacts}</h2>
          <p>Total Contacts</p>
        </div>
        <div>
          <h2>{summary.totalNotes}</h2>
          <p>Total Contact Notes</p>
        </div>
      </div>
    </div>
  );
};

export default HomeIndex;

Now would be a pretty good time to get some styling setup. We'll be using MUI React because we're efficient like that.

Let's install Material UI

npm i -D @mui/material @emotion/react @emotion/styled @fontsource/roboto

Let's restructure our Home/Index.tsx component so it looks somewhat presentable
We will create a card component so we can display information on the home page nicely components/MetricCard.tsx

import React from 'react';
import type {FC} from 'react';
import { Card, CardActions, CardContent, Typography } from '@mui/material';

interface MetricCardProps {
  actions?: React.ReactElement;
  label: string;
  value: number | string;
}

export const MetricCard: FC<MetricCardProps> = ({ actions, label, value }) => {
  return (
    <Card variant="outlined">
      <CardContent>
        <Typography sx={{ fontSize: 80 }} variant="body1">
          {value}
        </Typography>
        <Typography sx={{ fontSize: 20 }} variant="h2">
          {label}
        </Typography>
      </CardContent>
      {actions && <CardActions>{actions}</CardActions>}
    </Card>
  );
};

Let's update Home/Index.tsx

import { FC } from 'react';
import { Inertia } from '@inertiajs/inertia';
import { Box, Button, Grid, Typography } from '@mui/material';
import { MetricCard } from '../../components/MetricCard';

interface HomePageProps {
  summary: {
    totalContacts: number;
    totalNotes: number;
  };
}

const HomeIndex: FC<HomePageProps> = ({ summary }) => {
  return (
    <Box sx={{ flexGrow: 1 }}>
      <Typography variant="h2">Contact Summary</Typography>
      <Typography variant="body1">
        Here's a summary of your contact list and notes
      </Typography>
      <Box sx={{ flexGrow: 1 }}>
        <Grid container direction="row" spacing={1}>
          <Grid item xs={12} md={6}>
            <MetricCard
              actions={
                <>
                  <Button variant="outlined">Add New Contact</Button>{' '}
                  <Button
                    onClick={() => Inertia.visit('/contact')}
                    variant="outlined"
                  >
                    View all Contacts
                  </Button>{' '}
                </>
              }
              label="Total Contacts"
              value={summary.totalContacts}
            />
          </Grid>
          <Grid item xs={12} md={6}>
            <MetricCard
              actions={
                <>
                  <Button variant="outlined">View all notes</Button>{' '}
                </>
              }
              label="Total Notes"
              value={summary.totalNotes}
            />
          </Grid>
        </Grid>
      </Box>
    </Box>
  );
};

export default HomeIndex;

Let's add some icons via NPM

npm install -D @mui/icons-material

Let's update our layout file components/Layout.tsx

import React from 'react';
import type { FC } from 'react';
import { AppBar, Container, Toolbar, Typography } from '@mui/material';
import ContactsIcon from '@mui/icons-material/Contacts';

interface LayoutProps {
  // For our purposes, ReactNode will be fine.
  children: React.ReactNode;
}

const Layout: FC<LayoutProps> = ({ children }) => {
  return (
    <main>
      <AppBar position="static">
        <Container maxWidth="xl">
          <Toolbar disableGutters>
            <ContactsIcon sx={{ display: { xs: 'none', md: 'flex' }, mr: 1 }} />
            <Typography
              variant="h6"
              noWrap
              component="a"
              href="/"
              sx={{
                mr: 2,
                display: { xs: 'none', md: 'flex' },
                fontFamily: 'monospace',
                fontWeight: 700,
                letterSpacing: '.15rem',
                color: 'inherit',
                textDecoration: 'none',
              }}
            >
              Contact Manager - InertiaJs
            </Typography>
          </Toolbar>
        </Container>
      </AppBar>
      <div>{children}</div>
    </main>
  );
};

export default (page: React.ReactNode | React.ReactElement) => (
  <Layout>{page}</Layout>
);

Now we're getting somewhere. Let's press on 👍

Let's work on our contact list functionality by editing the contact/views.py

from django.shortcuts import redirect
from inertia import inertia

from contact import dataSource


@inertia('Contact/Listing')
def contacts(request):
    return dataSource.get_contacts()

Because we're doing things the typescript way, let's create an interface based on Contact model in react-app/src/interfaces/contact.interface.ts

export interface Contact {
  id: number;
  first_name: string;
  middle_name?: string;
  last_name: string;
  nickname?: string;
  email_address: string;
  phone_number: string;
}

Let's create our contact listing react-app/src/pages/Contact/Listing.tsx

import React from 'react';
import type { FC } from 'react';
import {
  Box,
  Divider,
  IconButton,
  List,
  ListItem,
  ListItemIcon,
  ListItemText,
} from '@mui/material';
import {
  DeleteForeverOutlined as DeleteIcon,
  EditRounded as EditIcon,
  InfoOutlined as InfoIcon,
  Person2Rounded as PersonIcon,
} from '@mui/icons-material';

import type { Contact } from '../../interfaces/contact.interface';

interface ListingProps {
  contacts: Contact[];
}

const Listing: FC<ListingProps> = ({ contacts }) => {
  return (
    <List sx={{ width: '100%' }}>
      {contacts.map((contact, index) => (
        <Box key={`item-${index}`}>
          {index ? <Divider /> : null}
          <ListItem
            key={`contact-${contact.id}`}
            alignItems="center"
            secondaryAction={
              <>
                <IconButton>
                  <InfoIcon />
                </IconButton>
                <IconButton>
                  <EditIcon />
                </IconButton>
                <IconButton>
                  <DeleteIcon />
                </IconButton>
              </>
            }
          >
            <ListItemIcon>
              <PersonIcon />
            </ListItemIcon>
            <ListItemText
              primary={`${contact.first_name} ${contact.last_name}`}
              secondary={contact.phone_number}
            />
          </ListItem>
        </Box>
      ))}
    </List>
  );
};

export default Listing;

Not too shabby for our listing. Of course, you are free to go for maximum style points if you'd like

Since we're looking at our listing, let's take this time to create a contact info modal component react-app/src/components/ContactInfoDialog.tsx

import type { FC } from 'react';
import {
  Button,
  Dialog,
  DialogActions,
  DialogContent,
  DialogTitle,
  Grid,
  ListItemText,
} from '@mui/material';
import { Close as CloseIcon, Edit as EditIcon } from '@mui/icons-material';

import type { Contact } from '../interfaces/contact.interface';

interface ContactInfoDialogProps {
  contact?: Contact;
  onClose: () => void;
  onEdit: () => void;
  open: boolean;
}

export const ContactInfoDialog: FC<ContactInfoDialogProps> = ({
  contact,
  onClose,
  onEdit,
  open,
}) => {
  return (
    <Dialog fullWidth maxWidth="sm" onClose={onClose} open={open}>
      <DialogTitle>Contact Information</DialogTitle>
      <DialogContent>
        <Grid container spacing={1}>
          <Grid item xs={4}>
            <ListItemText
              primary={contact?.first_name}
              secondary="First Name"
            />
          </Grid>
          <Grid item xs={4}>
            <ListItemText
              primary={contact?.middle_name || 'N/A'}
              secondary="Middle Name"
            />
          </Grid>
          <Grid item xs={4}>
            <ListItemText primary={contact?.last_name} secondary="Last Name" />
          </Grid>
          <Grid item xs={12}>
            <ListItemText
              primary={contact?.nickname || 'N/A'}
              secondary="Nickname / Alias"
            />
          </Grid>
          <Grid item xs={6}>
            <ListItemText
              primary={contact?.email_address}
              secondary="Email Address"
            />
          </Grid>
          <Grid item xs={6}>
            <ListItemText
              primary={contact?.phone_number}
              secondary="Phone Number"
            />
          </Grid>
        </Grid>
      </DialogContent>
      <DialogActions>
        <Button onClick={onEdit} startIcon={<EditIcon />}>
          Edit Contact
        </Button>
        <Button onClick={onClose} startIcon={<CloseIcon />}>
          Close
        </Button>
      </DialogActions>
    </Dialog>
  );
};

We'll need to edit our listing react-app/src/pages/Contact/Listing.tsx so that we can use the newly created dialog

// modified react import
import React, { useCallback, useMemo, useState } from 'react';
import type { FC } from 'react';
import { Inertia } from '@inertiajs/inertia';
import {
  Box,
  Divider,
  Fab,
  IconButton,
  List,
  ListItem,
  ListItemIcon,
  ListItemText,
} from '@mui/material';
import {
  AddCircleOutlineRounded as AddIcon,
  DeleteForeverOutlined as DeleteIcon,
  EditRounded as EditIcon,
  InfoOutlined as InfoIcon,
  Person2Rounded as PersonIcon,
} from '@mui/icons-material';

import type { Contact } from '../../interfaces/contact.interface';
import { ContactInfoDialog } from '../../components/ContactInfoDialog';

interface ListingProps {
  contacts: Contact[];
}

const Listing: FC<ListingProps> = ({ contacts }) => {
  const [selectedContactId, setSelectedContactId] = useState<
    number | undefined
  >();

  // this was added
  const closeContactInfoModal = useCallback(() => {
    setSelectedContactId(undefined);
  }, []);

  // this was also added - we'll use this later
  const editContact = useCallback((contactId: number) => {
    Inertia.visit(`/contact/${contactId}`);
  }, []);

  const selectedContact: Contact | undefined = useMemo(() => {
    try {
      return contacts.find((contact) => contact.id === selectedContactId);
    } catch (e) {
      return undefined;
    }
  }, [contacts, selectedContactId]);

  return (
    <>
      <List sx={{ width: '100%' }}>
        {contacts.map((contact, index) => (
          <Box key={`item-${index}`}>
            {index ? <Divider /> : null}
            <ListItem
              key={`contact-${contact.id}`}
              alignItems="center"
              secondaryAction={
                <>
                  <IconButton onClick={() => setSelectedContactId(contact.id)}>
                    <InfoIcon />
                  </IconButton>
                  <IconButton onClick={() => editContact(contact.id)}>
                    <EditIcon />
                  </IconButton>
                  <IconButton>
                    <DeleteIcon />
                  </IconButton>
                </>
              }
            >
              <ListItemIcon>
                <PersonIcon />
              </ListItemIcon>
              <ListItemText
                primary={`${contact.first_name} ${contact.last_name}`}
                secondary={contact.phone_number}
              />
            </ListItem>
          </Box>
        ))}
      </List>
      <ContactInfoDialog
        contact={selectedContact}
        onClose={closeContactInfoModal}
        onEdit={
            // we'll use this when we're ready to edit contacts
          selectedContact ? () => editContact(selectedContact.id) : () => {}
        }
        open={!!selectedContact}
      />
      <Fab
        color="primary"
        onClick={() => Inertia.visit('/contact/add')}
        sx={{ bottom: 20, position: 'absolute', right: 20 }}
      >
        <AddIcon />
      </Fab>
    </>
  );
};

export default Listing;

Not bad at all for our contact information dialog, right? Let's proceed to the edit functionality and then we'll handle the delete.

We're going to have a reusable notification component, so let's implement that right now react-app/src/components/Notification.tsx

import React from 'react';
import type { FC } from 'react';
import type { AlertColor } from '@mui/material';
import { Alert, Snackbar } from '@mui/material';

interface NotificationProps {
  closeNotification: () => void;
  duration?: number;
  notificationOpen: boolean;
  notificationText: string;
  notificationType?: AlertColor;
}

export const Notification: FC<NotificationProps> = ({
  closeNotification,
  duration = 3000,
  notificationOpen,
  notificationType,
  notificationText,
}) => {
  return (
    <Snackbar
      anchorOrigin={{ vertical: 'top', horizontal: 'center' }}
      autoHideDuration={duration}
      onClose={closeNotification}
      open={notificationOpen}
    >
      <Alert
        onClose={closeNotification}
        severity={notificationType}
        variant="filled"
      >
        {notificationText}
      </Alert>
    </Snackbar>
  );
};

Let's go ahead and implement the edit contact page react-app/src/pages/Contact/ContactForm.tsx

import React, { useCallback, useEffect, useState } from 'react';
import type { FC, FormEvent } from 'react';
import { Inertia } from '@inertiajs/inertia';
import { useForm } from '@inertiajs/inertia-react';
import {
  Box,
  Button,
  Container,
  FormControl,
  FormHelperText,
  Grid,
  Input,
  InputLabel,
  Typography,
} from '@mui/material';
import type { AlertColor } from '@mui/material';
import { ContactPhone as ContactIcon } from '@mui/icons-material';
import type { Contact } from '../../interfaces/contact.interface';
import { Notification } from '../../components/Notification';

type FormData = {
  first_name: string;
  middle_name: string;
  last_name: string;
  nickname: string;
  email_address: string;
  phone_number: string;
};

const SUBMIT_RESPONSE_MESSAGES: Record<AlertColor, string> = {
  success: 'Contact information was saved',
  error: 'There was a problem with saving contact information.',
  info: '',
  warning: '',
};

interface ContactFormProps {
  contact?: Contact;
}

const ContactForm: FC<ContactFormProps> = ({ contact }) => {
  const {
    clearErrors,
    data,
    errors,
    post: createContact,
    processing,
    setData,
    put: updateContact,
  } = useForm({
    first_name: '',
    middle_name: '',
    last_name: '',
    nickname: '',
    email_address: '',
    phone_number: '',
  });

  const [contactId, setContactId] = useState<number | undefined>();
  const [notificationType, setNotificationType] = useState<AlertColor>();
  const [notificationOpen, setNotificationOpen] = useState(false);
  const [notificationText, setNotificationText] = useState('');

  useEffect(() => {
    if (contact) {
      setContactId(contact.id);
      setData({
        ...contact,
        middle_name: contact.middle_name || '',
        nickname: contact.nickname || '',
      } as FormData);
    }
  }, [contact]);

  const closeNotification = useCallback(() => {
    if (notificationType === 'success') {
      Inertia.visit('/contact');
    }
    setNotificationOpen(false);
    setNotificationText('');
  }, [notificationType]);

  const handleNotification = useCallback((notificationType: AlertColor) => {
    setNotificationType(notificationType);
    setNotificationText(SUBMIT_RESPONSE_MESSAGES[notificationType]);
    setNotificationOpen(true);
  }, []);

  const submitContactData = useCallback(
    (e: FormEvent<HTMLFormElement>) => {
      e.preventDefault();
      clearErrors();
      contact
        ? updateContact(`/contact/${contactId}/`, {
            onError: () => handleNotification('error'),
            onSuccess: () => {
              handleNotification('success');
              setTimeout(() => {
                Inertia.visit('/contact');
              }, 3000);
            },
          })
        : createContact('', {
            onError: () => handleNotification('error'),
            onSuccess: () => {
              handleNotification('success');
              setTimeout(() => {
                Inertia.visit('/contact');
              }, 3000);
            },
          });
    },
    [contactId, data]
  );

  return (
    <Container maxWidth="md" sx={{ pt: 2, width: '100%' }}>
      <Box
        sx={{
          alignItems: 'center',
          display: 'flex',
          flexDirection: 'row',
          mb: 2,
        }}
      >
        <ContactIcon fontSize="large" />
        <Typography sx={{ fontSize: 40, ml: 1 }} variant="h1">
          {contact ? 'Update' : 'Add New'} Contact
        </Typography>
      </Box>
      <form onSubmit={submitContactData}>
        <Grid container spacing={2}>
          <Grid item sm={4} xs={12}>
            <FormControl error={!!errors.first_name} fullWidth>
              <InputLabel htmlFor="first-name">First Name</InputLabel>
              <Input
                id="first-name"
                onChange={(e) => setData('first_name', e.target.value)}
                placeholder="First Name..."
                required
                value={data.first_name}
              />
              {errors.first_name ? (
                <FormHelperText sx={{ ml: 0 }}>
                  {errors.first_name}
                </FormHelperText>
              ) : null}
            </FormControl>
          </Grid>
          <Grid item sm={4} xs={12}>
            <FormControl error={!!errors.middle_name} fullWidth>
              <InputLabel htmlFor="middle-name">Middle Name</InputLabel>
              <Input
                id="middle-name"
                onChange={(e) => setData('middle_name', e.target.value)}
                placeholder="Middle Name..."
                type="text"
                value={data.middle_name}
              />
              {errors.middle_name ? (
                <FormHelperText sx={{ ml: 0 }}>
                  {errors.middle_name}
                </FormHelperText>
              ) : null}
            </FormControl>
          </Grid>
          <Grid item sm={4} xs={12}>
            <FormControl error={!!errors.last_name} fullWidth>
              <InputLabel htmlFor="last-name">Last Name</InputLabel>
              <Input
                id="last-name"
                onChange={(e) => setData('last_name', e.target.value)}
                placeholder="Last Name..."
                required
                value={data.last_name}
              />
              {errors.last_name ? (
                <FormHelperText sx={{ ml: 0 }}>
                  {errors.last_name}
                </FormHelperText>
              ) : null}
            </FormControl>
          </Grid>
          <Grid item xs={12}>
            <FormControl error={!!errors.nickname} fullWidth>
              <InputLabel>Nickname</InputLabel>
              <Input
                error={!!errors.nickname}
                id="nickname"
                onChange={(e) => setData('nickname', e.target.value)}
                placeholder="Nickname..."
                value={data.nickname}
              />
              {errors.nickname ? (
                <FormHelperText sx={{ ml: 0 }}>
                  {errors.nickname}
                </FormHelperText>
              ) : null}
            </FormControl>
          </Grid>
          <Grid item sm={6} xs={12}>
            <FormControl error={!!errors.email_address} fullWidth>
              <InputLabel htmlFor="email-address">Email Address</InputLabel>
              <Input
                id="email-address"
                onChange={(e) => setData('email_address', e.target.value)}
                placeholder="user@example.com"
                required
                type="email"
                value={data.email_address}
              />
              {errors.email_address ? (
                <FormHelperText sx={{ ml: 0 }}>
                  {errors.email_address}
                </FormHelperText>
              ) : null}
            </FormControl>
          </Grid>
          <Grid item sm={6} xs={12}>
            <FormControl error={!!errors.phone_number} fullWidth>
              <InputLabel htmlFor="phone-number">Phone Number</InputLabel>
              <Input
                id="phone-number"
                onChange={(e) => setData('phone_number', e.target.value)}
                placeholder="555-0001"
                required
                value={data.phone_number}
              />
              {errors.phone_number ? (
                <FormHelperText sx={{ ml: 0 }}>
                  {errors.phone_number}
                </FormHelperText>
              ) : null}
            </FormControl>
          </Grid>
        </Grid>
        <Box sx={{ mt: 2 }}>
          <Button
            disabled={processing}
            fullWidth
            type="submit"
            variant="contained"
          >
            {contact ? 'Update' : 'Save New'} Contact
          </Button>
        </Box>
      </form>
      <Notification
        closeNotification={closeNotification}
        notificationOpen={notificationOpen}
        notificationText={notificationText}
        notificationType={notificationType}
      />
    </Container>
  );
};

export default ContactForm;

Next, let's set up our view so that we can navigate to the contact form by editing contact/views.py

# Add the function to contact/views.py

@inertia('Contact/ContactForm')
def add_contact(request):
    if request.method == 'GET':
        return {}

    result = dataSource.upsert_contact(json.loads(request.body))
    return result

Let's update our contact urls in contact/urls.py

from django.urls import path

from contact import views

urlpatterns = [
    path('', views.contact_list, name='contact-list'),
        path('add/', views.add_contact, name='add-contact'),
]

Let's edit our listing to add a New Contact button and hook it up

// add these imports
import { Fab } from '@mui/material';
import { Inertia } from '@inertiajs/inertia';

// Add this near the bottom of the markup in the JSX 
<Fab
  color="primary"
  onClick={() => Inertia.visit('/contact/add')}
  sx={{ bottom: 20, position: 'absolute', right: 20 }}
>
  <AddIcon />
</Fab>

Let's try try navigating to our newly created contact form by clicking the FAB we added

Since we're using Django's Model Forms, we get backend validation that we can tap into. Let's try it out

ℹ️ This would be a good time to also add in some Front-end validation with whatever method you would like.

Let's try to save a contact and see what happens

Let's work on implementing the edit functionality by updating our contact/views.py file as follows

# add this to end of the file
@inertia('Contact/ContactForm')
def contact(request, pk):
    if request.method == 'GET':
        data = dataSource.get_contact(pk)
        return {
            'success': True if data is not None else False,
            'contact': data
        }

    result = dataSource.upsert_contact(json.loads(request.body), pk)
    return result

Update our urls contact/url.py file as follows

from django.urls import path

from contact import views

urlpatterns = [
    path('', views.contact_list, name='contact-list'),
    path('add/', views.add_contact, name='add-contact'),
    path('<int:pk>/', views.contact, name='contact'), # <- we added this path
]

With this in place, we should be able to click the edit button from the listing or the contact info modal and have the contact form load with details. The save button should also work since we wired that up earlier. Go ahead and try it.

Let's move on to the delete functionality as no contact manager would be complete without delete functionality.

Edit contact/dataSource.py by adding the function below to the end of the file

def delete_contact(contact_id):
    result = {
        'errors': '',
        'success': False
    }
    try:
        Contact.objects.get(contact_id).delete()
        result['success'] = True
    except Exception as err:
        result['errors'] = err.__str__()

    return result

Let's also update our views contact/views.py by adding the following code to the end of the file

def delete_contact(request, pk):
    if request.method != 'DELETE':
        return redirect('contact_list')

    result = dataSource.delete_contact(pk)
    if not result['success']:
        return result

    return redirect('contact-list')

Let's update our urls contact/urls.py so that it looks like what is below

from django.urls import path

from contact import views

urlpatterns = [
    path('', views.contact_list, name='contact-list'),
    path('add/', views.add_contact, name='add-contact'),
    path('<int:pk>/', views.contact, name='contact'),
    path('<int:pk>/delete/', views.delete_contact), # <- we added this
]

You guys might notice that I like using dialogs, so we're going to make a question dialog called QuestionDialog 😼 in our components folder. react-app/src/components/QuestionDialog.tsx

import React from 'react';
import type { FC } from 'react';

import {
  Button,
  Dialog,
  DialogActions,
  DialogContentText,
  DialogTitle,
  DialogContent,
} from '@mui/material';
import { DeleteForeverOutlined as DeleteIcon } from '@mui/icons-material';
import type { Contact } from '../interfaces/contact.interface';

interface QuestionDialogProps {
  cancelAction: () => void;
  confirmAction: () => void;
  contact?: Contact;
  open: boolean;
}

export const QuestionDialog: FC<QuestionDialogProps> = ({
  cancelAction,
  confirmAction,
  contact,
  open,
}) => {
  return (
    <Dialog open={open} onClose={cancelAction}>
      <DialogTitle id="question-dialog-title">
        {`Delete Contact: ${contact?.first_name} ${contact?.last_name}`}?
      </DialogTitle>
      <DialogContent>
        <DialogContentText id="question-dialog-prompt-text">
          {contact
            ? `You are about to delete ${contact.first_name} ${
                contact.last_name
              } ${
                contact.nickname ? `[${contact.nickname}]` : ''
              }. Would you like to continue?`
            : ''}
        </DialogContentText>
      </DialogContent>
      <DialogActions>
        <Button onClick={cancelAction}>No</Button>
        <Button
          onClick={confirmAction}
          startIcon={<DeleteIcon />}
          variant="contained"
        >
          Yes
        </Button>
      </DialogActions>
    </Dialog>
  );
};

ℹ️ We could have made a dialog wrapper component since the structure and behavior of the dialogs are very similar (we can do that next time or, you could do it as a challenge)

Let's update our contact listing as follows

import React, { useCallback, useMemo, useState } from 'react';
import type { FC } from 'react';
import { Inertia } from '@inertiajs/inertia';
import {
  Box,
  Divider,
  Fab,
  IconButton,
  List,
  ListItem,
  ListItemIcon,
  ListItemText,
} from '@mui/material';
import type { AlertColor } from '@mui/material';
import {
  AddCircleOutlineRounded as AddIcon,
  DeleteForeverOutlined as DeleteIcon,
  EditRounded as EditIcon,
  InfoOutlined as InfoIcon,
  Person2Rounded as PersonIcon,
} from '@mui/icons-material';

import type { Contact } from '../../interfaces/contact.interface';
import { ContactInfoDialog } from '../../components/ContactInfoDialog';
import { QuestionDialog } from '../../components/QuestionDialog';
import { Notification } from '../../components/Notification';

type DialogType = 'info' | 'question' | 'none';

const CONTACT_LIST_MESSAGES: Record<AlertColor, string> = {
  error: 'An error occurred while trying to delete contact.',
  info: '',
  success: 'Contact was deleted successfully.',
  warning: '',
};

interface ListingProps {
  contacts: Contact[];
}

const Listing: FC<ListingProps> = ({ contacts }) => {
  const [selectedContactId, setSelectedContactId] = useState<
    number | undefined
  >();
  const [dialogType, setDialogType] = useState<DialogType>('none');
  const [notificationType, setNotificationType] = useState<AlertColor>();
  const [notificationOpen, setNotificationOpen] = useState(false);
  const [notificationText, setNotificationText] = useState('');

  const closeContactInfoModal = useCallback(() => {
    setSelectedContactId(undefined);
    setDialogType('none');
  }, []);

  const editContact = useCallback((contactId: number) => {
    Inertia.visit(`/contact/${contactId}`);
  }, []);

  const showContactInfo = useCallback((contactId: number) => {
    setDialogType('info');
    setSelectedContactId(contactId);
  }, []);

  const closeQuestionDialog = useCallback(() => {
    setDialogType('none');
    setSelectedContactId(undefined);
  }, []);

  const deleteContact = useCallback((contactId: number) => {
    Inertia.delete(`${contactId}/delete`, {
      onError: () => {
        setNotificationType('error');
        setNotificationText(CONTACT_LIST_MESSAGES['error']);
        setNotificationOpen(true);
      },
      onSuccess: () => {
        setNotificationType('success');
        setNotificationText(CONTACT_LIST_MESSAGES['success']);
        setNotificationOpen(true);
      },
    });
  }, []);

  const deleteContactPrompt = useCallback((contactId: number) => {
    setDialogType('question');
    setSelectedContactId(contactId);
  }, []);

  const resetNotification = useCallback(() => {
    setNotificationOpen(false);
    setNotificationText('');
    setNotificationType(undefined);
  }, []);

  const selectedContact: Contact | undefined = useMemo(() => {
    try {
      return contacts.find((contact) => contact.id === selectedContactId);
    } catch (e) {
      return undefined;
    }
  }, [contacts, selectedContactId]);

  return (
    <>
      <List sx={{ width: '100%' }}>
        {contacts.map((contact, index) => (
          <Box key={`item-${index}`}>
            {index ? <Divider /> : null}
            <ListItem
              key={`contact-${contact.id}`}
              alignItems="center"
              secondaryAction={
                <>
                  <IconButton onClick={() => showContactInfo(contact.id)}>
                    <InfoIcon />
                  </IconButton>
                  <IconButton onClick={() => editContact(contact.id)}>
                    <EditIcon />
                  </IconButton>
                  <IconButton onClick={() => deleteContactPrompt(contact.id)}>
                    <DeleteIcon />
                  </IconButton>
                </>
              }
            >
              <ListItemIcon>
                <PersonIcon />
              </ListItemIcon>
              <ListItemText
                primary={`${contact.first_name} ${contact.last_name}`}
                secondary={contact.phone_number}
              />
            </ListItem>
          </Box>
        ))}
      </List>
      <ContactInfoDialog
        contact={selectedContact}
        onClose={closeContactInfoModal}
        onEdit={
          selectedContact ? () => editContact(selectedContact.id) : () => {}
        }
        open={!!selectedContact && dialogType === 'info'}
      />
      <QuestionDialog
        cancelAction={closeQuestionDialog}
        confirmAction={
          selectedContact ? () => deleteContact(selectedContact.id) : () => {}
        }
        contact={selectedContact}
        open={!!selectedContact && dialogType === 'question'}
      />
      <Fab
        color="primary"
        onClick={() => Inertia.visit('/contact/add')}
        sx={{ bottom: 20, position: 'absolute', right: 20 }}
      >
        <AddIcon />
      </Fab>
      <Notification
        closeNotification={resetNotification}
        notificationOpen={notificationOpen}
        notificationText={notificationText}
        notificationType={notificationType}
      />
    </>
  );
};

export default Listing;

At this point, we should be able to delete a record and have it actually disappear from our listing. Go ahead and test it. If it all worked correctly, then you should see something like the image below.

Looking pretty good, right? At this point, everything should be working without issue, if that's the case, feel free celebrate.

Now would be a good time to commit the code we wrote. You guys already know how to do that since you're pros.

Upgrading to InertiaJS 1.x

We're now at the part where we can go ahead and upgrade our project to InertiaJs 1.x. We will have to do a fair bit of refactoring but I promise that it won't be difficult. You can review the InertiaJs migration docs here.

Make a new branch for the upgrade
Go ahead and stop Vite (if already running)
Remove the old InertiaJs dependencies

# we didn't use @inertiajs/server so it was never installed
npm remove @inertiajs/inertia @inertiajs/inertia-react @inertiajs/progress

Install the new dependency

npm install -D @inertiajs/react

In our react-app/src/main.jsx file, let's update our InertiaJs import

import React from 'react';
import { createRoot } from 'react-dom/client';
// Remove these lines
// - import { createInertiaApp } from '@inertiajs/inertia-react';
// - import { InertiaProgress } from '@inertiajs/progress';
// Add this line
import { createInertiaApp } from '@inertiajs/react';
import Layout from './components/Layout.tsx';

const pages = import.meta.glob('./pages/**/*.tsx');

document.addEventListener('DOMContentLoaded', () => {
  createInertiaApp({
    resolve: async (name) => {
      const page = (await pages[`./pages/${name}.tsx`]()).default;
      page.layout = page.layout || Layout;

      return page;
    },
    setup({ el, App, props }) {
      createRoot(el).render(<App {...props} />);
    },
  }).then();
});

Let's update the code in react-app/src/pages/Contact/Listing.tsx. Here, we're updating our imports and replacing all usages of Inertia.visit() with router.visit() and Inertia.delete() with router.delete()

import React, { useCallback, useMemo, useState } from 'react';
import type { FC } from 'react';
// import { Inertia } from '@inertiajs/inertia';
import { router } from '@inertiajs/react';
import {
  Box,
  Divider,
  Fab,
  IconButton,
  List,
  ListItem,
  ListItemIcon,
  ListItemText,
} from '@mui/material';
import type { AlertColor } from '@mui/material';
import {
  AddCircleOutlineRounded as AddIcon,
  DeleteForeverOutlined as DeleteIcon,
  EditRounded as EditIcon,
  InfoOutlined as InfoIcon,
  Person2Rounded as PersonIcon,
} from '@mui/icons-material';

import type { Contact } from '../../interfaces/contact.interface';
import { ContactInfoDialog } from '../../components/ContactInfoDialog';
import { QuestionDialog } from '../../components/QuestionDialog';
import { Notification } from '../../components/Notification';

type DialogType = 'info' | 'question' | 'none';

const CONTACT_LIST_MESSAGES: Record<AlertColor, string> = {
  error: 'An error occurred while trying to delete contact.',
  info: '',
  success: 'Contact was deleted successfully.',
  warning: '',
};

interface ListingProps {
  contacts: Contact[];
}

const Listing: FC<ListingProps> = ({ contacts }) => {
  const [selectedContactId, setSelectedContactId] = useState<
    number | undefined
  >();
  const [dialogType, setDialogType] = useState<DialogType>('none');
  const [notificationType, setNotificationType] = useState<AlertColor>();
  const [notificationOpen, setNotificationOpen] = useState(false);
  const [notificationText, setNotificationText] = useState('');

  const closeContactInfoModal = useCallback(() => {
    setSelectedContactId(undefined);
    setDialogType('none');
  }, []);

  const editContact = useCallback((contactId: number) => {
    router.visit(`/contact/${contactId}`);
  }, []);

  const showContactInfo = useCallback((contactId: number) => {
    setDialogType('info');
    setSelectedContactId(contactId);
  }, []);

  const closeQuestionDialog = useCallback(() => {
    setDialogType('none');
    setSelectedContactId(undefined);
  }, []);

  const deleteContact = useCallback((contactId: number) => {
    router.delete(`${contactId}/delete`, {
      onError: () => {
        setNotificationType('error');
        setNotificationText(CONTACT_LIST_MESSAGES['error']);
        setNotificationOpen(true);
      },
      onSuccess: () => {
        setNotificationType('success');
        setNotificationText(CONTACT_LIST_MESSAGES['success']);
        setNotificationOpen(true);
      },
    });
  }, []);

  const deleteContactPrompt = useCallback((contactId: number) => {
    setDialogType('question');
    setSelectedContactId(contactId);
  }, []);

  const resetNotification = useCallback(() => {
    setNotificationOpen(false);
    setNotificationText('');
    setNotificationType(undefined);
  }, []);

  const selectedContact: Contact | undefined = useMemo(() => {
    try {
      return contacts.find((contact) => contact.id === selectedContactId);
    } catch (e) {
      return undefined;
    }
  }, [contacts, selectedContactId]);

  return (
    <>
      <List sx={{ width: '100%' }}>
        {contacts.map((contact, index) => (
          <Box key={`item-${index}`}>
            {index ? <Divider /> : null}
            <ListItem
              key={`contact-${contact.id}`}
              alignItems="center"
              secondaryAction={
                <>
                  <IconButton onClick={() => showContactInfo(contact.id)}>
                    <InfoIcon />
                  </IconButton>
                  <IconButton onClick={() => editContact(contact.id)}>
                    <EditIcon />
                  </IconButton>
                  <IconButton onClick={() => deleteContactPrompt(contact.id)}>
                    <DeleteIcon />
                  </IconButton>
                </>
              }
            >
              <ListItemIcon>
                <PersonIcon />
              </ListItemIcon>
              <ListItemText
                primary={`${contact.first_name} ${contact.last_name}`}
                secondary={contact.phone_number}
              />
            </ListItem>
          </Box>
        ))}
      </List>
      <ContactInfoDialog
        contact={selectedContact}
        onClose={closeContactInfoModal}
        onEdit={
          selectedContact ? () => editContact(selectedContact.id) : () => {}
        }
        open={!!selectedContact && dialogType === 'info'}
      />
      <QuestionDialog
        cancelAction={closeQuestionDialog}
        confirmAction={
          selectedContact ? () => deleteContact(selectedContact.id) : () => {}
        }
        contact={selectedContact}
        open={!!selectedContact && dialogType === 'question'}
      />
      <Fab
        color="primary"
        onClick={() => router.visit('/contact/add')}
        sx={{ bottom: 20, position: 'absolute', right: 20 }}
      >
        <AddIcon />
      </Fab>
      <Notification
        closeNotification={resetNotification}
        notificationOpen={notificationOpen}
        notificationText={notificationText}
        notificationType={notificationType}
      />
    </>
  );
};

export default Listing;

Let's update the code in react-app/src/pages/Contact/ContactForm.tsx. Here, we're updating our imports and replacing all usages of Inertia.visit() with router.visit(). We don't have to change the usage of useForm.

import React, { useCallback, useEffect, useState } from 'react';
import type { FC, FormEvent } from 'react';
// remove these lines
// - import { Inertia } from '@inertiajs/inertia';
// - import { useForm } from '@inertiajs/inertia-react';
// Add this line
import {router, useForm} from '@inertiajs/react';
import {
  Box,
  Button,
  Container,
  FormControl,
  FormHelperText,
  Grid,
  Input,
  InputLabel,
  Typography,
} from '@mui/material';
import type { AlertColor } from '@mui/material';
import { ContactPhone as ContactIcon } from '@mui/icons-material';
import type { Contact } from '../../interfaces/contact.interface';
import { Notification } from '../../components/Notification';

type FormData = {
  first_name: string;
  middle_name: string;
  last_name: string;
  nickname: string;
  email_address: string;
  phone_number: string;
};

const SUBMIT_RESPONSE_MESSAGES: Record<AlertColor, string> = {
  success: 'Contact information was saved',
  error: 'There was a problem with saving contact information.',
  info: '',
  warning: '',
};

interface ContactFormProps {
  contact?: Contact;
}

const ContactForm: FC<ContactFormProps> = ({ contact }) => {
  const {
    clearErrors,
    data,
    errors,
    post: createContact,
    processing,
    setData,
    put: updateContact,
  } = useForm({
    first_name: '',
    middle_name: '',
    last_name: '',
    nickname: '',
    email_address: '',
    phone_number: '',
  });

  const [contactId, setContactId] = useState<number | undefined>();
  const [notificationType, setNotificationType] = useState<AlertColor>();
  const [notificationOpen, setNotificationOpen] = useState(false);
  const [notificationText, setNotificationText] = useState('');

  useEffect(() => {
    if (contact) {
      setContactId(contact.id);
      setData({
        ...contact,
        middle_name: contact.middle_name || '',
        nickname: contact.nickname || '',
      } as FormData);
    }
  }, [contact]);

  const closeNotification = useCallback(() => {
    if (notificationType === 'success') {
      router.visit('/contact');
    }
    setNotificationOpen(false);
    setNotificationText('');
  }, [notificationType]);

  const handleNotification = useCallback((notificationType: AlertColor) => {
    setNotificationType(notificationType);
    setNotificationText(SUBMIT_RESPONSE_MESSAGES[notificationType]);
    setNotificationOpen(true);
  }, []);

  const submitContactData = useCallback(
    (e: FormEvent<HTMLFormElement>) => {
      e.preventDefault();
      clearErrors();
      contact
        ? updateContact(`/contact/${contactId}/`, {
            onError: () => handleNotification('error'),
            onSuccess: () => {
              handleNotification('success');
              setTimeout(() => {
                router.visit('/contact');
              }, 3000);
            },
          })
        : createContact('', {
            onError: () => handleNotification('error'),
            onSuccess: () => {
              handleNotification('success');
              setTimeout(() => {
                router.visit('/contact');
              }, 3000);
            },
          });
    },
    [contactId, data]
  );

  return (
    <Container maxWidth="md" sx={{ pt: 2, width: '100%' }}>
      <Box
        sx={{
          alignItems: 'center',
          display: 'flex',
          flexDirection: 'row',
          mb: 2,
        }}
      >
        <ContactIcon fontSize="large" />
        <Typography sx={{ fontSize: 40, ml: 1 }} variant="h1">
          {contact ? 'Update' : 'Add New'} Contact
        </Typography>
      </Box>
      <form onSubmit={submitContactData}>
        <Grid container spacing={2}>
          <Grid item sm={4} xs={12}>
            <FormControl error={!!errors.first_name} fullWidth>
              <InputLabel htmlFor="first-name">First Name</InputLabel>
              <Input
                id="first-name"
                onChange={(e) => setData('first_name', e.target.value)}
                placeholder="First Name..."
                required
                value={data.first_name}
              />
              {errors.first_name ? (
                <FormHelperText sx={{ ml: 0 }}>
                  {errors.first_name}
                </FormHelperText>
              ) : null}
            </FormControl>
          </Grid>
          <Grid item sm={4} xs={12}>
            <FormControl error={!!errors.middle_name} fullWidth>
              <InputLabel htmlFor="middle-name">Middle Name</InputLabel>
              <Input
                id="middle-name"
                onChange={(e) => setData('middle_name', e.target.value)}
                placeholder="Middle Name..."
                type="text"
                value={data.middle_name}
              />
              {errors.middle_name ? (
                <FormHelperText sx={{ ml: 0 }}>
                  {errors.middle_name}
                </FormHelperText>
              ) : null}
            </FormControl>
          </Grid>
          <Grid item sm={4} xs={12}>
            <FormControl error={!!errors.last_name} fullWidth>
              <InputLabel htmlFor="last-name">Last Name</InputLabel>
              <Input
                id="last-name"
                onChange={(e) => setData('last_name', e.target.value)}
                placeholder="Last Name..."
                required
                value={data.last_name}
              />
              {errors.last_name ? (
                <FormHelperText sx={{ ml: 0 }}>
                  {errors.last_name}
                </FormHelperText>
              ) : null}
            </FormControl>
          </Grid>
          <Grid item xs={12}>
            <FormControl error={!!errors.nickname} fullWidth>
              <InputLabel>Nickname</InputLabel>
              <Input
                error={!!errors.nickname}
                id="nickname"
                onChange={(e) => setData('nickname', e.target.value)}
                placeholder="Nickname..."
                value={data.nickname}
              />
              {errors.nickname ? (
                <FormHelperText sx={{ ml: 0 }}>
                  {errors.nickname}
                </FormHelperText>
              ) : null}
            </FormControl>
          </Grid>
          <Grid item sm={6} xs={12}>
            <FormControl error={!!errors.email_address} fullWidth>
              <InputLabel htmlFor="email-address">Email Address</InputLabel>
              <Input
                id="email-address"
                onChange={(e) => setData('email_address', e.target.value)}
                placeholder="user@example.com"
                required
                type="email"
                value={data.email_address}
              />
              {errors.email_address ? (
                <FormHelperText sx={{ ml: 0 }}>
                  {errors.email_address}
                </FormHelperText>
              ) : null}
            </FormControl>
          </Grid>
          <Grid item sm={6} xs={12}>
            <FormControl error={!!errors.phone_number} fullWidth>
              <InputLabel htmlFor="phone-number">Phone Number</InputLabel>
              <Input
                id="phone-number"
                onChange={(e) => setData('phone_number', e.target.value)}
                placeholder="555-0001"
                required
                value={data.phone_number}
              />
              {errors.phone_number ? (
                <FormHelperText sx={{ ml: 0 }}>
                  {errors.phone_number}
                </FormHelperText>
              ) : null}
            </FormControl>
          </Grid>
        </Grid>
        <Box sx={{ mt: 2 }}>
          <Button
            disabled={processing}
            fullWidth
            type="submit"
            variant="contained"
          >
            {contact ? 'Update' : 'Save New'} Contact
          </Button>
        </Box>
      </form>
      <Notification
        closeNotification={closeNotification}
        notificationOpen={notificationOpen}
        notificationText={notificationText}
        notificationType={notificationType}
      />
    </Container>
  );
};

export default ContactForm;

Let's restart Vite and if everything worked as it should, we shouldn't notice any changes or errors.

Hope you found this guide / tutorial useful. And of course, let me know if you have any questions or comments. There might be a Part 2.5 to this tutorial that would cover the Contact Notes section.

References

The following resources were used in the creation of this part of the tutorial

InertiaJs migration guide https://inertiajs.com/upgrade-guide
Material UI for React https://mui.com/material-ui/getting-started/overview/
Django Model Form documentation https://docs.djangoproject.com/en/4.1/topics/forms/modelforms/

Django, InertiaJs and React - A guide to get you started - Pt. 1

Simon (Sai) — Sun, 15 Jan 2023 02:14:42 +0000

⚠️ This guide is for versions of Inertiajs before v 1.0. I will be including the upgrade to InertiaJs V 1.0 in Part 2.

Motivations: I prepared this guide to solve a problem I was having with one of the projects that I have in production. I won't bore you with the details but, what I can say about it is that it's a Django project that makes use of ReactJs using Webpack but in a kind of thrown together way that made development a pain. With that in mind, I decided to search for a better way. Hopefully this will be of help to someone.

I'll be splitting this guide into two parts just to make it easier to consume.

Prerequisites

Some experience with the Django framework and React
Have an environment that is ready for Django app development (the usual requirements like Pip / Pipenv and so on)
Python 3.7+
NodeJS 16.x+
React Dev Tools

Tested platforms

✅ Ubuntu 22.04 LTS
✅ MacOS
✅ Windows ** Thanks to @TappMax for testing

What we'll be doing in Part. 1

Setting up our Django project
Setting up GIT (optional, but usually a good idea)
Installing the required Django dependencies and configuring them
Setting up our Inertia App
Testing Django with our InertiaJS App

Initial Setup of up our Django Project

For this guide, we will be building a simple contact list manager. Since the main focus is to walk through getting Django, InertiaJS, React with Vite to play nicely, we will be skipping things like Authentication and styling (for the most part).

Let's begin getting our Django project started

Let's create a folder for our project and navigate to it

mkdir contact-app
cd contact-app

Create your virtual environment using the following command (or your preferred way to create a virtual environment):

python3 -m venv .venv

activate your newly created environment using:

source .venv/bin/activate

install Django 4.1 LTS using the command and it would be a good idea to upgrade pip in our virtual environment as well

pip install Django==4.1
pip install --upgrade pip

ℹ️ Your terminal output might be different but as long as all the packages were installed properly, you can proceed to the next step

⚠️ A note about the settings file in the django project that was just created: the SECRET_KEY is something that should be kept safe. There are a few things that we can do to secure our settings file but we'll save that for another time.

Create our django project in our current directory

django-admin startproject contact_manager .

ℹ️ If the command ran correctly, you will not see anything returned. You can always checking using the ls command

Let's make sure our application is working correctly

./manage.py runserver

ℹ️ Your terminal should show something similar. Don't worry about unapplied migrations warning. We'll fix those soon.

At this point, you should be able to navigate to the development server address.
We should be up and running at this point. The console will tell us that we have unapplied migrations...that's ok for now

ℹ️ We should see the start page when we navigate to http://127.0.0.1:8000 as directed in the terminal output

# All the commands
python3 -m venv .venv
source .venv/bin/activate
pip install Django==4.1
pip install --upgrade pip
./manage.py runserver

# Windows Notes: Provided by Max

# All the commands on windows
python -m venv .venv
.venv\Scripts\activate
pip install Django==4.1
pip install --upgrade pip
manage.py runserver

Setting up git (optional, but recommended)

This step is optional but recommended. If you have the development server run, go ahead and stop it.

⚠️ if you intend to follow this step, the assumption here is that you have experience setting up GIT. That said, if you don't, I gotchu. This link will help: https://www.atlassian.com/git/tutorials/install-git

Let's initialize our git repo for this project

git init

You should see something that looks like

Initialized empty Git repository in PATH/TO/YOUR/PROJECT

Let's get a git ignore file in place from now. Depending on your IDE or Editor, you may be able to generate a .gitignore file.
Create a file named .gitignore in the root of the project and copy and paste the following (this file is probably overkill for our purposes)

# Byte-compiled / optimized / DLL files
__pycache__/
*.py[cod]
*$py.class

# PyInstaller
*.manifest
*.spec

# Installer logs
pip-log.txt
pip-delete-this-directory.txt

# Minimal Django:
*.log
local_settings.py
db.sqlite3
db.sqlite3-journal

# Minimal Virtualenv
.venv

# Jetbrains
.idea

# Minimal NodeJS
dist
node_modules

With this in place, we can add all our files and then commit them

git add .
git commit -m 'initial commit'

Installing Django Dependencies

In this section, we'll be installing inertia/django and django-vite and configuring our settings to make things work.

If you're using version control, let's go ahead and make a new branch from main

git checkout -b install-dependencies # or whatever you want to call it

Installing Inertia/Django

For more information about the Inertia.js Django Adapter: https://pypi.org/project/inertia-django/

pip install inertia-django

ℹ️ Your output should look something like what's shown above

Now would be a good time to open up the project in your IDE or editor. I'll be using Pycharm Professional but VSCode is fine too. And let's have a look at the project structure so far.

Next, we will update our INSTALLED_APPS in our settings.py file to inertia inertia

INSTALLED_APPS = [
  # django inertia apps,
  'inertia',
  # our project's apps,
]

and then update our MIDDLEWARE in settings.py to include the inertia middleware inertia.middleware.InertiaMiddleware

MIDDLEWARE = [
  # django middleware,
  'inertia.middleware.InertiaMiddleware',
  # your project's middleware,
]

ℹ️ Your settings.py should look something like the image above

Next, create a template file templates/base.html having the initial structure

<!DOCTYPE *html*>
<html *lang*="en">
  <head>
    <meta *charset*="UTF-8">
    <title>Title</title>
  </head>
  <body>
    {% block *inertia* %}{% endblock %}
  </body>
</html>

To settings, add INERTIA_LAYOUT = 'base.html' to the end of the settings file

Update DIRS in TEMPLATES to include BASE_DIR / 'templates'

TEMPLATES = [
    {
        'BACKEND': 'django.template.backends.django.DjangoTemplates',
        'DIRS': [BASE_DIR / 'templates'], # add this line
        'APP_DIRS': True,
        'OPTIONS': {
            'context_processors': [
                'django.template.context_processors.debug',
                'django.template.context_processors.request',
                'django.contrib.auth.context_processors.auth',
                'django.contrib.messages.context_processors.messages',
            ],
        },
    },
]

ℹ️ The TEMPLATES section of your settings.py should look like this

Installing Django-Vite

pip install django-vite

Once installed, add django-vite to our installed apps

INSTALLED_APPS = [
  # django apps,
  'django_vite',
  'inertia',
  # your project's apps,
]

In the root of the project, we will need to create a package.json file by using npm

npm init -y

Now we can install Vite 🚀

npm i -D vite

For vite to work, we need to create a vite.config.js file in the root of our project with the following content

import { resolve }  from 'path';

module.exports = {
 plugins: [],
 root: resolve('./react-app'),
 base: '/static/',
 server: {
   host: 'localhost',
   port: 3000,
   open: false,
   watch: {
     usePolling: true,
     disableGlobbing: false,
   },
 },
 resolve: {
   extensions: ['.js', '.json'],
 },
 build: {
   outDir: resolve('./react-app/dist'),
   assetsDir: '',
   manifest: true,
   emptyOutDir: true,
   target: 'es2015',
   rollupOptions: {
     input: {
       main: resolve('./react-app/src/main.js'),
     },
     output: {
       chunkFileNames: undefined,
     },
   },
 },
};

Update the file templates/base.html with the following content

{% load django_vite %}
<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="UTF-8">
    <!-- include vite hmr -->
     {% vite_hmr_client %}
     {% vite_asset 'src/main.js' %}
     <title>Title</title>
  </head>
  <body>
     {% block inertia %}{% endblock %}
  </body>
</html>

ℹ️ we are referencing js/main.js, we will create this file eventually.

Update settings.py to include the necessary settings for Django Vite

# InertiaJS Related settings
INERTIA_LAYOUT = 'base.html'

# We need this for django form posting
CSRF_HEADER_NAME = 'HTTP_X_XSRF_TOKEN'
CSRF_COOKIE_NAME = 'XSRF-TOKEN'

# Where ViteJS assets are built.
DJANGO_VITE_ASSETS_PATH = BASE_DIR / "react-app" / "dist"

# If we should use HMR or not.
DJANGO_VITE_DEV_MODE = DEBUG

# we need this to get around cors issues
DJANGO_VITE_DEV_SERVER_HOST = '127.0.0.1'

# this is the default, but I'm leaving this here, so you know what to change if you want to run on a different port
DJANGO_VITE_PORT = 3000

# Name of our static files' folder (after called python manage.py collectstatic)
STATIC_ROOT = BASE_DIR / "static"

# Include DJANGO_VITE_ASSETS_PATH into STATICFILES_DIRS to be copied inside
# when run command python manage.py collectstatic
STATICFILES_DIRS = [DJANGO_VITE_ASSETS_PATH]

Let's create our react-app/dist folder which we will use eventually (Django's dev server will complain about it)
Let's create our entry point for what will become our React/InertiaJS app react-app/src/main.js

alert('Django Vite says hello world!');

Update package.json to include dev and build scripts so that we can run vite

{
  "scripts": {
    "build": "vite build",
    "dev": "vite",
    "test": "echo \"Error: no test specified\" && exit 1"
  },
}

At this point, we should be able to run vite and we shouldn't see any errors in the terminal. That said, we still can't do anything useful yet

In our browser, we should able to access our js file

Let's add a file for our views and we'll call it... contact_manager/views.py 😏

from django.shortcuts import render


def index(request):
   return render(request, "base.html")

Let's update our urls urls.py

from django.contrib import admin
from django.urls import path

# this was added
from contact_manager import views
# from contact_manager.views import index # this is a valid import as well

urlpatterns = [
   path('', views.index), # this was added
   path('admin/', admin.site.urls),
]

Open a new terminal and run the django dev server
Navigate to http://127.0.0.1:8000 and we should see our JavaScript alert.

ℹ️ We have HMR working. Of course you can check that it works by changing the main.js file and observing what happens. 👍

Since we're at a decent point, let's commit our changes before we move forward (if you're using version control)

git add .
git commit -m "Install dependencies and did initial setup for vite to serve main.js file via vite"

Now for the interesting part 🙌

Update the previously created contact_manager/views.py fileto include an import from inertia

from inertia import inertia


@inertia('Home/Index')
def index(request):
   return {
       'contacts': ['Acid Burn', 'Crash Override', 'Lord Nikon'],
   }

ℹ️ The object we return from our index function becomes the props of the React component we will eventually render

If everything worked correctly, when we inspect our index page, we should see a div that has id="app" along with a data-page attribute that contains the contacts as defined in our python view file.

The last thing we'll do for Part 1 of this tutorial is to setup our InertiaJS application

Let's install the dependencies we need via NPM

npm i -D react react-dom @vitejs/plugin-react

Edit: For our InertiaJs dependencies @inertiajs/inertia-react @inertiajs/progress, we will need specific versions as shown in the package.json snippet below.

"devDependencies": {
    "@inertiajs/inertia-react": "^0.8.1",
    "@inertiajs/progress": "^0.2.7",
    "@types/react": "^18.0.26",
    "@types/react-dom": "^18.0.10",
    "@vitejs/plugin-react": "^3.0.1",
    "react": "^18.2.0",
    "react-dom": "^18.2.0",
    "ts-loader": "^9.4.2",
    "typescript": "^4.9.4",
    "vite": "^4.0.4"
  }

Stop vite if you have not yet done so
Rename our main.js to main.jsx and replace the content with what is shown below

import React from 'react';
import { createRoot } from 'react-dom/client';
import { createInertiaApp } from '@inertiajs/inertia-react';
import { InertiaProgress } from '@inertiajs/progress';
import Layout from './components/Layout.jsx';

const pages = import.meta.glob('./pages/**/*.jsx');

document.addEventListener('DOMContentLoaded', () => {

 InertiaProgress.init();

 createInertiaApp({
   resolve: async (name) => {
     const page = (await pages[`./pages/${name}.jsx`]()).default;
     page.layout = page.layout || Layout;

     return page;
   },
   setup({ el, App, props }) {
     createRoot(el).render(<App {...props} />);
   },
 }).then();
});

Let's update our vite.config.js file to work with our changes

import { resolve }  from 'path';
import react from '@vitejs/plugin-react';

module.exports = {
 plugins: [
   react({
     include: '**/*.disabled',
   }),
 ],
 root: resolve('./react-app'),
 base: '/static/',
 server: {
   host: 'localhost',
   port: 3000,
   open: false,
   watch: {
     usePolling: true,
     disableGlobbing: false,
   },
 },
 resolve: {
   extensions: ['.js', '.json'],
 },
 build: {
   outDir: resolve('./react-app/dist'),
   assetsDir: '',
   manifest: true,
   emptyOutDir: true,
   target: 'es2015',
   rollupOptions: {
     input: {
       main: resolve('./react-app/src/main.jsx'),
     },
     output: {
       chunkFileNames: undefined,
     },
   },
 },
};

Let's create a layout component src/components/Layout.jsx which we will use to wrap our pages

const Layout = ({ children }) => {
 return (
   <main>
     <div>{children}</div>
   </main>
 );
};

export default (page) => <Layout>{page}</Layout>;

Update templates/base.html to point to our main.jsx file
Create our Index page component src/pages/Home/Index.jsx and paste the following content

export default function Home ({contacts}) {
 return (
   <div>
     <h1>Contact List</h1>
     {Array.isArray(contacts) && contacts.length ? <ul>
       {contacts.map(contact => <li key={contact}>{contact}</li>)}
     </ul> : <p>No contacts yet...</p>}
   </div>
 );
}

ℹ️ Now, if everything worked, we should see something that looks like the image below 👍

Go ahead and commit our changes

git add .
git commit -m "update implementation to render inertia js app with props"

If you've made it this far and everything works then, nice! As you can see, InertiaJs is pretty cool and being able to use it with Django makes it way cooler (imo).

Coming up in part 2, we'll take a look at the following:

Upgrade InertiaJs to v1.0
Integrating TypeScript
Installing Material UI (you can use any component library you want)
Implementing the contact app
- Backend
- models, views
- Frontend
- Pages and components

Hope you found this guide useful. Let me know if you have questions or suggestions.

References:

The following links were used in the making of this guide

inertia-django https://pypi.org/project/inertia-django/
django-vite https://github.com/MrBin99/django-vite
vite.config.js original source: https://raw.githubusercontent.com/MrBin99/django-vite-example/master/vite.config.js
InertiaJs + Django Setup video (inspiration for this guide) https://www.youtube.com/watch?v=85-i4fr5MeU