django-blocks

Atomic Django apps. Copy, own, customize.

Inspired by shadcn/ui, django-blocks is a registry of production-ready Django apps you can selectively add to your project. No bloated boilerplate, just copy the code you need and own it completely.

---

Status

🚧 Design stage — This document describes the proposed architecture and CLI experience. Implementation has not started yet. Feedback and ideas are welcome.

---

Design: CLI & Registry Experience

Problem

Most Django templates are all-or-nothing. You clone a repo with 15 apps, half of which you don't need, and spend hours ripping out what you don't want. Alternatively, you start from scratch and rebuild the same auth/users/payments logic for the hundredth time.

Proposal

A CLI tool that lets you add individual, well-crafted Django apps to your existing project:

uv tool install django-blocks

# Scaffold a new project
djblocks init

# Or configure for an existing project
djblocks init --existing

# Browse available blocks
djblocks list

# Add specific blocks
djblocks add users
djblocks add payments
djblocks add multitenancy

How It Works

1. Registry, not dependency — Blocks are copied directly into your project, not installed as packages. You own the code.

2. Truly atomic — Each block is self-contained. Blocks use settings.AUTH_USER_MODEL and other Django conventions to avoid hard dependencies on each other.

3. Configuration scaffolding — After adding a block, the CLI outputs the settings/urls changes needed (or optionally applies them automatically).

Example Flow

$ djblocks add users

✓ Created apps/users/
✓ Added dependencies: Pillow
✓ Created migration: 0001_initial.py

Next steps:
  1. Add 'apps.users' to INSTALLED_APPS
  2. Set AUTH_USER_MODEL = 'users.User'
  3. Add path('', include('apps.users.urls')) to urlpatterns
  4. Run ./manage.py migrate

Handling Recommendations

Blocks are atomic but some work better together. Instead of auto-installing dependencies, the CLI warns and lets you decide:

$ djblocks add payments

⚠ payments works best with a custom user model.
  Run `djblocks add users` first, or ensure AUTH_USER_MODEL is set.

Proceed anyway? [y/N]

Updating Blocks

Blocks can be updated after installation. Since you own the code and may have customized it, updates require explicit confirmation:

djblocks update users           # overwrites with confirmation
djblocks update users --diff    # preview changes before applying
djblocks update users --backup  # save old files to .djblocks/backup/

For v1, the simple approach: warn users to commit their changes before updating.

Proposed Blocks (v1)

Block	Description
users	Custom user model, profile, account management
auth	Authentication flows (login, register, password reset)
teams	Multi-tenant team/organization support
payments	Stripe/PIX integration, subscriptions
emails	Transactional email with templates
api	DRF boilerplate, token auth, rate limiting
tasks	Celery setup with sensible defaults
storage	S3/local file storage abstraction

Design Principles

• Copy, don't install — You should be able to read and modify every line
• Truly atomic — Each block works standalone, no hidden dependencies
• Production-ready defaults — Security, performance, and Brazilian compliance (LGPD) baked in where relevant
• DRF-first — API endpoints included by default, not an afterthought

---

Future: Web UI

A documentation website (similar to ui.shadcn.com) to browse blocks, preview code, and copy manually. Not required for initial release.

---

Contributing

This project is in design stage. Ideas, feedback, and discussion are welcome — open an issue.

License

MIT