Apostrophe 4.21.0: Effortless Image Uploads and Strategic Platform Enhancements

[BoDonkey]

Apostrophe 4.21.0: Effortless Image Uploads and Strategic Platform Enhancements

Hello Apostrophe Community!

Apostrophe 4.21.0 delivers immediate improvements to the content editing experience while laying important groundwork for next-generation features. This release centers on quick image uploads that eliminate friction for editors, plus platform enhancements that will enable exciting new capabilities in upcoming releases.

Important: Before updating, ensure your Node.js version is 20 or higher, as this release requires a supported version of Node.js.

pres-4.21.0.mov

Quick Image Upload: Smoothing the Content Creation Flow

Content editors can now upload images exactly the way they expect to—with zero extra steps. Our new quick image upload transforms what was previously a multistep media library workflow into an instant, intuitive experience.

Content managers can now:

• Drag images directly from their desktop onto any image widget
• Click to upload from the file picker without leaving your editing context
• See images automatically cropped and ready to use immediately
• Stay in the flow of content creation without context switching

This enhancement eliminates the cognitive overhead that comes with bouncing between the media library and content editing interfaces. For editorial teams working with image-heavy content—whether blog posts, product pages, or marketing materials—this translates to measurably faster content creation and a much more natural editing experience.

The implementation works seamlessly with all existing image widget functionality, including focal point adjustment and alternative text, ensuring that accessibility and design control remain intact while dramatically improving usability.

Foundation for Next-Generation Editing Features

While the quick image upload delivers immediate value, this release also includes strategic platform enhancements that will enable powerful new capabilities in upcoming versions. We've built new infrastructure for custom widget creation workflows and enhanced modal interactions to support features like reusable section templates and AI-powered layouts.

These behind-the-scenes improvements include new APIs for extending the "add widget" experience, transformer pipelines for processing content before insertion, and enhanced modal flexibility. While these changes immediately benefit developers building advanced editorial interfaces, the groundwork being laid will soon enable editors to work with pre-built layout templates, leverage AI for content suggestions, and access other productivity-enhancing tools.

The groundwork being laid here will soon enable editors to work with pre-built layout templates, leverage AI for content suggestions, and access other productivity-enhancing tools that build on these foundational improvements.

Relationship Field Refinements: Responsive to Community Feedback

Based on developer feedback, we've adjusted relationship field validation to be less restrictive in practice. The strict server-side enforcement introduced in 4.16.0 was causing unexpected errors when related content changed, so we've returned to a more practical approach that balances data integrity with real-world content management workflows.

Quality Improvements Across the Platform

This release includes several important fixes that improve the stability and usability of core features:

• API Rendering: The ?render-areas=1 API feature now correctly disregards areas in related documents, rather than failing the call
• Conditional Fields: Now work as expected in the Image Editor interface
• Widget Data Processing: Fixed an issue where widget data was being cloned before post-processing, which could cause data loss
• Relationship Updates: Improved live preview performance by only post-processing updated relationships

---

These improvements are ready for you to explore! Remember to update your Node.js version to 20 or higher before running npm update. Let us know what you think on our roadmap.

🚀 Happy coding!

Apostrophe 4.21.0

Adds

• Modules can now call apos.area.addCreateWidgetOperation to register a custom operation that invokes a modal and inserts the widget returned by that modal. These operations are offered as choices in all "add widget" menus, both regular and expanded.
• AposDocEditor now accepts a values prop, which can be used to pass an object of initial values for some or all fields. Use of this prop is optional. It is not supported when editing existing documents.
• apos.doc.edit now accepts an optional values object as the final parameter, containing initial values for some or all fields. This is supported only when editing existing documents.
• When specifying a modal name to be executed, developers may now register "transformers" to be invoked first, using pipe syntax. For example, the modal name aposSectionTemplateLibraryWidgetToDoc|AposDocEditor will invoke the transformer aposSectionTemplateLibraryWidgetToDoc with the original props, and pass the returned result to AposDocEditor. Note that transformers are awaited. Transformers are registered in frontend admin UI code by passing a name and a function to apos.ui.addTransformer.
• Adds quick image upload UI to @apostrophecms/image-widget.
• Makes autocropping work when uploading or selecting images from the new quick image upload UI.

Fixes

