Apostrophe 4.31.0: Developer Activation

[BoDonkey]

Hello Apostrophe Community!

Apostrophe 4.31.0 is our first quarterly feature release, and its theme is Developer Activation — a focused set of changes that make ApostropheCMS meaningfully easier to adopt, extend, and deploy. This release introduces JSX as a server-side templating option, a redesigned CLI installer, support for PostgreSQL and SQLite databases, and several security patches that warrant prompt attention from all users.

New.interactive.CLI.mp4

JSX Templates

Apostrophe page, widget, and component templates can now be written in JSX as an alternative to Nunjucks. For developers already comfortable with React or another JSX-aware framework, this means real JavaScript control flow, modern editor support, and accurate error reporting with source maps — without standing up a separate front-end project.

JSX templates are a server-side templating feature, not a React runtime. There is no virtual DOM, no client runtime, and no framework requirement. JSX and Nunjucks coexist freely in the same project and can be migrated incrementally, allowing teams to convert individual templates over time while keeping existing layouts in place. Nunjucks remains a fully supported, first-class option. And Astro continues to be a great option for those who need dynamic islands, support for multiple frontend frameworks on the back end, or static build support.

We're releasing JSX now to gather community feedback, and will be updating our documentation over time to show it as the preferred authoring path for new projects. See the JSX templates guide to get started.

A New Interactive CLI Installer

apos create now delegates to the new create-apostrophe package, delivering a guided interactive installer that walks developers through project name, starter kit selection, and database configuration via prompts. This was a heavily requested improvement on our roadmap, and substantially lowers the barrier to getting a new Apostrophe project running from scratch.

Under the hood, create-apostrophe is a standalone installer that can also be invoked directly via npm create apostrophe@latest. It supports SQLite, MongoDB, and PostgreSQL out of the box, handles sample data for demo kits, and creates an admin user — all in a single flow.

PostgreSQL, SQLite, and Multi-Postgres Database Support

ApostropheCMS now supports PostgreSQL and SQLite databases, in addition to MongoDB. Connection is via standard URI: postgres://, sqlite:// and, for multisite projects, multipostgres:// URIs are all recognized by the new db-connect API, which covers all database operations used in our own core, Pro and Assembly modules.

This opens the door for teams with existing PostgreSQL investments, and gives developers a lightweight SQLite option for local development.

Command-line utilities are also provided to dump and restore databases in a universal way, across all three databases.

See the database configuration documentation for details.

Security Updates

This release includes several proactively identified and responsibly disclosed security fixes across core, @apostrophecms/seo, and sanitize-html. We recommend all users upgrade promptly with npm update.

Full details are available in the changelog below and in the published GitHub security advisories.

Additional Improvements

Beyond the headline features, this release focuses on editing stability and deployment ergonomics.

Resilient schemas: Adding or removing area fields from a schema no longer breaks existing documents on external front ends like Astro. Missing or orphaned areas now fail gracefully, and newly added fields are materialized as empty objects, so editors can work with them immediately in context.

Streamlined configuration: Session secrets and uploadfs keys can now be set via environment variables, bringing them in line with the rest of Apostrophe's environment-based configuration and modern CI/CD practices.

Community Contributions

Thanks to tonghuaroot, H3xV0rT3x, 5h1kh4r, EchoSkorJjj, hibrian827, and Dipanshu singh for their security reports and contributions in this release.

Node 20: End of Support

Node 20 has officially passed its end of life date upstream, and is not supported by Apostrophe 4.31.0. Those who are still using Node 20 should upgrade locally to Node 22 or 24, test their code, and deploy to Node 22 or 24.

Node 26: Start of Support

Node 26 is not yet an official long-term-support release upstream, so most users should continue to use Node 22 or 24 in production for now. However, we have introduced Node 26 support in this release of Apostrophe.

---

How to Update

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

🚀 Happy coding!

The “stable” option

Everything above reflects our standard, “latest” module releases. 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.

---

Apostrophe 4.31.0

Adds

• Added support for draggable: false on non-inline array schema fields. Previously this option was only respected when inline: true. When set on a standard (modal-based) array field, drag-and-drop reordering and keyboard reordering are now disabled in the array editor's slat list.
• Introduced support for postgres://, sqlite://, and multipostgres:// database URIs in addition to mongodb://. The new db-connect API supports all of the database operations currently used in our own core, pro and multisite modules. For more information see the documentation.
• JSX support for templates within ApostropheCMS. JSX is now co-equal with Nunjucks, with a gradual migration strategy. Anyone who is familiar with React will be very comfortable writing JSX templates, which also offer a superior debugging experience, and templates can be migrated gradually. JSX is a great option for those who don't wish to create parallel Astro and ApostropheCMS projects, but still prefer a modern syntax. For more information, see the new JSX templates guide.
• The session secret and the uploadfs disabledFileKey can now be supplied via the APOS_SESSION_SECRET and APOS_UPLOADFS_DISABLED_FILE_KEY environment variables. As with other Apostrophe environment variables, these take precedence over the corresponding app.js configuration.

