Overview

Public roadmap for MiiaJS - what is shipped, what is coming, and how items are prioritized.

This page is a living plan. It exists so you can see where MiiaJS is going before you adopt it - and so contributors can pick up something that matches their interest. Items move forward when there is a real reason to do them: an example app needs them, a user reports a gap, or production usage exposes a missing primitive. Nothing on the list is a promise of a date.

The repo is pre-1.0; the public API is allowed to evolve. After the first stable release this page will split into "shipped" and "planned" with semver-respecting deprecation cycles for breaking work.

Principles that don't move

These are not roadmap items - they are constraints every roadmap item is checked against.

Web Standards first. No Express.Request, no proprietary Reply. Anything new must compose with Request/Response/Headers/URL and run on Bun, Deno, and Node.
Decorators for declarations, middleware for control flow. Koa-style middleware replaces interceptors, pipes, and filters. New features should not introduce a fourth lifecycle layer just because NestJS has one.
Lightweight before clever. Each package earns its keep. If a feature is one screen of glue code on top of @miiajs/core, it stays in the host app or in an example - not a new package.
Per-app DI container, flat by default. Module scoping arrives only when there is a concrete user request that flat DI cannot solve.
Real demand over theoretical completeness. A pattern lands when the second user asks for it, not the first time it sounds nice in a design doc.

Status legend

Each package and roadmap item carries a maturity label. Same scale as elsewhere in the docs.

Status	Meaning	How it advances
`experimental`	API may break, no proof of correctness. Low or no tests, untested failure modes. Use in side projects, expect churn.	Real-app validation surfaces edge cases, tests cover them, API stops moving.
`beta`	API mostly stable, well-tested internally, but the package has not faced real production load yet. Pre-1.0 default for any package shipped.	Production deployment, no P0/P1 issues for 60 days, semver freeze.
`stable`	API frozen with semver guarantees, production-tested at scale, community-validated. Post-1.0 only. No package can be `stable` while the project itself is on `0.x`.	Project ships 1.0; package keeps a clean track record across at least one minor cycle.
`planned`	On the roadmap. No code yet (or scaffolding only).	Design discussion lands; implementation begins; status moves to `experimental` on first publish.
`idea`	Direction we like; needs more demand or design before it becomes `planned`.	A second independent user asks for it, or a design doc resolves the open questions.

Where the project is today

Current package state, all on 0.1.0:

Package	Status	Tests	Note
`@miiajs/core`	beta	174	Foundation. DI, decorators, router, middleware, exceptions.
`@miiajs/node-server`	beta	28	Optimized Node.js HTTP adapter.
`@miiajs/uws-server`	beta	28	uWebSockets.js adapter, parallel optimization to node-server.
`@miiajs/swagger`	beta	63	OpenAPI 3.1 + Swagger UI.
`@miiajs/messaging`	beta	54	Decorator-driven event bus, retry, DLQ, idempotency, named buses.
`@miiajs/config`	beta	16	Zod-validated env via `ConfigService` + `ConfigModule.configure`.
`@miiajs/papr`	beta	19	MongoDB via Papr.
`@miiajs/mongoose`	beta	19	MongoDB via Mongoose.
`@miiajs/drizzle`	beta	17	Drizzle ORM (PG/MySQL/SQLite).
`@miiajs/auth`	beta	12	Strategy primitives, AuthGuard. Small surface; critical paths covered.
`@miiajs/jwt`	beta	6	JWT sign/verify (jose wrapper). Core logic tested upstream in `jose`.
`@miiajs/serve-static`	beta	49	Static file serving. Full HTTP semantics (Range, conditional GET, HEAD, dotfile guard, SPA fallback).
`@miiajs/cli`	experimental	49	Build/dev/scaffold CLI. Scaffolds not yet validated by real adoption.
`@miiajs/messaging-redis`	experimental	14	Redis Streams transport + idempotency store. Untested at production load; XAUTOCLAIM crash-recovery test still TODO.

Roadmap horizons

The list is split by realistic timeframes, not strict commitments. Items can move up if real demand surfaces; items can move down if a use case goes cold.

Short term (0-3 months) - hardening: validate experimental packages on real apps, file upload, rate limiting, body size limits, server-sent events.
Mid term (3-9 months) - production essentials: WebSocket, OpenTelemetry, cache abstraction.
Long term (9-12+ months) - ecosystem: NATS transport, GraphQL, request-reply, type-safe RPC client.

Road to 1.0

1.0 is gated by facts on the ground, not a date. Concrete criteria:

At least 3 independent production users. Pre-1.0 friends-of-friends do not count - need teams that can answer "what broke" with telemetry, not opinions.
All beta packages have zero open P0/P1 API issues for 60 consecutive days. Bug fixes are fine; design churn is not.
Semver deprecation policy documented and exercised at least once. A breaking change shipped through a deprecation cycle, removal in the next major.
Benchmarks frozen. Stable numbers vs Hono/Elysia in the miiajs/benchmarks repo, regression CI gate in place.
API freeze period. Minimum two months in 1.0.0-rc.x before final.
Examples coverage. At least one example app per shipped package. As of 0.1, every package is covered by an example - examples/full-app exercises core/config/auth/jwt/drizzle/swagger/serve-static, examples/messaging-app covers messaging + messaging-redis, the dedicated DB examples cover papr/mongoose, and examples/uws-app covers the uWS adapter. Coverage for new packages must land alongside the package itself.

Anything not on this list is nice-to-have, not gating.

How items get prioritized

Roughly in this order, top wins:

Validate experimental packages on real apps. @miiajs/cli and @miiajs/messaging-redis need real-adoption shakedowns before they earn beta. Internal tests are not enough.
Production essentials missing from existing packages. Multipart, rate limiting, body size limits, SSE. These unblock real apps for real deployments.
High-impact abstractions. WebSocket, OpenTelemetry, cache - each enables a class of apps but doesn't depend on niche infrastructure.
New transports / integrations. NATS, GraphQL, RPC client. Niche-r, but each opens a deployment lane.
Polish. DX improvements, better error messages, examples coverage. Continuous, not project-managed.

How to influence the roadmap

Open an issue describing the problem (not the solution). Real workloads beat hypothetical ones.
Bring a use case from production. "I'd use this if it had X" is the strongest signal.
Submit a PR. Pre-1.0 is the cheapest time to land breaking design improvements.

The roadmap will be revised when meaningful items ship or new ones emerge - probably every couple of months.

uWS Server

uWebSockets.js HTTP server adapter for maximum throughput.

Short term (0-3 months)

Hardening and gap-fills - what gets attention next.