Wheels 4.0.0 — GA release notes

[bpamiri]

Wheels 4.0.0 is released today.

By the numbers

• 260+ merged PRs across ~15 weeks since the 3.0.0 stable tag.
• ~75 distinct user-visible features and changes.
• 40+ security-hardening PRs — a full section in the audit.
• 7 breaking changes — each covered in the upgrade guide with detect / fix / opt-out guidance.

Headlines

• wheels deploy — port of Basecamp's Kamal into the Wheels CLI. Zero-downtime Dockerized deploys to Linux servers over SSH. No Ruby runtime. Byte-compatible with Kamal on the server side.
• Data layer — bulk insert/upsert with per-adapter native UPSERT (7 databases), polymorphic associations, advisory locks, pessimistic locking, chainable injection-safe query builder, enums, named scopes, batch processing, CockroachDB adapter, auto-migrations from model diffs with rename detection.
• Testing — browser testing via Playwright Java, HTTP test client, parallel test runner, WheelsTest BDD as the sole style for new tests.
• Multi-tenancy — per-request datasource switching in-core. Tenant-aware background jobs work natively.
• Background jobs — DB-backed queue with persistent worker daemon, optimistic locking, timeout recovery, configurable exponential backoff, live dashboard. No Redis.
• Security — 40+ hardening PRs across SQL injection, path traversal, console/reload endpoints, CORS/CSRF/HSTS defaults, rate limiter, MCP. Secure by default.
• Middleware pipeline — first-class middleware layer with built-in rate limiting, CORS, security headers, request ID.
• Router modernization — group(), typed constraints (whereNumber, whereAlpha, whereUuid, whereSlug, whereIn), API versioning, route model binding, indexed lookup.
• DI container — request-scoped services, declarative inject(), auto-wiring, interface binding.
• Package system — packages/ → vendor/ activation model with dependency graph, per-package error isolation.
• Engine adapters — dedicated modules for Lucee, Adobe CF, BoxLang. Railo dropped.
• Developer experience — LuCLI-native CLI, zero-Docker inner loop, ~60s full test suite on SQLite. CI runs the same stack.
• AI integration — stdio MCP (wheels mcp wheels) for IDE assistant integration. Auto-generates .mcp.json via wheels mcp setup.
• Vite pipeline — transitive modulepreload + CSS resolution for multi-entry Vite builds.

Breaking changes (7)

Full detect / fix / opt-out guidance for each in the upgrade guide:

1. wheels snippets renamed to wheels generate snippets.
2. CFWheels → Wheels rebrand in active code namespaces.
3. testbox → wheelstest namespace (new tests extend wheels.WheelsTest).
4. tests/specs/functions/ → tests/specs/functional/.
5. Legacy RocketUnit removed from core (existing specs still run).
6. CORS default: wildcard → deny-all.
7. allowEnvironmentSwitchViaUrl false in production; non-empty reload password required.

The Legacy Compatibility Adapter provides a soft-landing path for staged migrations.

Where Wheels now stands

Against Rails 8, Laravel 12, and Django 5, most of the rows that said "No" for CFWheels now say "Yes" for Wheels 4.0. Honest remaining gaps:

• Ecosystem size — smaller than peer frameworks; not a short-term fix.
• Bidirectional WebSocket — intentional non-goal; SSE with pub/sub channels is the cross-engine-uniform primitive.
• Asset-pipeline maturity — Vite integration improved in 4.0 but newer than Rails' / Laravel's.

Full comparison: https://github.com/wheels-dev/wheels/blob/develop/docs/wheels-vs-frameworks.md

Links

• Upgrade guide — start here if you're on 3.x.
• CHANGELOG — the canonical what-changed list.
• Full feature audit — PR-level receipts for every user-visible change.
• 3.0 → 4.0 row-by-row — only rows that changed; each tagged and linked.
• Framework comparison — where 4.0 lands against peer frameworks.
• Deployment: landing, first deploy, migrating from Kamal.

Contributors

Thanks to @bpamiri (Peter Amiri), @zainforbjs, @chapmandu, @mlibbe, @MukundaKatta, plus Dependabot. And to everyone who filed issues, tested release candidates, and pushed for corrections in the audit.

