Faster In-Context Editing, and Steadier Rolling Deploys

[BoDonkey]

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.

Hello Apostrophe Community!

Apostrophe 4.32.1 is a maintenance release: a focused round of performance work and fixes, hence the patch version number change. It contains two security fixes (see the Changelog below for details), so we recommend an update as soon as practical.

A Leaner Admin UI

The logged-in admin UI JavaScript bundle is roughly 200KB smaller minified — about 90KB gzipped — with no change in behavior. Two dependencies came out of it:. lodash is CommonJS and not tree-shakeable, so importing a single function pulled the entire library into the bundle; @paralleldrive/cuid2 brought its own dependencies along with it. The small set of utilities the browser actually needed now lives in a dependency-free module in core, fuzz-tested against the original implementations. Every editor loading the admin interface gets a faster start, on every page.

Speaking of which, we should mention one requirement that came into play starting last month: Apostrophe 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!

---

Apostrophe 4.32.1

Changes

• Schema field _id properties are now derived from the position of the field in the schema tree, such as doc.article.pets.petName, rather than hashed from the field definition. Ids hashed from the definition changed whenever an unrelated property such as a label was edited, so two processes running slightly different code, as during a rolling deploy, did not agree on them and a field id already held by the browser could be rejected as invalid. Position-based ids only change when a field is renamed or moved, and are readable when debugging.

  apos.schema.register now requires a fourth parentPath argument and throws if it is missing. If you have overridden a method that calls apos.schema.register you must pass it through; the error message includes guidance.

  The scopedArrayName and scopedObjectName properties are unchanged, keeping their existing form and continuing to honor the arrayName and objectName options, because they are stored in the database on every array item and object. No migration is required.

Fixes

• Fixed piecesFilters navigation (with static: true) reverting to the unfiltered index when logged in and an editor had clicked Edit at least once. It now recognizes filter path segments appended to the context doc's URL and preserves both the browser URL and the correctly filtered content on refresh.
• The performance of patches to deeply nested properties on the page has been optimized. As a result, each edit to a widget "in context" on the page does not require the same amount of time necessary to save the entire page via the page settings dialog. We consider this a bug fix rather than a feature because the issue was acute enough to prevent effective editing in some cases.
• The email schema field now validates and stores the laundered value, so surrounding whitespace is trimmed rather than causing a valid address to be rejected as invalid. Non-string input (for example a number sent through the REST API) is now coerced by the launder step instead of throwing an uncaught error. Thanks to spokodev for the fix.
• Fixed a 500 error when logging in on a session that had just been invalidated by a password change or by a disabled account. Such sessions are now regenerated rather than destroyed, so the request keeps a usable session and the invalidated one is removed from the store before the response is sent.
• Fixed incorrect sizing and spacing across the admin UI in webpack builds. A byte order mark preserved by PostCSS 8.5.24 invalidated the stylesheet rule setting box-sizing for .apos- elements. Sass is now compiled with charset: false in webpack builds, so the marker is never emitted. Vite builds were unaffected.
• Widget preview renderings are now properly debounced in cases where the server does not return the first preview before the timeout to generate a second preview arrives. Apostrophe will always wait for a previous render before attempting a new one based on the latest data available. This greatly mitigates the performance impact on the server if a widget is particularly slow and expensive to preview.

Security

• Completed the fix for server-side prototype pollution via dot-notation paths (CWE-1321, GHSA-vmg4-6gfg-83qx). apos.util.set() and apos.util.get() refused the __proto__, constructor and prototype segments, but followed every other property inherited from Object.prototype and Array.prototype. An authenticated editor could send a single PATCH REST API request with a body of { "toString.call": "x" } to reach the shared Object.prototype.toString function and shadow its call method, breaking every later Object.prototype.toString.call() in the process, including those inside the MongoDB driver: one request took the site down until it was restarted. Both methods now traverse own properties only, which confines a dot path to the request body and the document being patched. All users should update. Thanks to Fabian Bräunlein of Positive Security for reporting the vulnerability.

Free Modules

@apostrophecms/apostrophe-astro 1.15.0

This module integrates ApostropheCMS into your Astro application.

Adds

• AposTemplate.astro now forwards any additional props passed to it (beyond aposData) to the resolved page template component, matching the existing behavior of AposArea and AposWidget.

Fixes

• Fixed a bug where redirect responses proxied through aposProxy.js (e.g. OAuth login callbacks) lost every header except Location. This affected setups where Apostrophe is only reachable through the Astro proxy (e.g. a sidecar deployment), causing the session Set-Cookie header from an OAuth callback redirect to be silently dropped and the login to appear to fail.
• Included fix to aposResponse.js to remove entity headers describing the body when dropping the body (e.g. redirects) which may otherwise cause strict clients to hang waiting for bytes. Thanks to Erika for this fix.