Apostrophe 4.20.0: Enhanced Rich Text Experience and Infrastructure Updates

[BoDonkey]

Hello Apostrophe Community!

Apostrophe 4.20.0 delivers improvements to the content editing experience alongside important infrastructure updates that support better integration with external frontends and ensure long-term project compatibility.

Smoother Rich Text Editing

We've improved the rich text editing experience by making widget controls more context-aware. When editors click into text within a rich text widget, the widget controls are hidden to provide a cleaner editing experience. No more overlapping controls or difficult text selection—just focused, intuitive content creation.

Enhanced HTML Injection for External Frontends

This release introduces new prependNodes and appendNodes methods in core, providing a more robust way to inject HTML into pages. This enhancement was developed specifically to support better integration with external frontends like Astro, enabling developers of new extensions for ApostropheCMS to add custom HTML elements consistently across their applications.

Several popular extensions have been updated to take advantage of this new capability, making them easier to use with Astro and other external frontends:

• @apostrophecms/favicon
• @apostrophecms/open-graph
• @apostrophecms/seo
• @apostrophecms-pro/palette

Node.js Version Update Required

🚨 Breaking Change: Node.js 18 has reached end-of-life support. Since there is no upstream support for Node.js 18 itself and modules we depend on have begun to use newer features, starting with this release, Apostrophe 4.x requires Node.js 20 or later. Projects running on Node.js 18 or earlier will no longer be supported and may experience compatibility issues.

Please update your Node.js version before upgrading to ensure continued functionality, security updates, and optimal performance.

Backwards compatibility breaks due to Node.js 20 itself are not expected.

Update your modules together to avoid errors

⚠️ Important Compatibility Update: Several official extensions now depend on modules that use our new HTML injection method in preference to async Nunjucks components for “behind the scenes” features like SEO metadata. Always make sure you update all of your ApostropheCMS npm packages together with npm update. Also, make sure your package.json contains semantic versioning rules that allow updates to new patchlevels and minor releases via npm update, for instance:

"apostrophe": "^4.20.0"

Note the use of the ^ character, not ~ . This means “keep the same major version, but allow the minor and patchlevel versions to be updated.”

Additional Improvements

This release also includes several quality-of-life enhancements: improved alt text handling during rich text image imports, better page unparking capabilities, and resolved issues with relationship handling and rich text paragraph styling. We've also strengthened security by replacing connect-multiparty with the actively maintained multer library.

Community Contributions

We're grateful to acknowledge the contributions from our community members who help make Apostrophe better. Special thanks to Harsh Mehta for their work on document versioning improvements. While these specific changes weren't included in this release due to architectural considerations, community contributions like these drive important conversations about how we can enhance Apostrophe's capabilities.

We also thank Radhakrishnan Mohan for the security improvement that replaced connect-multiparty with multer.

---

These improvements are ready for you to explore! Again, make sure that you first update your Node.js version to 20 or higher. Then update your projects with npm update and let us know what you think on our roadmap.

🚀 Happy coding!

Apostrophe 4.20.0

Adds

• Adds any alt text found in an attribute to the media library attachment during import of rich text inline images by API
• Adds prependNodes and appendNodes methods to every module. These methods allow you to inject HTML to every page using a node declaration.

Changes

• Changes handling of order and groups in the admin-bar module to respect, rather that reverse, the order of items
• Interacting with the text inside a rich text widget will hide the widget controls to prevent awkward text selection.

Fixes

• Let the @apostrophecms/page:unpark task unpark all parked pages with the given slug, not just the first one.
• Exclude unknown page types from the page manager.
• Remove multiple calls to render-widget when switch to edit mode.
• Resolved an issue affecting withRelationships with two or more steps. This issue could cause a document to appear to be related to the same document more than once.
• You can now use checkboxes as filter inputType.
• Fixed a regression that prevented multiple variations of p with different classes from being recognized again when reopening the rich text editor, even if they are all on the style menu. This was caused by knock-on effects of upstream changes in tiptap and prosemirror and our previous efforts to mitigate these. Those upstream changes were correct, but they did have certain side effects in ApostropheCMS. By more fully specifying the desired behavior, we have now fully corrected the issue at the ApostropheCMS level.
• Correctly update alt attribute of images in rich text widgets.

Security

• Clear an npm audit warning by replacing connect-multiparty with multer. Thanks to Radhakrishnan Mohan for this contribution.
• To be clear, this was never an actual security vulnerability. The CVE in question is disputed, and for good reasons. However, since connect-multiparty is no longer maintained, it makes sense to move to multer.

Pro Modules

