novuhq
novu-dotnet & novu-csharp
Hello!
I see that a new .NET SDK for NovuAPI has been created - novu-csharp.
I would like to ask how this would generally affect the development and future of novu-dotnet?
Something like thisāI am trying to get to the bottom of this. This will change as there is a new 2.2 release on the horizon. Please add below what you are wanting for reference.
https://github.com/novuhq/novu-dotnet/pull/110#pullrequestreview-2835529867
Versioning and the Shift to v2.x
As Novu evolves, its ecosystem has split into two main branches:
-
Novu Cloud ā The hosted, commercial SaaS service (currently
v2.1.1) -
Novu Project ā The open-source, self-hostable distribution (currently
0.24.x)
The novu-dotnet SDK is maintained with this bifurcation in mind. This section clarifies which environments are supported, what versions to use, and how the project roadmap reflects the ongoing direction of the broader Novu ecosystem.
Novu Project: Recommended for Self-Hosting
We refer to the open-source edition of Novu as the Novu Project. This tracks the 0.x version line and is the recommended base for all self-hosted deployments.
- The
0.xline (latest:0.24.x) remains the only documented and stable path for self-hosting. - The
v2.xAPI used by Novu Cloud can technically be self-hosted, but this remains undocumented and unsupported for now. - Crucially, many of the
0.xendpoints still work inv2.xdeployments, but these are excluded from the OpenAPI spec, meaning they are unsupported and subject to unannounced changes.
SDK Support Strategy
The novu-dotnet SDK will not support the v2.x OpenAPI specification. It is committed to tracking the 0.x API surface area as long as it remains active in the Novu Project.
| Project | Description | SDK Support | Notes |
|---|---|---|---|
| novu-dotnet | Community-maintained SDK for 0.x Novu Project versions |
Full (0.18+ to 0.24.x) |
Targeted for self-hosted environments < 0.x |
| novu-csharp | Official SDK tracking Novu Cloud v2.x+ API |
Full (2.x) |
Starts from SDK version 1.x and beyond |
All novu-dotnet releases will continue to use the 0.x version range, reflecting its tight alignment with the Novu Project. Future breaking or structural changesāif necessaryāwill still respect the semantic versioning guidelines under the 0.x umbrella.
Guidance for Developers
- Use
novu-dotnetif you are integrating with Novu Project (0.24.x) or environments based on0.xAPI behavior. - Use
novu-csharpif you are building for Novu Cloud (v2.x) and require compatibility with the OpenAPIv2spec. - Avoid mixing the two SDKsāthey serve different environments and version lifecycles.
@toddb, thank you for these clarifications! Such a document would be very helpful.
One additional question ā Iām not sure whether this is the right place, but still:
Why is Novu Project so far behind Novu Cloud in versions? As far as I know, they are both developed in a single repo - novu. How is the difference between these two versions achieved? Will it increase over time...? If the Novu Project continues on version 0.x, it may give the impression of being permanently in alpha.
@atanas-todorov-assent Great question ā and honestly, one I've been digging into myself. (Also agree this isnāt the ideal place for this kind of discussionā¦ but where else? š )
Why is Novu Project so far behind Novu Cloud in versions? As far as I know, they are both developed in a single repo - novu. How is the difference between these two versions achieved? Will it increase over time...? If the Novu Project continues on version 0.x, it may give the impression of being permanently in alpha.
Hereās what Iāve found out so far:
- Novu is in the middle of a strategic shift toward a code-first architecture, which is the basis of the 2.x (Cloud) release.
- However, they still want to support the no-code (UI-based) experience, especially for non-developer users.
- It seems the long-term plan is to have both code-first and no-code coexist, with the no-code editor ultimately generating code-first workflows behind the scenes (rather than use the current implementation).
- The current no-code editor requires extra infrastructure and abstractions that are not yet compatible with the new code-first architecture.
- Because of that, the self-hosted āNovu Projectā version is staying pinned at 0.x, while they figure out how to migrate and align the no-code experience into the code-first foundation.
So in short: the version gap is intentional (for now) and reflects the architectural transition. Itās not necessarily a lack of support for self-hosted, but rather a matter of timing and technical complexity in aligning both approaches.
My questions back to them was:
Why not retain the existing abstractions and simply extend them with code-first abstractions? That would preserve continuity while allowing the platform to evolve.
Interestingly, theyāve instead opted for:
- Two full rewrites (which version 2 is only the first)
- Plus a migration path to bridge the gap
This is a bold approach, but it introduces some fragmentation in the short term (which has turned to be the medium term). Whether this pays off long-term will depend on how seamlessly they can unify the experiences and migrate users across.
Hope that helps clarify! Let me know if youāve found anything different ā Iām actively tracking this too.
Very interesting and very helpfulā¦ Thank you, @toddb! I think this explains some of the things.
A few additional clarifications:
As Novu evolves, its ecosystem has split into two main branches
I guess by ābranchesā you donāt mean āgit branchesā š ā but still, my question here is: Are both the Novu Project and Novu Cloud developed in the novu repo? Or there is a private fork of the public repo for Novu Cloudā¦
So in short: the version gap is intentional (for now) and reflects the architectural transition. Itās not necessarily a lack of support for self-hosted, but rather a matter of timing and technical complexity in aligning both approaches.
Does this mean (in general) that whatever functionality is developed in Novu Cloud it will also become available (sooner or later) in the Novu Project? And I don't mean the key differences, but rather core functionalities.