Open-source project
viewflow/django-material avatar
viewflow/django-material

Django Material: two manifests with two version numbers, and a changelog link with no releases behind it

Material Design for Django

2,530 stars419 forksJavaScriptAGPL-3.0

At a glance

What is it?
A Material Design 3 component and CRUD layer for Django that tells you it needs no build step while shipping the npm scripts to run one, declares 0.1.0 in package.json and 3.0.0a0 in pyproject.toml, and formats its own tree with two different formatters.
Who is it for?
Django Material is worth reading as an alpha, and the file says so itself by asking for evaluation before production use. Three things decide whether it can be adopted now.
Can I use it commercially?
Yes, with strict conditions. AGPL-3.0 is a network copyleft licence: if people use a modified version over a network, for example as a hosted service, you must offer them its source code under the same licence.
Is it still maintained?
Activity is slowing. The repository last received commits 6 months ago.
What is it written in?
Mainly JavaScript, according to GitHub's language statistics.

Answers come from the project's GitHub data, last synced on November 15, 2026, and from our analysis. They are not legal advice.

From daily snapshots

Star history

  • viewflow/django-material2,530 ★ · -9
Star history
Repository2026-09-302026-11-15
viewflow/django-material2.5k2.5k

-9 Stars in the last 46 days, measured from the daily GitHub snapshot. Compare with other projects

Editorial analysis

Two manifests, two version numbers, no releases

The JavaScript manifest says one thing and the Python manifest says another. `package.json` carries `"version": "0.1.0"`. `pyproject.toml` carries `version = "3.0.0a0"` and a classifier of `Development Status :: 3 - Alpha`.

Nothing else in the tree reconciles them. The package has no GitHub releases at all, so there is no tag to check the number against, and the URL block in `pyproject.toml` still points a Changelog link at the releases page of the repository, which is empty.

That leaves the published name `django-material` as the only stable handle. Whether a consumer installs version 0.1.0 or 3.0.0a0 depends on which artifact they resolve and which file the installer reads, and the repository does not say. It also puts the classifier and the JavaScript version in direct conflict, since one says alpha and the other says a pre one release number.

The default branch is `vibe`, not `main`, which is worth knowing before anyone writes a clone command against the usual default.

The feature list denies a build step, the usage section hands you one

One feature bullet says no build step is required, because pre-built CSS and JS are included. Four commands later, the usage section says to modify design tokens in `material/assets/` and rebuild:

bash
npm run build:css
npm run build:js

Both statements are true about different audiences. A consumer who installs the wheel gets the compiled assets and never runs npm. Anyone who changes a design token has to run the toolchain, and those two scripts are Tailwind and esbuild:

bash
tailwindcss -i ./material/assets/index.css -o material/static/material/css/material.css --minify
esbuild material/templates/cotton/index.js --bundle --format=iife --outfile=material/static/material/js/material.js --minify --sourcemap

A third script, `update:fonts`, pulls Roboto and Material Symbols Rounded from fonts.googleapis.com with an npx helper, so at least one asset path reaches the network at build time. Node is optional for use and required for modification, and the file does not draw that line explicitly.

The tree is formatted twice, by two different formatters

One script handles formatting:

bash
uv run ruff format material demo tests && uv run ruff check material demo tests --fix && uv run black .

Three steps, two formatters. Ruff format is scoped to three directories, then black runs over the entire tree with no path. Anything outside `material`, `demo` and `tests` is therefore formatted only by black, and anything inside them is formatted by ruff first and black second. When the two disagree, the last one wins silently, with no conflict marker and no check that they agree.

The lint script has a different shape again:

bash
pyright material && uv run ruff check material

It type checks and lints one directory only, so `demo/` and `tests/` are formatted but never checked. The JavaScript side is handled separately by `lint:js` over `material/templates/cotton/**/*.js` and `format:js` through prettier, so four tools govern one repository.

One more script reads a `.copyFiles[]` array out of `package.json` and copies each entry from a `src` to a `dest`. The visible part of that manifest has no `copyFiles` key, and whether it appears further down is not shown.

The dev server script binds every network interface

The development entry point is one npm script:

bash
uv run manage.py runserver 0.0.0.0:8000

The host is `0.0.0.0`, so the development server listens on every interface the machine has rather than only on loopback. The `dev` script runs that in parallel with the Tailwind and esbuild watchers through npm-run-all2.

The repository also carries a `deploy.yml` at the top level, and the development dependency group includes `ansible`, so the project has deployment tooling of some kind. What that tooling does, which hosts it targets, and whether it expects the development server to be reachable from elsewhere are not described anywhere in the file.

For a project whose stated audience is other developers, binding all interfaces in the default dev command is the line worth checking before anyone runs it on a shared or hosted machine.

Three license files sit at the root and the README names all three

The licensing is described in three different vocabularies. The license field on the repository says AGPL-3.0. The `pyproject.toml` field says `AGPL-3.0-or-later`. The README says the project is licensed under AGPLv3 with Additional Permissions, points at `LICENSE` and `LICENSE_EXCEPTION`, and says commercial terms are in `COMM-LICENSE`.

All three files are present at the top level, alongside `MANIFEST.in` and `uv.lock`.

What the file does not do is say what the Additional Permissions grant, or which parts of the codebase each of the three documents covers. A reader who needs to know whether a given file falls under the exception has to open all three and work it out, and the difference between `AGPL-3.0` and `AGPL-3.0-or-later` is left to them as well. Nothing in the quick start mentions licensing at all; it appears only in the last section of the README.

