# Novu's default branch is next, and its SDKs sit on different major versions

> Novu is a TypeScript notification and agent-messaging platform sold as one API and one unified conversation model, with a React Inbox component and an ACI layer for connecting an existing agent to Slack, Telegram, and WhatsApp. The repository underneath is a large pnpm and Nx monorepo whose onboarding path does not match its getting-started link.

**novuhq/novu** — The open-source communication infrastructure for agents and products

- Repository: https://github.com/novuhq/novu
- Website: https://go.novu.co/github
- Stars: 40,099 · Forks: 4,506
- Language: TypeScript
- License: NOASSERTION
- Published: 2026-08-17 · Updated: 2026-08-18 · Language: en
- Canonical page: https://hysenlabs.com/projects/novuhq-novu

## The default branch is next, and three license files sit at the root

Two things about the repository's identity are worth knowing before you clone it. The default branch is `next`, not `main`, so a plain clone gets you the next major rather than the line the releases are cut from. And the license does not resolve to a single identifier, because the root carries `LICENSE-MIT`, `LICENSE-ENTERPRISE`, and a separate `EE-PACKAGES-LICENSE` alongside an `enterprise/` directory.

That combination is the shape of a project with an open core, and it means the licensing question is per package rather than per repository. A team that reads only the repository-level license field sees a value that tells them nothing about the specific package they are about to depend on. The three files are the answer; the metadata field is not.

Two other root entries have no explanation in the README at all. `domain-connect/` sits beside `apps/`, `libs/`, `packages/`, and `enterprise/` without a line of documentation, and `_templates/` is where the code generators read from, which the `g:module` and `g:usecase` scripts confirm. A reader mapping the tree will hit both and find nothing on the page to resolve them.

## @novu/framework is on 2.14.0 while @novu/react is on 3.19.2

The recent releases are three different packages, and they are not on the same version line. `@novu/framework` shipped v2.14.0 on 2026-09-28. `@novu/react` shipped v3.19.2 on 2026-09-07 and `@novu/nextjs` shipped v3.19.2 on 2026-09-07, one second apart, which tells you the React and Next.js packages are cut as a pair.

So the framework package sits a full major version behind the two SDK packages, and its last release is three weeks more recent than theirs. The version numbers are per package, not coordinated across the monorepo, which is normal for a large SDK set and has one practical consequence: `npm install @novu/react` tells you nothing about which framework version resolves underneath it. A lockfile is the only place that relationship is written down.

The cadence also differs by package rather than by release train. If you upgrade the React component on its own, you are taking a 2.x framework alongside a 3.x SDK, and whether that combination is the one the maintainers test is not something the release list will tell you.

## Getting Started is a signup link, and the only command runs the showcase

The Getting Started section is one sentence: create a free account and follow the instructions on the dashboard. For a project whose pitch is that it is open source, that is the whole self-service path, and it points at hosted infrastructure rather than at your own machine.

The repository does contain a `docker/` directory. The README does not reference it. So a reader who wants to self-host has a directory and no instructions, and the documented alternative is an account on someone else's dashboard.

There is exactly one runnable command in the README, and it is not for the platform:

```bash
npx novu@latest connect
```

That belongs to Novu Connect, a showcase that wires an existing Claude Managed Agent into Slack, Telegram, or email as a teammate, which the README says takes less than two minutes. It is worth running, because it is the fastest way to see what ACI is supposed to feel like, and it is worth being clear about what it is not: a self-hosted deployment of the notification platform.

## There is no single build command; build and build:v2 cover different projects

The root manifest is a workspace shell named `root`, marked private, pinned to `packageManager: pnpm@11.0.9`, and every real command delegates to Nx. The build scripts overlap without nesting cleanly:

```json
"build": "nx run-many --target=build --all --exclude=nextjs,nestjs",
"build:v2": "nx run-many --target=build --all --projects=@novu/api-service,@novu/worker,@novu/ws,@novu/dashboard,tag:type:package"
```

Those two differ in method. One runs everything except two framework packages; the other names four services plus a project tag. Alongside them sit `build:packages`, which builds only what carries `tag:type:package`, `build:agents` with its own `prebuild:agents`, and per-service targets for the api-service, dashboard, webhook, worker, ws, and inbound-mail.

So there is no answer to the question a new contributor asks first, which is the one that produces a system I can start. `build` and `build:v2` are not synonyms, and the difference is an exclusion list in one case and a project list in the other. Budget time to work out which one your target needs, and note that the project tags are declared in `nx.json` rather than anywhere the README points you to.

## dev:portless runs a process orchestrator, and a clone needs submodules

Local development does not start with a compose file you wrote. `dev:portless` runs `node scripts/mprocs-dev.mjs`, backed by an `mprocs.yaml` at the root, and `dev:config` runs `node scripts/novu-dev-config.mjs`. Configuration for a local run is generated by a script, and the process graph comes from a YAML file whose format you have to learn before you can change it.

Alongside that, `dev:thalamus-observer` and `dev:socket-worker` start two specific services by filter. Those names are internal architecture vocabulary rather than anything a newcomer would guess, and they are the visible edge of a service topology that the README never describes.

