https://github.com/novaframework/nova
Web framework for Erlang.
https://github.com/novaframework/nova
api-server distributed erlang realtime web-framework
Last synced: 2 days ago
JSON representation
Web framework for Erlang.
- Host: GitHub
- URL: https://github.com/novaframework/nova
- Owner: novaframework
- License: apache-2.0
- Created: 2019-08-06T09:39:22.000Z (over 6 years ago)
- Default Branch: master
- Last Pushed: 2025-05-08T14:24:45.000Z (11 months ago)
- Last Synced: 2025-05-13T13:01:09.502Z (11 months ago)
- Topics: api-server, distributed, erlang, realtime, web-framework
- Language: Erlang
- Homepage: http://www.novaframework.org
- Size: 1.16 MB
- Stars: 237
- Watchers: 10
- Forks: 22
- Open Issues: 4
-
Metadata Files:
- Readme: README.md
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
- Codeowners: .github/CODEOWNERS
Awesome Lists containing this project
README
A web framework for the BEAM
Build fault-tolerant, distributed web applications in Erlang, Elixir, or LFE.
---
## Why Nova?
Nova is the web framework for the **BEAM**. Whether you write Erlang, Elixir, or LFE, Nova gives you the productivity of a modern web framework on the runtime you already trust:
- **Routing, controllers, and views** — familiar MVC patterns that map naturally to Erlang modules
- **Plugin pipeline** — composable middleware for auth, CORS, logging, and custom concerns
- **WebSockets and Pub/Sub** — real-time features backed by OTP's `pg` module, distributed out of the box
- **Session management** — ETS-backed by default, pluggable for custom backends
- **Template rendering** — ErlyDTL (Django Template Language) with hot reload
- **OTP-native** — your web app is a proper OTP application with supervision trees, hot code upgrades, and releases
Nova runs on [Cowboy](https://github.com/ninenines/cowboy) and supports **Erlang**, **Elixir**, and **LFE**.
## Quick start
Install the rebar3 plugin:
```bash
# One-line install
sh -c "$(curl -fsSL https://raw.githubusercontent.com/novaframework/rebar3_nova/master/install.sh)"
# Or add to ~/.config/rebar3/rebar.config
{project_plugins, [rebar3_nova]}.
```
Create and run your app:
```bash
rebar3 new nova my_app
cd my_app
rebar3 nova serve
```
Open [localhost:8080](http://localhost:8080) — you're running Nova.
## What a controller looks like
```erlang
-module(my_app_main_controller).
-export([index/1, create/1]).
index(#{method := <<"GET">>} = _Req) ->
{json, #{message => <<"Hello from Nova!">>}}.
create(#{method := <<"POST">>, json := Body} = _Req) ->
%% Validate, persist, respond
{json, #{status => <<"created">>, data => Body}}.
```
Route it:
```erlang
routes(_Environment) ->
[#{prefix => "/api",
security => false,
routes => [
{"/", {my_app_main_controller, index}},
{"/items", {my_app_main_controller, create}}
]}].
```
## Features
| Feature | Details |
|---------|---------|
| **Routing** | Path parameters, prefixes, per-route security, environment-based routing |
| **Controllers** | Return `{json, Map}`, `{ok, Variables}`, `{status, Code}`, `{redirect, Path}`, `{sendfile, ...}` |
| **Plugins** | Pre/post request hooks — built-in CORS, CSRF, correlation ID, or write your own |
| **WebSockets** | Full WebSocket support via `nova_websocket` behaviour |
| **Pub/Sub** | Distributed messaging via `nova_pubsub` — channels, topics, broadcast |
| **Sessions** | ETS-backed sessions with pluggable backends |
| **Templates** | ErlyDTL (Django-style) with hot reload via `rebar3 nova serve` |
| **Security** | Per-route security functions for authentication and authorization |
| **Static files** | Built-in file controller with range request support |
| **Observability** | [OpenTelemetry integration](https://github.com/novaframework/opentelemetry_nova) for tracing and metrics |
| **Database** | [Kura](https://github.com/novaframework/kura) — an Ecto-inspired database layer for Erlang |
## Request pipeline
```
Request → Cowboy → Nova Router → Plugins (pre) → Security → Controller → Plugins (post) → Response
```
## Ecosystem
| Package | Description |
|---------|-------------|
| [nova](https://hex.pm/packages/nova) | Core framework |
| [rebar3_nova](https://github.com/novaframework/rebar3_nova) | Project scaffolding and generators |
| [nova_test](https://github.com/novaframework/nova_test) | Testing utilities and request builder |
| [kura](https://hex.pm/packages/kura) | Database layer — schemas, migrations, changesets, queries |
| [rebar3_kura](https://github.com/novaframework/rebar3_kura) | Migration generator for Kura |
| [opentelemetry_nova](https://github.com/novaframework/opentelemetry_nova) | Automatic OpenTelemetry instrumentation |
## Documentation
- **[The Nova Book](https://novaframework.github.io/nova-book)** — step-by-step tutorial building a complete blog platform
- **[API Reference](https://hexdocs.pm/nova/)** — module documentation on HexDocs
- **[Quick Start Guide](https://hexdocs.pm/nova/quick-start.html)** — get up and running in 5 minutes
## Requirements
- Erlang/OTP 23+
- Rebar3
## Community
- [Erlang Slack](https://erlef.org/slack-invite/erlanger) — `#erlanger` channel
- [Nova Forum](https://erlangforums.com/c/erlang-frameworks/nova-forum/65) — questions and discussion
- [Issue Tracker](https://github.com/novaframework/nova/issues) — bugs and feature requests
## Contributing
Contributions are welcome! Check [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md) and look for issues labeled `good first issue`.
## License
[Apache 2.0](LICENSE)