django-angular3

django-angular3 enables seamless integration of Django, Django REST Framework (DRF), and Angular — giving teams a contract-first, automation-ready bridge between a DRF backend and an Angular Material frontend.

Project website: https://djangoangular.com/

Documentation: https://django-angular3.readthedocs.io/

Related docs:

• doc/ARCHITECTURE.md — architecture, integration boundaries, and design decisions
• doc/specifications/SPECIFICATIONS.md — exact platform structures and topology definitions
• doc/specifications/AI_AUTOMATION_SPECIFICATIONS.md — exact AI automation module organization and realization
• doc/specifications/TEST_SCENARIO_SPECIFICATIONS.md — exact build-scenario suite realization and coverage
• doc/contracts/CHANGE_MODEL_CONTRACTS.md — shared Change Model and interface boundaries
• doc/contracts/TOOL_CONTRACTS.md — deterministic Tool contracts
• doc/contracts/HOOK_CONTRACTS.md — lifecycle Hook contracts
• doc/contracts/PROVIDER_ADAPTER_CONTRACTS.md — provider-adapter contracts
• doc/contracts/PLUGIN_CONTRACTS.md — Plugin packaging contracts
• doc/contracts/SKILL_CONTRACTS.md — Skill contracts and catalog ownership
• doc/contracts/TEST_SCENARIO_CONTRACTS.md — build-scenario input and expected oracle boundaries
• doc/plan/CONFIGURATION_PLAN.md — configuration planning
• doc/plan/CONSTRUCTION_PLAN.md — construction sequencing and backlog
• doc/plan/AUTOMATION_PLAN.md — automation sequencing and backlog
• doc/plan/APPLICATION_DELIVERY_PLAN.md — generated-application delivery
• doc/plan/VERIFICATION_PLAN.md — verification sequencing and backlog

It allows you to:

• Keep Django responsible for data, authentication, and administration.
• Keep Angular responsible for the end-user application and client-side route tree.
• Use OpenAPI as the source of truth for API-contract-derived functionality.
• Support pages, reactive forms, navigation, and workflows through an OpenUI concrete UI document.
• Automate the handoff from backend API contract to Angular integration artifacts through a deterministic, repeatable pipeline.

Requirements

See the requirements corpus for product, generated-application, build_app, and AI automation requirements.

Installation

pip install django-angular3

To install from a local clone:

pip install -e /path/to/django-angular3/

For contributor development, use the development setup in CONTRIBUTING.md, which includes both the dev and docs extras for code and documentation validation. The installation commands above are for package use, not the contributor toolchain.

OpenAPI and OpenUI validation

django-angular3 uses openapi-spec-validator for full OAS compliance validation of OpenAPI documents and openui-spec to validate structured OpenUI documents against its schema and catalog. Both are pure-Python dependencies installed automatically with the package — no external validation toolchain is required.

OpenAPI documents are validated against the full OpenAPI specification using openapi-spec-validator; OpenUI documents are validated through openui-spec. The bundled 0.12.1 integration requires each OpenUI document's version to match 0.12.0 and every type to be an exact, case-sensitive literal from its canonical catalog. Use id for instance identity and attrs for configuration rather than aliases, selectors, or implementation names.

An attribute key is categorized: uses.<name> configures the element, produces.<name> is an event it emits, and behaves.<name> is a behavior it applies. An attribute value is a string or null, or a list of strings and null: null indicates no value, and "null" is the string null. A JSON number or Boolean is not a value; write it as a string, such as "true" or "25". A string literal is quoted inside the string, such as "\"Users\"".

Django app integration

If you install django-angular3 into a Django project, add the app to INSTALLED_APPS to enable the bundled ng_ management commands.

INSTALLED_APPS = [
    # ...
    "django_angular3",
]

Or use the explicit app config path:

INSTALLED_APPS = [
    # ...
    "django_angular3.apps.DjangoAngular3Config",
]

