Apostrophe 4.33.0: Faster In-Context Editing, and Steadier Rolling Deploys

When first posted, this announcement mentioned a lighter admin UI JavaScript bundle. That has been postponed to September because it is a feature, not a fix, and this is a maintenance release.

You need a supported version of Node.js

While this technically became a requirement last month, it bears mentioning: ApostropheCMS now requires Node.js 22.12 or newer. This requirement doesn’t really come from us: Node.js 20.x is officially unsupported and should not be used in any case, and older versions of Node.js 22 should not be used because they do not have the fixes in more recent releases, including security fixes. So with that in mind, we are now taking advantage of features requiring up to date releases of Node.js 22 or better.

Faster In-Context Editing

Two changes make editing widgets on the page noticeably quicker. Patches to deeply nested properties have been optimized, so an edit to a single widget in context no longer costs the same as saving the entire page through the page settings dialog. Separately, widget preview rendering is now properly debounced: when the server hasn't returned a first preview before a second one is requested, Apostrophe waits for the render in flight and then works from the latest data rather than stacking requests. For widgets that are slow or expensive to preview, this meaningfully reduces server load.

We're treating both as fixes rather than features. The nested-property issue in particular was acute enough to prevent effective editing in some cases.

We will continue to deliver optimizations in this area.

Steadier Rolling Deploys

Schema field _id values are now derived from a field's position in the schema tree, such as doc.article.pets.petName, rather than hashed from the field definition. Under the old scheme, editing an unrelated property like a label changed the hash, so two processes running slightly different code (— exactly what happens during a rolling deploy) — disagreed about ids, and a field id the browser already held could be rejected as invalid. Position-based ids only change when a field is genuinely renamed or moved, and they have the pleasant side effect of being readable when you're debugging.

For developers: apos.schema.register now requires a fourth parentPath argument and throws if it's missing. If you've overridden a method that calls it, pass the argument through — the error message includes guidance. No migration is needed: scopedArrayName and scopedObjectName keep their existing form for now, since they're stored in the database on every array item and object.

Additional Improvements

• Filtered piece index pages using piecesFilters with static: true no longer revert to the unfiltered index for logged-in editors who have clicked Edit. Both the browser URL and the filtered content now survive a refresh.

• Email schema fields now trim surrounding whitespace rather than rejecting an otherwise valid address, and non-string input sent through the REST API is coerced instead of throwing. Thanks to spokodev for the fix.

• Logging in on a session that had just been invalidated by a password change or a disabled account no longer produces a 500 error.

• Admin UI sizing and spacing is corrected in webpack builds, where a byte order mark had been invalidating the rule that sets box-sizing on Apostrophe elements. Vite builds were unaffected.

• For Astro projects, OAuth login callbacks proxied through the integration no longer lose their Set-Cookie header. Thanks to Erika for this fix. AposTemplate.astro also now forwards additional props through to the resolved page template component, matching how AposArea and AposWidget already behaved.

How to Update

Update your projects with npm update and let us know what you think on our roadmap.

The “stable” option

Our Hosting, Pro and Assembly customers also have the option of following our “stable” releases. The difference is simple: The stable releases receive new features one full quarter later, but receive bug fixes and security fixes at the same time as “latest.” In order for this to be an effective technique to increase stability, customers still need to actively evaluate “latest” so that they have meaningful head start on what is coming in “stable.” Customers interested in following this path should reach out for complete information on how to point their dependencies to “stable.”

Everything we ship as “latest” is 100% ready for production. The “stable” series is an option for those with a large investment in training, automated testing, etc. It allows delayed implementation of new features without falling behind on fixes.

🚀 Happy coding!