Fixes

• Fixed an issue where using the Tab key to navigate within modals could incorrectly jump focus to a wrong element instead of the next input field.
  Fixed Tab navigation escaping out of modals when the form contained hidden sections or elements that became disabled after editing.
• Fixed adding or removing an area field from a schema breaking existing documents on an external front such as Astro.
• For Astro: AposArea now renders only schema-backed areas. A missing area no longer throws, and an area orphaned by removing its field from the schema (while its content remains in the document) renders nothing instead of breaking sibling areas in edit mode. Logged-in editors get a diagnostic message in place of an orphaned area; anonymous visitors see nothing.
• Editable documents sent to an external front (Asgtro) now materialize empty area objects for schema area fields added after the document was created, so they can be edited in context.
• apos.util.getManagerOf accepts a { log } option to suppress its error log when probing objects that may not have a manager.
• Fix more admin UI a11y issues.
• Selecting an item in a relationship "browse" dialog no longer scrolls the title and Cancel/Select buttons out of view when the item is far down the list.
• Sites with a custom filterByIndexPage method no longer experience failures in the sitemap module and potential creeping CPU performance penalties. A regression introduced with our static site support, but not specific to static sites.

Security

• Server-side prototype pollution (CWE-1321) via dot-notation paths. apos.util.set() and apos.util.get() now refuse to traverse __proto__, constructor and prototype path segments. Previously an authenticated editor could send a PATCH REST API request whose patch operators (for example $pullAll with a key of __proto__.publicApiProjection) wrote to Object.prototype. A polluted publicApiProjection defeated the publicApiCheck() authorization gate on piece-type REST endpoints for subsequent unauthenticated requests, for the lifetime of the Node.js process. All users should update. Thanks to tonghuaroot, H3xV0rT3x, and 5h1kh4r for reporting the vulnerability.
• When @apostrophecms/file pretty URLs are enabled (prettyUrls: true), the upstream request used to serve the file is no longer built from the incoming Host header. The self-request is now resolved against the site's configured baseUrl (via req.baseUrl), falling back to the request host only when no baseUrl is configured. This closes a server-side request forgery (SSRF) vector in which the Host header could steer the proxied fetch at another host. The real-world risk was low: the path is constrained to an existing attachment's /uploads/attachments/<cuid>-<slug>.<ext>, and cuids are unique and immutable, so any reachable content was already public via the front door. Thanks to EchoSkorJjj for reporting the issue.

Pro Modules

@apostrophecms-pro/cypress-tools 1.0.0-beta.29

Automated functional browser tests are an important part of quality assurance for enterprise websites and web applications. Cypress is an industry-standard, open-source library for carrying out automated functional browser tests. This module provides a collection of conveniences for testing the ApostropheCMS admin UI within Cypress. Explore our documentation to learn how this extension can enhance your project. Once you're ready, obtain a license and install it through Apostrophe Workspaces. For further details or inquiries, feel free to contact us or visit our pricing page.

Fixes

• Bump db-connect dependency to the official one.

@apostrophecms-pro/document-versions 2.7.1

This module automatically creates versions of your published documents and allows manual restore to any previously saved version. Explore our documentation to discover how this extension can enhance your project. Integrate it through Apostrophe Workspaces. For further details or inquiries, feel free to contact us or visit our pricing page.

Fixes

• Fix accessibility trigger issue.

@apostrophecms-pro/multisite 4.5.0

This module lets you have many ApostropheCMS websites running on a single codebase in a single Node.js process. Each has its own database, users, media uploads, etc. Sites can be created and managed via a dashboard site. Explore our documentation to discover how this extension can enhance your project. For further details or inquiries, feel free to contact us or visit our pricing page.

Adds

• Postgres and SQLite support

@apostrophecms-pro/multisite-dashboard 1.7.0

This extension creates the new default multisite dashboard with infinite scroll, search functionality, and the ability to save templates. This extension requires that the project also have the @apostrophecms-pro/multisite extension installed and configured. Explore our documentation to discover how this extension can enhance your project. For further details or inquiries, feel free to contact us or visit our pricing page.