The static django-angular3.json configures djng's Angular tool settings, including executable resolution. DJANGO_ANGULAR3 and DjangoAngularSettings are derived from that file; they are not independent configuration authorities. The generated app's identity and artifact locations are instead supplied by the project configuration defined in doc/specifications/SPECIFICATIONS.md §2.1.

To reset a generated app's build artifacts, run django-admin clean. To remove all untracked files and directories from its Git worktree, run django-admin distclean; use --dry-run with either command to inspect its effect first.

Once installed, Django and the standalone CLI expose the same Angular command resolution flow. Use --dry-run only for diagnostic validation and debugging; it resolves commands without executing Angular tooling:

./manage.py ng_new --dry-run
./manage.py ng_workspace --dry-run
./manage.py ng_config --dry-run
./manage.py ng_add --dry-run
./manage.py ng_gen_app --dry-run
./manage.py ng_page --name orders --target-path src/app/features/orders --dry-run
./manage.py ng_component --name order-card --dry-run
./manage.py ng_reactive_form --name contact --definition forms/contact.json --dry-run
./manage.py ng_openapi_gen --dry-run
./manage.py ng_build --dry-run

• ng_new creates an empty Angular workspace
• ng_workspace runs the upstream-aligned workspace bootstrap flow: ng new, workspace defaults, ng add angular-django2, and ng generate angular-django2:workspace-setup
• ng_config applies workspace defaults such as package manager, style, and routing
• ng_add installs and registers the configured angular-django2 package (pinned via tool.ngAddPackage), whose OpenUI integration requires validated 0.12.0 canonical-catalog documents
• ng_gen_app generates an Angular application inside the configured workspace via the angular-django2:material-app schematic, forwarding --ssr, --zoneless, and --defaults to align with the Angular CLI ng new defaults
• ng_material_setup configures Angular Material in an existing project via the angular-django2:material-setup schematic, forwarding optional --theme, --typography, and --animations
• ng_page, ng_component, and ng_reactive_form wrap the matching angular-django2 schematics without changing their deterministic behavior
• ng_workspace, ng_gen_app, ng_page, ng_component, ng_complex_component, and ng_reactive_form accept --document (a workspace-relative OpenUI document) and, except ng_workspace, --node-id to compile an OpenUI element; ng_openapi_setup accepts --auth-scheme bearer|basic
• ng_openapi_gen runs a locally installed ng-openapi-gen for the configured OpenAPI source

build_app --dry-run derives these steps from detected OpenAPI, OpenUI and project changes, following the command mapping of the installed angular-django2 package, and prints each step's order, wrapper command, resolved parameters and reason. Without --dry-run it runs the same steps in order, halts at the first failure and writes build/build-evidence.json. It refuses what ngdj cannot do; see Changes build_app turns into steps for what is supported and refused.

ng_openapi_gen resolves to pnpm exec, so it only uses dependencies that are already installed in the Angular workspace. It does not download and execute packages at runtime.

• ng_build builds the configured Angular application

Naming note: The ng_* command names (e.g. ng_workspace, ng_openapi_gen) are the frozen CLI wrapper layer — stable entry points that never change. The automation subsystem uses two separate layers with distinct names: TOOL contracts are deterministic agent-callable operations (e.g. angular_workspace_scaffold, openapi_schema_export) and SKILL names are AI-guided session identifiers (e.g. angular-workspace-foundation, angular-api-integration). See doc/ARCHITECTURE.md §3.6.4 for the authoritative definition.

Use --app-name <name> with ng_gen_app to override the generated Angular application name.

Beyond these workspace wrappers, angular-django2 ships schematics for composing bespoke feature UI. ng generate angular-django2:component <name> scaffolds a standalone component seeded with begin/end embedding hooks, and ng generate angular-django2:embed-component --component=<child.ts> --parent=<parent.ts> wires a generated child into a parent — importing the class, registering it in the parent standalone imports array, feeding input signals, and binding outputs to on<Output>() handler stubs. Embedding is idempotent, so it is safe to re-run during iterative development. See the Usage workflow for the full generate → embed composition flow.

