Angel3 Framework

A production-ready dart backend framework.

---

About

Angel3 originated from a fork of the archived Angel framework in support of Dart SDK 2.12.x or later. It is a full-stack backend framework in Dart that aims to streamline development by providing many common features out-of-the-box in a consistent manner. The codebase has been completely migrated and refactored to support null safety. One of the main goals is to enable developers to build both frontend and backend in dart language. Angel3 is designed as a collection of plugins that enable developers to pick and choose the parts needed for their projects. A series of starter templates are also provided for quick start and trial run with Angel3. Visit our website to learn more.

The available features in Angel3 include:

• OAuth2 Authentication
• WebSocket
• HTTP/2
• HTTP Streaming
• GraphQL, with graphql_dart
• Markdown, Mustache, Jinja and JAEL as Server-Side HTML Rendering
• ORM support for PostgreSQL, MySQL and MariaDB
• MongoDB, Sembast and RethinkDB as storage
• Redis as cache
• Dependency injection with or without dart:mirrors, so apps can be compiled with dart compile exe

The Core Framework

The packages directory contains specialized sub-packages that act as individual plugins or modules. Depending on the needs of a project, a developer can plug in specific packages. The Available Packages table of the framework's README describes each of them.

They can broadly be categorized as follows:

1. Core Framework & Request Handling

   • framework: The foundational package (angel3_framework). It provides the base HTTP and HTTP/2 server, request/response contexts, services, controllers and middleware pipelines.
   • route: The routing engine handling URL matching and route parameters.
   • container: Dependency Injection (DI) system for resolving services, without dart:mirrors. container_mirrors provides the opt-in MirrorsReflector for the Dart VM, and container_generator generates reflection data for @injectable classes, so apps can be compiled with dart compile exe.
   • configuration: Utilities for loading YAML configuration files and .env files.

2. Data Modeling & Persistence (ORM) The framework provides an extensive ORM (angel3_orm) ecosystem with generators and database drivers:

   • orm: Houses the ORM runtime, its code generator (angel3_orm_generator), the migration DSL and runner, the executors for PostgreSQL and MySQL/MariaDB, and a service adapter (angel3_orm_service).
   • model: Base model abstractions for data entities.
   • serialize: Libraries to serialize/deserialize data to and from JSON using code generation (angel3_serialize_generator).
   • mongo, rethinkdb, sembast: Specialized services for MongoDB, RethinkDB, and Sembast (a NoSQL local database).
   • file_service: A service that persists data to a JSON file, for development.

3. Authentication & Security

   • auth: Core authentication abstractions and strategies (local, token-based).
   • auth_oauth2 & oauth2: Out-of-the-box support for OAuth2 authentication flows, as a client and as a server.
   • auth_twitter: Authentication with Twitter OAuth 1.0a.
   • security: Security middleware: CSRF protection, signed cookies and rate limiting.
   • cors: Middleware to handle Cross-Origin Resource Sharing effortlessly.

4. Frontend & Template Rendering Support for processing and returning HTML views to the client:

   • jael: The Jael template engine specifically built for Angel. It is split into the parser and renderer (jael3), template inheritance (jael3_preprocessor), the Angel3 integration (angel3_jael) and an experimental virtual DOM (jael3_web).
   • mustache, jinja, markdown: Wrappers/integrations for rendering Mustache templates, Jinja templates, or parsing Markdown into HTML.
   • html & seo: Utilities for building out HTML responses and optimizing for search engines.

5. Additional Utilities and APIs

   • websocket: Integration for real-time bidirectional communication, and sync to scale it across instances.
   • client: A client-side library designed to interface seamlessly with Angel3 backends directly from Dart/Flutter.
   • cache & redis: Caching interfaces with Redis integration to improve response times.
   • hot & production: Tooling for hot-reloading the server during development, and managing clustering/multi-threading under production loads.
   • test & mock_request: Testing utilities for mocking HTTP requests without spinning up a real server.
   • static: For serving static assets (images, CSS, JS) efficiently.
   • shelf, proxy, paginate, validate, user_agent, http_exception: Shelf interop, request forwarding, pagination, validation, user agent parsing and HTTP errors.

Important Notes

Angel3 packages are published under angel3_ prefix on pub.dev. Each package has its own test suite. The development work is currently focused on:

• Keeping the packages with angel3_ prefix in sync with Dart SDK releases
  • Remove and replace deprecated classes and methods while keeping them backward compatible
  • Refactor the code to use new language features
• Fix and resolve reported issues
• Performance optimization
• Improve on existing features, unit test, user guide and examples
• Add new features

Status

Branch: master

• Version : 10.0.0
• Dart version : 3.13.0 or later.
• Publish : Refer to all packages with angel3_ prefix on pub.dev.
• Status : Production
• Notes : Use this branch for all PR submission

Release Notes (version: 10.0.0)

• Updated all packages to 10.0.0. Each package's CHANGELOG.md lists its breaking changes, new features and fixes, and its README tells how to upgrade, under Migrating from 9.x to 10.0.0
• Removed the use of dart:mirrors, so apps can be compiled with dart compile exe. MirrorsReflector moved to the new angel3_container_mirrors package, and angel3_container_generator generates reflection data for @injectable classes, used through StaticReflector. angel3_websocket, jael3 and angel3_markdown no longer use mirrors either
• Framework: graceful shutdown, in which requests in progress finish before the shutdown hooks run; malformed requests are a 400 instead of a 500
• ORM: @HasMany and @ManyToMany are loaded with a query each instead of joins, so a limit counts records; nested transactions use savepoints on PostgreSQL; MySQL and MariaDB use the mysql_dart driver; migrations are recorded by Migration.name instead of their source path
• Security: CSRF protection (CsrfFilter) in angel3_security; JWTs expire after a day by default and expired ones are no longer revived (angel3_auth); a random state and PKCE verifier for each OAuth2 login (angel3_auth_oauth2); SQL injection fixes in like (angel3_orm), $sort (angel3_orm_service) and string defaults (angel3_migration_runner)
• Templates: Markdown values are HTML-escaped, and views outside the views directory are not read (angel3_jinja, angel3_markdown, angel3_mustache)
• Requires PostgreSQL 14 or later, MySQL 8 or later, or MariaDB 10.2 or later
• Updated the belatuk_ dependencies to their latest releases (belatuk_code_buffer, belatuk_combinator, belatuk_html_builder, belatuk_merge_map and belatuk_symbol_table 6, belatuk_range_header 7). angel3_html pages are HTML-escaped by belatuk_html_builder 6: HTML written as it is needs raw
• The repository is managed with melos 8.9 or later