The toolchain has its own prerequisites. `.nvmrc` pins Node, `packageManager` pins pnpm to an exact version that a strict corepack will insist on, and `.gitmodules` means the repository carries git submodules, so a fresh clone without submodule initialisation gives you an incomplete tree with no error at the point where you would notice. `renovate.json` handles dependency updates, `.husky/` and `.lintstagedrc.js` gate commits, `biome.json` with `biome-plugins/` handles lint and format, and `jest.config.js` handles tests. That is a well-instrumented repository. It is also a lot of configuration to read before your first build.

## Only React has an Inbox component; Vue and Angular are coming soon

The embeddable Inbox is the part of Novu a product team actually puts in front of users, and it ships for one framework. The README points to React for the ready-made component and offers the API and SDK as the alternative for everyone else, then states that React Native, Vue, and Angular are coming soon.

So a Vue or Angular team has two paths and neither is free. Build the notification centre yourself on the API and SDK, which means owning the unread count, the read state, the realtime connection, and the preferences surface, or wait. The preferences component has the same constraint, since it is described as embeddable without a framework list of its own.

That constraint is the sharpest limit in an otherwise broad channel story. The delivery side is genuinely wide, with Inbox and In-App, push, email, SMS, and chat behind one API, but the surface your users touch is the narrowest part, and it is the part that has to look like your product rather than like Novu.

## ACI normalizes inbound messages, which is where the abstraction earns its keep

Agent Communication Infrastructure is the half of Novu that is not about notifications, and its mechanism is stated plainly. Novu receives inbound messages from each channel, normalizes them into one consistent shape, routes them to your agent, and sends the agent's responses back out. The README's own summary of the benefit is that you integrate once instead of building and maintaining a webhook handler per platform.

That is the actual argument, and it is a plumbing argument rather than a model argument. Slack, Microsoft Teams, Telegram, WhatsApp, email, and an in-app inbox each have their own payload shapes, threading semantics, and send paths, and a team wanting an agent in all of them otherwise maintains that matrix itself. Novu states the boundary plainly: you build the agent, Novu gives it a voice, and Novu connects the agent to the world rather than being the agent itself.

The Novu Connect command is the fastest way to judge whether that normalization is good enough for your channels, because it puts a real agent behind a real one in under two minutes.

## The provider generator shells out to npm inside a pnpm workspace

New code in this repository is generated rather than written, which is the right call for a codebase this size. `g:module` runs `hygen module new` and `g:usecase` runs `hygen usecase new`, both taking their name and module from pnpm config variables, so the module boundary is enforced by a template in `_templates/` rather than by convention.

Then there is the provider generator, and it is worth reading closely:

```json
"generate:provider": "cd libs/automation && npm run generate:provider"
```

That is npm inside a repository whose root pins `packageManager: pnpm@11.0.9` and which carries `pnpm-lock.yaml` and `pnpm-workspace.yaml`. The two package managers resolve differently, so the one script that adds a channel provider is also the one most likely to produce a tree that differs from everyone else's. If you are adding an integration, run it early and check the lockfile afterwards.

One more script deserves a look before you run it. `clean` invokes rimraf against build, dist, and node_modules paths at every depth, with the globs unquoted rather than escaped for the shell. That is a broad target for a script named clean, and it is worth reading twice.

## Conclusion

Novu fits a product team that wants one integration across Inbox, email, SMS, push, and chat, or a team with an existing agent that needs a voice on real channels without writing a webhook handler per platform. Do not clone the default branch expecting a stable release, because that branch is `next`, and do not plan a Vue or Angular Inbox, since the README lists both as coming soon. Verify three things first. Which license covers the packages you intend to use, because the repository ships LICENSE-MIT, LICENSE-ENTERPRISE, and an EE-PACKAGES-LICENSE side by side, which is why the project does not resolve to a single license identifier. Which framework version you are actually installing, since @novu/framework is at 2.14.0 while @novu/react and @novu/nextjs are at 3.19.2. And which build script produces a runnable system, because `build` and `build:v2` cover different project sets.

## FAQ

### What does Novu stand for?

The README does not expand the name. It describes the project as open-source communication infrastructure for agents and products, built around one API and one unified conversation model covering Inbox, Email, SMS, Push, Chat, Slack, Microsoft Teams, and Telegram.

### What are the benefits of using Novu?

For products, one API across Inbox and In-App, email, SMS, push, and chat instead of a separate provider integration per channel, plus a workflow engine with branching, a digest engine, and embeddable Inbox and preferences components. For agents, ACI normalizes inbound channel messages into one shape and sends replies back out, so you integrate once rather than per platform.

### Is Novu free to use?

The repository ships `LICENSE-MIT` next to `LICENSE-ENTERPRISE` and a separate `EE-PACKAGES-LICENSE`, with an `enterprise/` directory, which is why the project does not resolve to a single license identifier. The documented getting-started path is a free account on the hosted dashboard rather than a self-hosted install.

## Sources

- [Official documentation](https://go.novu.co/github)
- [Official README](https://github.com/novuhq/novu#readme)
- [Project repository](https://github.com/novuhq/novu)
- [Release notes](https://github.com/novuhq/novu/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/novuhq-novu