For advanced Material components, use the ng_complex_component wrapper. It invokes angular-django2:complex-component, which owns theme mixins, nested child composition, projection slots, CDK overlay support, and create/modify/ delete lifecycle handling:

./manage.py ng_complex_component \
  --name dashboard-card --target-path src/app/features/dashboard \
  --features mixins,nested,projection --dry-run

Use --mode delete --confirm for deletion.

At the moment this reusable Django app contributes configuration helpers and management commands; it does not yet ship models, URLs, templates, static assets, or migrations, so there is no extra URL inclusion or migration step for the package itself.

Example

Let's take a look at a simple example of starting from Django REST framework and then layering Angular Material integration on top.

Start by creating a DRF-backed project in the usual way:

pip install djangorestframework
django-admin startproject mysite .
./manage.py migrate
./manage.py createsuperuser

Now edit your project's urls.py module:

from django.contrib.auth.models import User
from django.urls import include, path
from rest_framework import routers, serializers, viewsets


# Serializers define the API representation.
class UserSerializer(serializers.HyperlinkedModelSerializer):
    class Meta:
        model = User
        fields = ["url", "username", "email", "is_staff"]


# ViewSets define the view behavior.
class UserViewSet(viewsets.ModelViewSet):
    queryset = User.objects.all()
    serializer_class = UserSerializer


# Routers provide a way of automatically determining the URL conf.
router = routers.DefaultRouter()
router.register(r"users", UserViewSet)


# Django serves API and authentication routes.
urlpatterns = [
    path("api/", include(router.urls)),
    path("api-auth/", include("rest_framework.urls", namespace="rest_framework")),
]

Add the following to your settings.py module:

INSTALLED_APPS = [
    # ...
    "rest_framework",
]

REST_FRAMEWORK = {
    "DEFAULT_PERMISSION_CLASSES": [
        "rest_framework.permissions.DjangoModelPermissionsOrAnonReadOnly",
    ]
}

At this point, Django + DRF own the backend data and authentication services.

The next step is to export the OpenAPI contract from that backend and use it as the source for API-contract-derived Angular integration.

A simplified schema fragment might look like this:

paths:
  /api/users/:
    get:
      operationId: listUsers
    post:
      operationId: createUser
  /api/users/{id}/:
    get:
      operationId: retrieveUser
    patch:
      operationId: updateUser

Under the generated-app convention, UI requirements are supplied in the project-root app.openui.json selected by artifacts.openuiSpecification. The OpenUI concrete UI document may complement or reference API-contract-derived content. Its role, grammar, and catalog relationship are defined by the OpenUI artifact-role SSOT; see the OpenUI examples for the per-scope vocabulary.

For example:

{
  "id": "root",
  "version": "0.12.0",
  "type": "Application",
  "children": [
    {
      "id": "dashboardPage",
      "type": "DashboardPage"
    },
    {
      "id": "inviteUserForm",
      "type": "Form",
      "attrs": {
        "title": "\"Invite user\"",
        "behaves.submit": "createUser(form.value)"
      }
    }
  ]
}

The scaffolded first version in this repository already includes example inputs. For the contributor workflow around local validation, see Contributing.

Documentation

User-facing usage documentation is published at https://django-angular3.readthedocs.io/:

• Tutorial — install, run the bundled tutorial, and complete the workflow end to end.
• Configuration — configuration guidance and references.
• Usage workflow — the contract-first cycle for your own project.
• Command reference — every command in both the standalone CLI and management-command form.

The project website is available at https://djangoangular.com/.

Current project documents:

• Contributing
• Releasing
• Requirements
• Specifications
• AI automation specifications
• Test scenario specifications
• Change model contracts
• Tool contracts
• Hook contracts
• Provider adapter contracts
• Plugin contracts
• Skill contracts
• Test scenario contracts
• Architecture
• Configuration plan
• Construction plan
• Automation plan
• Application delivery plan
• Verification plan

Status

This project now includes a first scaffolded Python package, example inputs, and the current contributor workflow. The repository does not yet include a frontend workspace. Actual code generation and Angular assembly are still pending.