What is in the pipeline?

• Performance optimization
• Out of the box OIDC and SAML2 support
• Integrated Open API 3 support
• Expand ORM to support
  • SQL Server
  • Oracle DB
  • SQLite
  • Multi-tenant architectures and SQL schema reverse engineering
• ORM caching with Redis

Installation and Setup

(Option 1) Create a new project by cloning from boilerplate templates

1. Download and install Dart. Minimum 3.13.0.

2. Clone one of the following starter projects:

   • Angel3 Basic Template
   • Angel3 PostgreSQL ORM Template
   • Angel3 MySQL ORM Template
   • Angel3 GraphQL Template

3. Run the project in development mode (hot reload is enabled on file changes).

   dart --observe bin/dev.dart

4. Run the project in production mode (hot reload is disabled).

   dart bin/prod.dart

5. Run as docker. Edit and build the image with the provided Dockerfile file.

6. Next, refer to the User Guide to learn more about Angel3 framework.

(Option 2) Create a new project with Angel3 CLI

1. Download and install Dart. Minimum 3.13.0.

2. Install the Angel3 CLI:

   dart pub global activate angel3_cli

3. On terminal, create a new project:

   angel3 init hello

   The latest angel3_cli is 9.0.0, which predates the 10.0.0 packages: check the versions in the generated pubspec.yaml.

4. Run the project in development mode (hot reload is enabled on file changes).

   dart --observe bin/dev.dart

5. Run the project in production mode (hot reload is disabled).

   dart bin/prod.dart

6. Run as docker. Edit and build the image with the provided Dockerfile file.

7. Next, refer to the User Guide to learn more about Angel3 framework.

Performance Testing

Refer to Angel3 Performance Test Suite for more information. It is still in early stage, but eventually will contain test cases for running load testing with Locust on various key features of Angel3 framework. These test cases can serve as a foundation for building performance tests for any applications developed with Angel3 framework.

Performance Benchmark

An official performance benchmark can be found at TechEmpower Framework Benchmarks

The test cases are built using the standard Angel3 ORM template for PostgreSQL and MySQL databases. The results are used for improving Angel3 framework with respect to other frameworks. The following test cases will be added in the subsequent update to this benchmark.

1. Cache with Redis
2. Angel3 with MongoDB

Documentation

Refer to User Guide for more detailed information on the available features of Angel3 framework.

Examples

Take various applications at Examples for a spin to get a feel of what Angel3 framework can do.

Community

Join us on Discord.

Contributing

If you are interested in contributing to Angel3 framework please check out the Contribution Guide.

Development Setup

1. Fork angel repository

2. Clone the project to local and create a new branch

   git clone https://github.com/<your_repo_name>/angel.git
   git checkout -b feature/<your_branch_name>

3. Download and install Dart. Minimum 3.13.0.

4. Install melos 8.9 or later

   dart pub global activate melos

5. Run dart pub get at the repository root to resolve all the packages in the workspace, or melos exec "dart pub upgrade" to upgrade them

6. Contribute changes to the desired packages. After changing a model or a code generator, regenerate the code in the affected packages:

   dart run build_runner build --delete-conflicting-outputs

7. Run dart format, dart analyze and dart test in each package you changed, from its directory. The tests of some packages need a running server, which their test setup describes: PostgreSQL (orm_postgres), MySQL or MariaDB (orm_mysql), MongoDB (mongo), RethinkDB (rethinkdb) and Redis (redis). Run the ORM tests with dart test -j1, as their test files share tables

8. Add an entry for each user-facing change to the CHANGELOG.md of its package, under ### Breaking changes in X.Y.Z, ### New in X.Y.Z or ### Fixes in X.Y.Z, and use Conventional Commits for commit messages

Donation & Support

If you like this project and are interested in supporting its development work, you are welcome to make a donation via the following links.

• 
• Paypal Donation

Paid Support

We offer professional paid support for teams and developers using Angel3 framework. Our support services are designed to help you build faster, deploy with confidence, and scale reliably, whether you’re just getting started or running the framework in production. The fund collected will go into continued improvements of the framework.

What we can help with

• Architecture and best-practice guidance
• Framework setup, configuration, and upgrades
• Debugging runtime, performance, or build issues
• Production readiness (scaling, monitoring, deployment)
• Code reviews and design feedback
• Custom feature guidance and extensions

Who this is for

• Teams using or planning to use Angel3 in production
• Developers who want expert guidance from people who maintain the framework
• Migration from other Dart or non-Dart frameworks

Support options

We offer flexible plans depending on your needs:

• Hourly support for one-off issues
• Monthly retainers for ongoing help
• Consulting sessions for architecture and planning

Support is available via email, chat, and scheduled calls.

Why paid support?

Paid support ensures you get reliable, professional assistance when it matters most.

Get in touch

If you’re interested in paid support, contact us at dukefirehawk.apps@gmail.com with your contact and use cases. We will get back within 24 hours.