Adds

• Support for Postgres and SQLite.

Free Modules

@apostrophecms/apostrophe-astro 1.13.0

This module integrates ApostropheCMS into your Astro application.

Fixes

• Adding or removing an area field from a schema no longer breaks documents on an external front such as Astro.
• AposArea now renders only schema-backed areas. A missing area no longer throws, and an area orphaned by removing its field from the schema (while its content remains in the document) renders nothing instead of breaking sibling areas in edit mode. Logged-in editors get a diagnostic message in place of an orphaned area; anonymous visitors see nothing.
• Editable documents sent to an external front now materialize empty area objects for schema area fields added after the document was created, so they can be edited in context.
• apos.util.getManagerOf accepts a { log } option to suppress its error log when probing objects that may not have a manager.

@apostrophecms/import-export 3.6.1

Changes

• 04d3053: Debug logging is now disabled by default and can be enabled by setting the debug: true option on the @apostrophecms/import-export module, or by setting the APOS_DEBUG_IMPORT_EXPORT=1 environment variable.

@apostrophecms/redirect 1.6.0

Fixes

• Prevent infinite redirects to external URLs

@apostrophecms/seo 1.5.0

Adds

• Removes unimplemented hreflang output; use @apostrophecms/sitemap for hreflang support

Changes

• Removes the seoSiteCanonicalUrl field from global settings. The base URL is now derived automatically from APOS_BASE_URL or the baseUrl option. The value remains available at req.data.global.seoSiteCanonicalUrl for backwards compatibility.

Security

• The Google Analytics tracking ID (seoGoogleTrackingId) and Google Tag Manager ID (seoGoogleTagManager) global SEO fields were interpolated directly into the bodies of inline <script> tags without escaping. Any user permitted to edit the global document, including editors and contributors (if their submission were approved), could set these fields to a value that broke out of the surrounding script and executed arbitrary JavaScript for every visitor on every page (stored XSS). These values are now emitted as escaped json nodes, matching the JSON-LD handling, so they can no longer terminate the <script> element or escape the string literal they sit in. All projects using @apostrophecms/seo with untrusted editors should upgrade promptly to close this vulnerability. Thanks to H3xV0rT3x and hibrian827 for reporting the issue.

Utilities

@apostrophecms/cli 3.7.0

The Apostrophe CLI is a cross-platform starting point for creating and configuring ApostropheCMS projects, providing a simple boilerplate generator and wrapping other useful functions into an easy to use command line tool.

Adds

• apos create is now an interactive guided installer (it delegates to create-apostrophe). The <shortname> positional argument and the --starter and --mongodb-uri options have been removed - project name, starter kit, and database are now chosen through prompts. For scripted installs, use npm create apostrophe@latest -- --unattended instead.

create-apostrophe 1.0.1

create-apostrophe is the guided installer behind npm create apostrophe. It clones a starter kit, wires up your database, installs dependencies, and creates an admin user — so a fresh Apostrophe project is running in minutes. It can be used standalone via npm create apostrophe@latest or through the Apostrophe CLI's apos create command.

Adds

• Initial creation.

Fixes

-Fix CLI link

sanitize-html 2.17.5

Security

• Added a number of new attributes to be protected against unsafe URLs, e.g. javascript: and similar. None of these are used in the default configuration of sanitize-html or apostrophe or likely to be used there, and some attributes, like an action for a form, are inherently unsafe to allow if XSS protection is your goal. Nevertheless it makes sense to block certain URL types where they are not appropriate. Some attributes are not supported at all by modern browsers but are included for completeness. Thanks to crattack for reporting the vulnerability.
• Address a potential vulnerability when nonTextTags is configured in a nonstandard way. While it is never a good idea to remove known non-text tags from the standard list e.g. script, styles, etc., this change ensures that doing so does not result in nested tags being passed through without sanitization when they are not expressly allowed. (ApostropheCMS would never trigger this situation.) Thanks to Dipanshu singh for pointing out the issue and contributing the fix.

launder 1.7.1

Security

• launder now uses and exports the best available naughtyHref function for detecting malicious URLs. sanitize-html now depends on it, and apostrophe now uses type: 'url' for the link URL field of image widgets, which leverages it. Prior to this fix, it was possible for any user with editing privileges, including a contributor, to trigger arbitrary JavaScript via a javascript: URL in the link URL field of an image widget. A migration has been included to strip any such malicious URLs already present in the database. All users of apostrophe are encouraged to upgrade to get this security fix. Thanks to Muhammad Uwais for reporting the issue.