For a package whose stated goal includes code generation by assistants, that boundary is the one a commercial adopter will want in writing before anything else.

Python 3.12 and Django 5.2 are floors, not suggestions

The build backend is setuptools with a floor of 61.0, and `requires-python` is `>=3.12`. The classifiers name Python 3.12 and 3.13 and Django 5.2, so the tested surface is two Python versions and one Django major line.

Three runtime dependencies, all with lower bounds:

- `django>=5.2` - `django-cotton>=2.0.0` - `django-filter>=25.1`

`django-cotton` is the component layer, which is why the templates use cotton tags such as `<c-button.filled>` and `<c-card>` inside an ordinary `{% extends "material/base.html" %}` block. `django-filter` is pulled in for list views, and the development group adds cursor pagination and formtools, which are how the CRUD pages are built.

The install path itself is three steps: `pip install django-material`, adding `'material'` to `INSTALLED_APPS`, and `python manage.py collectstatic` for production. The last one matters for deployment, since the CSS and JS are static files that have to be collected before they are served.

The npm test script runs a Python test suite

`npm test` is documented as the way to run tests, and it expands to:

bash
uv run python manage.py test

That is Django's own test runner, so the name suggests JavaScript and the contents are Python. The JavaScript in this repository is the cotton template glue under `material/templates/cotton/`, and it is covered by `lint:js` and `format:js` but by no test script.

The rest of the test surface is a `tests/` directory at the root and a `demo/` project beside it, which carries its own settings, urls, forms, fixtures, templates and a `crud/` directory. A demo with fixtures and prebuilt CRUD pages is a usable reference for what the generated views look like, and the README does not point at it, referring instead to the hosted documentation and live demos at `material.viewflow.io`.

The Python tools in use are `uv` for environment and command running, ruff for lint and format, pyright for types, and black for the second formatting pass.

One author, one maintainer, and an explicit request to evaluate first

The opening line of the README is a caution rather than a pitch: the project asks to be used for exploration and prototyping, warns that APIs, components and behavior may change between versions, and says to evaluate carefully before production use. The classifier in `pyproject.toml` agrees with the caution, marking the package Alpha.

The same file states the project's aim in unusual terms, describing it as a rethink of UI component APIs for AI assisted development, aimed at being intuitive for developers, predictable for code generation tools, and quicker for interfaces written by hand or by machine. That goal explains the AI first bullet in the feature list and the presence of `CLAUDE.md` at the repository root, next to another one inside `demo/`.

Ownership is concentrated. `pyproject.toml` names one person as both author and maintainer, with one email address. The closing line credits the Viewflow Team. The two hosted pointers a reader is given are the documentation site and the demo, and the repository's own homepage field points at a different address entirely.

Editorial conclusion

Django Material is worth reading as an alpha, and the file says so itself by asking for evaluation before production use. Three things decide whether it can be adopted now. Pick one manifest as the version source, because 0.1.0 and 3.0.0a0 cannot both be current, and the changelog link points at a releases page with nothing on it. Decide early whether the Node toolchain is part of your build, since the shipped CSS and JS avoid it but every customization goes through Tailwind and esbuild. And settle the license question with whoever owns the deployment, because AGPL, an exception file and a separate commercial license file sit side by side with no stated boundary between them.

Frequently asked questions

What does django-material add to a Django project?

It brings Material Design 3 to Django in two layers: low level components such as buttons, cards, forms, tables and navigation, and ready made list, create, update and delete views with Material styling. Components are written as django-cotton tags like `<c-button>` and `<c-card>`, on top of TailwindCSS, with no frontend framework.

What does installing django-material require?

Python 3.12 or newer, and three runtime dependencies with lower bounds: django>=5.2, django-cotton>=2.0.0 and django-filter>=25.1. The package is classified as Development Status :: 3 - Alpha and its classifiers name Python 3.12 and 3.13 with Django 5.2.

Does django-material need a frontend build step?

Not to use it, since pre-built CSS and JS are included in the package and only a collectstatic step is needed for production. To change design tokens in material/assets/ you do need one, through npm run build:css and npm run build:js, which run Tailwind and esbuild.

Which license covers django-material?

Three documents are involved and the boundaries between them are not spelled out. The license field on the repository says AGPL-3.0, pyproject.toml says AGPL-3.0-or-later, and the README describes AGPLv3 with Additional Permissions, pointing at LICENSE, LICENSE_EXCEPTION and COMM-LICENSE for the commercial terms.

How do you run the django-material tests?

The documented command is npm test, which expands to uv run python manage.py test, so the suite is Django's Python test runner rather than a JavaScript one. The JavaScript under material/templates/cotton/ has lint and format scripts but no test script.

Official sources

  1. Issues
  2. License: AGPL-3.0
  3. Project website
  4. README
  5. viewflow/django-material on GitHub
Add this badge to your README

If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.

Add this badge to your README

markdown
[![Hysen Labs](https://hysenlabs.com/badge/viewflow-django-material.svg)](https://hysenlabs.com/projects/viewflow-django-material)

Star history chart for your README

markdown
[![Star history](https://hysenlabs.com/chart/viewflow-django-material.svg)](https://hysenlabs.com/projects/viewflow-django-material)

Was this useful?