Adoption

What adopting Nexus actually means.

License terms, governance structure, support channels, and what happens if the project changes direction. Honest answers before you commit production systems.

⚖️

License & IP

Nexus is released under the MIT License. Every package under packages/ is published independently to Packagist under the same terms. You can use, modify, fork, and distribute Nexus in commercial products without a licensing agreement.

  • ✓ Commercial use — no fee, no notice required beyond the MIT attribution line
  • ✓ Modification and redistribution — fork the monorepo or any individual package
  • ✓ No CLA required — contributors retain copyright on their patches
  • ✓ Sublicensing — you can ship Nexus inside a proprietary product without open-sourcing your code

The full text lives at github.com/nexus-actors/nexus/blob/main/LICENSE.

🏛️

Maintainers & Governance

Nexus is developed under the nexus-actors GitHub organisation. The project is small and honest about it: a core maintainer team makes architectural decisions; external contributions are reviewed and merged via pull request.

  • → Architecture and roadmap decisions are made by the core maintainer(s) and documented in GitHub Discussions
  • → Breaking changes follow semver and ship in major versions — with a CHANGELOG entry and migration notes
  • → Security reports: open a GitHub Discussion — do not file public issues for vulnerabilities
  • → Contributions welcome — the easiest entry points are test coverage, documentation, and compatibility packages
💬

Support

V1 ships with community-tier support only. There is no paid support tier yet — that will be evaluated based on adoption. Here is what you can rely on:

Community (available now)

Commercial (not yet)

Priority response, private channels, and SLA-backed support are planned for a future release. If your team needs this today, open a GitHub Discussion thread — early conversations shape the offering.

📈

Is Nexus ready for production?

The stability matrix at /stability gives the per-package answer. The short version: core actor system, FiberRuntime, SwooleRuntime, persistence, and HTTP are all Stable. nexus-cluster (multi-machine routing) is Experimental.

If you are evaluating Nexus for a new service, the right question is not "is it stable?" but "does it match the problem?" The When to use actors guide gives an honest answer based on workload characteristics — not marketing claims.

Nexus is a V1 release. The API surface is intentionally narrow. Packages that are not ready are not shipped — the monorepo has not-yet-published packages behind feature flags. What is in the stable set is there because it has test coverage, Psalm level-1 analysis, and integration tests across both FiberRuntime and SwooleRuntime.

🔁

Project continuity

What happens if the maintainers change direction, hand off the project, or stop actively developing it?

  • → MIT = forkable by anyone. If development stalls, any team can fork the monorepo and continue. No relicensing, no CLA, no negotiation required.
  • → Individually published packages. Each of the 25 packages under packages/ is split to its own GitHub repo via splitsh-lite and published to Packagist independently. A monorepo restructure does not break composer require nexus-actors/core.
  • → Semver with a CHANGELOG. Breaking changes are gated to major versions. The CHANGELOG documents what changed and why. Migration guides ship alongside breaking releases. The criteria for a major bump are defined in the versioning policy.
  • → Be the first production user. Nexus has no "used by X" list yet. Early adopters shape the roadmap directly — open a GitHub Discussion and it gets read by the people who write the code.
✅

Evaluation checklist

Work through these questions before committing Nexus to a production service. None of them are blockers — they are context that helps you set realistic expectations.

□ Do you need long-lived state? If your service is stateless request-response with no shared mutable state, the actor model adds complexity without benefit. Actors shine when state lives longer than a single request.
□ Can your team run Psalm Level 1? Nexus relies heavily on Psalm generics for type safety. If your existing codebase has significant Psalm violations, plan time to clean those up before introducing ActorRef<T> generics.
□ Do you need PHP-FPM compatibility? FiberRuntime requires PHP 8.5+. SwooleRuntime requires the Swoole extension. If your deployment environment cannot run either, Nexus is not yet the right fit.
□ Have you scoped the PoC? Pick one isolated service with a clear bounded context — not the most critical system you run. Implement it in Nexus, run it in production for a few weeks, and evaluate before expanding.
□ Do you have a monitoring strategy? Actors are long-lived processes. You need process supervision at the OS level (systemd, Docker restart policy) on top of Nexus's own supervision. PSR-3 logging and PSR-14 event dispatching are the integration points for your existing observability stack.
🔬

Scoping a proof of concept

The fastest path to a useful evaluation is a small, isolated service that exercises the specific properties you care about — not a port of your entire backend.

Good PoC candidates

  • A wallet or balance service with audit-log requirements — exercises event sourcing and single-writer guarantees
  • A WebSocket notification service — exercises actor-per-connection and pub/sub channels
  • A device telemetry ingestor — exercises passivation and bounded mailboxes under high volume
  • A multi-step approval workflow — exercises Saga actors and durable state

PoC scope: keep it narrow

  • One bounded context, one actor tree, one persistence backend
  • Integration tests using StepRuntime — they run in CI without Swoole
  • FiberRuntime in development; SwooleRuntime in staging/production
  • Measure: latency, memory stability under load, restart-recovery time
Quick Start — working actor in 5 minutes →
📈

Incremental adoption path

You do not need to rewrite your existing application to use Nexus. The typical adoption curve looks like this:

  1. 1
    New service, isolated — Start Nexus in a new service that does not share code with your existing application. Pick a bounded context where the actor model has a clear advantage (state, concurrency, event sourcing). Ship it, observe it.
  2. 2
    Extract a stateful subsystem — Identify a part of your existing application that is already stateful but clunky (a Redis-backed counter, a cron-driven processor). Replace it with an actor behind a thin adapter. Your existing code still calls the adapter — the actor is invisible to it.
  3. 3
    Add Nexus HTTP to one route group — If your application handles WebSockets or high-concurrency reads, migrate that route group to Nexus HTTP while leaving the rest on PHP-FPM. Use a reverse proxy to split traffic.
  4. 4
    Evaluate full migration — Once your team is fluent with the actor model and you have observability in place, assess whether migrating the rest of the application delivers enough value to justify the cost.
⚠️

Common gotchas

Things teams most often trip over in their first Nexus project.

Blocking I/O inside handlers

sleep(), file_get_contents(), and synchronous database calls block the Fiber or coroutine. The nexus-psalm plugin catches the most common cases at analysis time. For HTTP clients and DB access, use async-aware libraries (Swoole coroutine-native clients) or route the I/O through a dedicated actor.

Shared mutable state in closures

Props factory closures captured by reference (&$var) break the single-writer guarantee. The Psalm plugin catches this. Keep all actor state inside the actor — if you need to share state between actors, pass messages.

Asking from inside a handler without a timeout

An ask() without a bounded timeout can deadlock two actors waiting on each other. Always supply a Duration timeout. Keep ask chains short — deep ask chains amplify latency and increase the risk of timeout cascades.

Spawning too many actors

Each actor allocates a mailbox and a Fiber/coroutine. For workloads with millions of entities, use passivation — actors that are not actively receiving messages write state to persistence and stop. The passivation guide covers the EntityRefFactory pattern for transparent reactivation.

Start evaluating Nexus today.

The quick-start takes five minutes. The stability matrix answers the per-package readiness question.

composer require nexus-actors/nexus
Quick Start Stability matrix