🎄 To gain access to our Pro modules today, feel free to [sign right up via our self-service portal.](https://app.apostrophecms.com/) You can also check out our [pricing page](https://apostrophecms.com/pricing). [Contact us](https://apostrophecms.com/contact-us) with any questions.

@apostrophecms-pro/data-set 2.0.3

This module provides an easy avenue for low-code data presentation. It creates a data-set piece for the import of comma-separated values (CSV) files. A separate widget allows for the dynamic selection of columns, and display of the data as an HTML table, or in other templates provided by the developer. Contact us or visit our pricing page to learn more.

Fixes

• Add validation for the modal UI, server validation data.

Changes

• Bumps eslint-config-apostrophe to 5, fixes errors, removes unused dependencies.

@apostrophecms-pro/doc-template-library 2.2.6

This module solves the "blank page problem" for developers and product managers, and makes it faster for editors to create content. doc-template-library allows for the configuration of default widgets and pre-populated content on piece or page templates, and to re-use existing layouts. Explore our documentation to discover how this extension can enhance your project. Then, effortlessly integrate it through our new Apostrophe Workspaces. For further details or inquiries, feel free to contact us or visit our pricing page.

Adds

• Adds perPage option to control the number of template listed when you create a new piece or page and in the template manager.

Fixes

• Fixes template list pagination

@apostrophecms-pro/document-versions 2.6.0

This module automatically creates versions for your published documents (pages and pieces) and allows manual restore to any previously saved document version. Explore our documentation to discover how this extension can enhance your project. Then, effortlessly integrate it through our new Apostrophe Workspaces. For further details or inquiries, feel free to contact us or visit our pricing page.

Adds

• Adds localeMapping options. This is a key: value pair used to map apos.i18n.locale with an Intl.Locale. For example, you can map the following { en: 'en-CA', fr: 'fr-CA' }. If empty, the apos.i18n.locale value will be used in place for DateTimeFormat locales.
• Adds dateTimeFormatOptions options. This is used to display the date time format in the version list modal (and few other places). Please refer to DateTimeFormat#options for more details.

Changes

• Removing versionDayjsTitleFormat translation key. You can use dateTimeFormatOptions instead.
• Removing dayjs. We now use Intl.DateTimeFormat.
• Removing cuid dependency. We now use @paralleldrive/cuid2.

@apostrophecms-pro/palette 4.8.1

An in-context interface for changing CSS. @apostrophecms-pro/palette is a module that provides an in-context interface for changing the values of developer-set CSS properties. The values are stored in an Apostrophe piece singleton (like @apostrophecms/global) and applied to the site whenever the stylesheet link is included in a template. Adjusting values via the palette interface renders changes to the site instantly. Explore our documentation to discover how this extension can enhance your project. Then, effortlessly integrate it through our new Apostrophe Workspaces. For further details or inquiries, feel free to contact us or visit our pricing page.

Changes

• Inject nodes instead of async Nunjucks component to support external frontends.

Apostrophe modules

@apostrophecms/anchors v1.0.2

This Anchors module adds a wrapping element with an anchor linking target around all widgets. Developers may customize or opt-out individual widget types.

Changes

• Updates README

@apostrophecms/favicon 1.1.3

This module allows users to edit the "favicon" (browser tab icon) of the site via the global settings of the site. As such, it pairs well with the Apostrophe palette and multisite modules.

Changes

• Inject nodes instead async Nunjucks component to support external frontends.

@apostrophecms/import-export 3.3.0

This module enables import and export of pages and pieces, with or without related documents such as files, images and other related types.

Adds

• Adds a checkbox to select and deselect all related document types in the export modal.

@apostrophecms/open-graph 1.2.3

Open Graph for ApostropheCMS.

Changes

• Bumps eslint-config-apostrophe to 5, fixes errors, removes unused dependencies.
• Removes circle ci, adds github actions.
• Inject nodes instead of async Nunjucks component to support external frontends.

@apostrophecms/passport-bridge 1.5.1

apostrophe-passport works together with passport-google-oauth20, passport-gitlab2 and similar passport strategy modules to let users log in to Apostrophe CMS sites via Google, Gitlab and other identity providers. This feature is often called federation or single sign-on.

Changes

• README update

@apostrophecms/seo 1.3.1

Add useful meta fields to all pages and pieces.

Changes

• Bumps eslint-config-apostrophe to 5, fixes errors, removes unused dependencies.
• Removes circle ci, adds github actions.
• Inject nodes instead of async Nunjucks component to support external frontends.

@apostrophecms/sitemap 1.2.0

The Apostrophe Sitemap module generates XML sitemaps for websites powered by ApostropheCMS. The sitemap includes all of the pages on your site that are visible to the public, including "piece" content, such as events and blog posts.

Adds

• Adds tests for the perLocale option

Changes

• Updates the README to include the perLocale option

Utilities

@apostrophecms/apostrophe-astro 1.5.0

This module integrates ApostropheCMS into your Astro application.

Adds

• Add support for prependHead, appendHead, prependBody, and appendBody in the aposData object, allowing for custom HTML to be injected into the <head> and <body> sections of the layout.

Fixes

• Handle deep schema validation errors when rendering widgets, so that a message is displayed in the widget preview instead of a crash.

postcss-viewport-to-container-toggle 2.0.1

A plugin for PostCSS that allows to toggle between viewport and container units based on the presence of a container data attribute.

Fixed

• Add :where() pseudo-class back to fix specificity issues.

uploadfs 1.25.0

uploadfs copies files to a web-accessible location and provides a consistent way to get the URLs that correspond to those files. uploadfs can also resize, crop and autorotate uploaded images. uploadfs includes S3-based, Azure-based, GCS-based and local filesystem-based backends and you may supply others.

Adds

• Adds SAS token support for the Azure storage backend.