• The ?render-areas=1 API feature now correctly disregards areas in separate documents loaded via relationship fields. Formerly their presence resulted in an error, not a rendering.
• Make conditional fields work in Image Editor.
• Importing a custom icon from an npm module using a ~ path per the admin UI now works per the documentation, as long as the Vue component used for the icon is structured like those found in @apostrophecms/vue-material-design-icons.
• The button: true flag works again for piece module utility operations. Previously the button appeared but did not trigger the desired operation.
• Fix the fact that area options minSize and aspectRatio weren't passed to the image cropper when coming directly from the area and the widget controls (without passing through the widget editor).
• Fixes the widget data being cloned to be saved before the postprocess method being called, which leads to a loss of data in AposWidgetEditor (like the autocrop data).
• In editors like AposWidgetEditor relationships are now post processed after they are updated in AposInputRelationship only for the relationship that has been updated.
  It allows live preview to work well with it, it also avoids complexity and fixes updated data not being properly synced between the editor and the AposSchema.
• Deeply nested widgets can now be edited properly via the editor dialog box. This longstanding issue did not affect on-page editing.

Changes

• Rolled back a change in 4.16.0 that strictly enforced required and min for relationship fields. Because the related document can be archived or deleted at any time, it is misleading to offer such enforcement. Also, it greatly complicates adding these constraints to existing schemas, resulting in surprising and unwanted behaviors. Therefore it is better for these constraints to be soft constraints on the front end. max is still a hard constraint.
• The @apostrophecms/login/whoami route now accepts both POST (recommended) and GET requests. Previously, it only supported GET. This maintains backwards compatibility while aligning with the documentation’s recommendation to use POST.

Pro Modules

@apostrophecms-pro/advanced-permission 1.0.5

This module provides more granular control over content permission. It allows the creation of custom groups with proscribed abilities and the ability to assign users to as few or as many groups as desired. Users and groups can also be assigned per-document and per-locale permissions allowing for fine control of who can edit and publish any document. 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.

Changes

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

@apostrophecms-pro/automatic-translation 1.4.3

This bundle allows automatic translation of documents (pages and pieces) when localizing content. It comes with two translation providers: Google Cloud Translation and DeepL, but it is also possible to configure your own providers. 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.

Changes

• README improvement

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

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.

Adds

• Adds dragAndDropFile command.

@apostrophecms-pro/data-set 2.0.4

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. 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.

Changes

• README improvement

@apostrophecms-pro/import-export-translation 1.0.4

The purpose of this module is to create a specialized JSON file containing the text of the site, which can be downloaded and manually edited into a different language before being imported into a new locale. Upon import, pages from the default locale will be localized into the new locale substituting the translated text. 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.

Changes

• README improved

@apostrophecms-pro/seo-assistant 1.2.2

The SEO Assistant module generates SEO page metadata automatically through the use of AI. It comes configured for use with the OpenAI models. It is also possible to configure your own providers. This extension requires that the project also have the @apostrophecms-pro/automatic-translation and apostrophecms/seo extensions installed. 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.

Changes

• README improvement

Free modules

@apostrophecms/blog 1.0.6

This module bundle helps developers quickly add blog articles to Apostrophe websites. It provides the blog post piece type (@apostrophecms/blog) as well as a special page type (@apostrophecms/blog-page) for editors to create a blog.

Changes

• README improvements

@apostrophecms/import-export 3.3.1

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

Fixes

• CSV imports should not require a type column when importing pieces.
• Removed unused connect-multiparty middleware, eliminating superfluous warnings.

@apostrophecms/passport-bridge 1.5.2 (2025-08-27)

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.

Fixes

• Fixed regression introduced in 1.5.0-beta.1 that made it more difficult to see the logs regarding certain types of login failures and account creation issues. This issue was particularly likely to occur with strategies that do not supply req.
• Works correctly out of the box when only email is available in the profile, e.g. when the user's full name or username is not available, as can happen when an idP is configured to provide an absolute minimum of information.

@apostrophecms/redirect 1.4.3

Manages site redirects for Apostrophe.

Fixes

• Bug fix: UTF8 URLs now match properly. For instance, redirects containing Thai characters work as expected. Editors can paste them naturally (without hand-escaping them first) and the redirect module will correctly decode the URL received from Express before attempting to match it to a redirect.

@apostrophecms/seo 1.3.2

Add useful meta fields to all pages and pieces.

Changes

• README improved

Utilities

uploadfs 1.25.1 (2025-08-28)

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.

Changes

• Bump @google-cloud/storage to 7.x to address a deprecation warning.
• npx mocha test/gcs.js exits without hanging (there was no bug in the actual functionality, just the test).