What's next

4.0.x point releases will focus on asset-pipeline maturity (the known remaining peer-framework gap), documentation polish, and ergonomics feedback from early adopters. The follow-ups section of the audit tracks specific candidates.

If Wheels 4.0 unblocks a project you've been deferring, we'd love to hear about it in this thread.

Read the full post: https://blog.wheels.dev/posts/wheels-4-closing-the-maturity-gap/

[zainforbjs]

Really excited to see Wheels 4.0 finally out. A huge amount of work clearly went into this release across testing, deployment tooling, security hardening, CLI improvements, and overall developer experience.

What stands out to me most is that 4.0 doesn’t just add features for the sake of it — a lot of the changes solve real-world development and operational problems that teams actually deal with in production.

The new direction around wheels deploy, Playwright browser testing, parallel testing, stronger security defaults, and improved local workflows makes the framework feel much more aligned with modern development expectations while still keeping the simplicity that made Wheels productive in the first place.

Definitely worth reading through the 4.0 docs at guides.wheels.dev because there’s a lot more depth in this release than a quick summary can show.

[mikegrogan]

Hope to be able to start reviewing all the changes! I'm assuming upgrading from 2.5 has to go to 3 first and then 4? Took me a minute to find the upgrade page to get to 3! Thought it was lost. https://guides.wheels.dev/v3-0-0/introduction/upgrading/.

Kudos to all the work Peter. Barely recognize wheels with all these updates. I realize keeping an eye on the commits this might have been AI enhanced to some degree. Assuming care was taken to make sure there are plenty of tests to make sure things don't break. Again, I need to review more, but it's very impressive. An idea for a blog post is how you were able to make all this happen so quickly. Hopefully help others get involved.

Trying to figure it out the logo needs updating? Seems like the site is dark mode by default now, but the logo is setup for light maybe?

[bpamiri]

AI is used, not trying to hide that, but adversarial review processes, advisor model pattern, and plane old TDD are used throughout the process. Right now when an issue is filed, an AI agent will triage the issue and try to bucket it into bug, feature request, doc change, other, etc. It will also give a confidence score high, medium, low of how it feels about the proposed solution. Regardless of what confidence tag something gets, another AI Agent will analyze the complexity and downgrade the confidence if the proposed solution touches too many layers of the framework or cross functional fixes. After those phases high confidence issues are dispatched to an AI agent for implementation, Medium and Low confidence issues are held for human review. The implementor agent will propose a solution and open a PR. This is where the fun starts, Agent Reviewer A will review the PR and analyze it on several levels and propose changes, good to go level comments, then Agent Reviewer B will review and critique Reviewer A's review. If A and B are not aligned, they go back and forth till they get into alignment, if they can't they call on an Advisor Agent to arbitrate and get them into alignment. Meanwhile implementor agents are working along side the reviewers to get things implemented. All along the way CI is running tests and agents are validating and fixing things that pop. The TDD approach makes sure the test harness is continuously improving. Eventually the PR has a green CI state and waits for human review and merge. Nothing is merged into the repo automatically.

This is essentially the pattern the Bun team use to improve Bun. Take a look at https://www.youtube.com/live/DlTCu_pNDHE?si=vlY9azBHDbaQ_Onk if you get a chance where Boris and Jarred go through this flow. Jarred mentions he has seen the two reviewers go back and forth for over 100 rounds. I've seen them get up to eleven rounds in our workflow.

[mikegrogan]

Very interesting. Thanks for sharing.

[mikegrogan]

This answered my 2 -> 3 and 3 -> 4 question.
https://guides.wheels.dev/v4-0-1-snapshot/upgrading/2x-to-3x/

[bpamiri]

Ya, I need to figure out how to make the boundaries better discoverable and have better long lived links. Right now Main is the stable branch and Develop is the next snapshot branch. That is helping with the versioning cadence but is is making it difficult on the url to guides and things. During the snapshot phase the url to things will have a -snapshot in the url and when promoted to stable the -snapshot is currently stripped out which mean old links break all of a sudden. I'll have to address that at some point. Glad you found what you needed.