Apostrophe 4.22.0: Astro improvements & quality of life updates

[boutell]

Hello Apostrophe Community!

Apostrophe 4.22.0 introduces major improvements for developers using external frontends like Astro, including a new template injection system and expanded widget options that bring headless workflows closer to feature parity with traditional rendering. Alongside these enhancements, a series of quality-of-life fixes improve security, content filtering, international URL handling, and CSS performance.

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

Enhanced Astro Integration and Template Injection

This release significantly improves support for external frontends, particularly Astro, with new infrastructure that enables better headless CMS workflows.

New Template Injection System: The new prependNodes and appendNodes methods replace the previous template injection approach, providing a cleaner way for modules to add HTML elements to pages. This enhancement enables modules like SEO and Palette to inject content consistently across both traditional and headless implementations.

Astro Widget Options: Developers can now pass both per-area and global widget options from the backend to Astro components using the new annotateWidgetForExternalFront() method. This brings Astro widget implementations closer to parity with traditional server-rendered widgets, including support for the @apostrophecms/anchors module.

Quality of Life Improvements Throughout

Beyond the major new features, this release includes refinements that improve daily editorial work:

Improved URL Handling: Redirects to URLs with accent marks and non-ASCII characters now work correctly with Astro and other external frontends, preventing redirect errors for international content.

Enhanced Piece Filtering: Fixed issues with filters when values from optional fields are falsy, ensuring reliable content discovery in large collections.

Better Login Security: Resolved an issue where customized login validation rules defined to run after form submission but before username/email and password checks were not being enforced.

• This only applied to projects where developers explicitly added such rules using the uponSubmit filter, which was documented but has never used in our own modules so far.
• Standard authentication methods (username/email + password) and all official ApostropheCMS modules such as CAPTCHA, hCAPTCHA and TOTP were never vulnerable.
• The fix ensures that all login validation rules, regardless of when they are triggered, are now properly enforced in addition to standard password validation.

Smarter CSS Generation: The Palette Pro extension now merges rules using the same selector, significantly reducing the size of generated CSS files and improving page load performance.

---

These improvements are ready for you to explore! Update your projects with npm update and let us know what you think on our roadmap.

🚀 Happy coding!

Apostrophe 4.22.0

Adds

• Custom operations registered with addCreateWidgetOperation can now specify an ifTypesIntersect property containing an array of widget type names. If the area in question allows at least one, the operation is offered.
• The login-requirements tests were updated to include tests for the uponSubmit filter.
• Add prependNodes and appendNodes calls for main.
• Add options for pieces to change the title, message and icon of the empty state block.

Fixes

• Fixes a bug in the login uponSubmit filter where a user could login without meeting the requirement. Again, we need to explicitly describe anywhere we actually used this in any of our own modules, if at all, and if not, state there is no vulnerability in our modules and existing sites using them have secure login.
• Fixes pieces filters when values from optional fields are falsy.
• Resolve inline image URLs correctly when in edit mode and not in the default locale.

Changes

• Redirects to URLs containing accent marks and other non-ASCII characters now behave as expected with Astro. Pre-encoding the URLs exactly the way res.redirect would before passing them to Astro prevents an error in Astro and allows the redirect to succeed.
• Removes the non-functional and unused uniqueUsername route from the user module (unique usernames are enforced elsewhere)
• Modifies the annotateAreaForExternalFront() method of the @apostrophecms/template module to accept a per-module annotateWidgetForExternalFront() method. This allows widgets to send project-level options alongside the per-area options to external frontends.
• Updated dependencies to address deprecation warnings.

Pro Modules

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

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.

Changes

• useAreaAdd gets menu items even if not visible, and will scroll to the selected one before to click on it.
• Change selector for pieceFilterGroup to support custom piece filters.

@apostrophecms-pro/multisite-dashboard 1.5.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.

Changes

• Inject "apos-multisite-dashboard" div using prependNodes instead of a template.

@apostrophecms-pro/palette 4.10.0

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

• Rules using the same selector are now merged. This helps reduce the size of the generated CSS file.
• Pre-renders the style when using serverRendered: true. This helps reduce visual "jump" during initial page display.

Adds

• Add missing Content-Type header to POST render request.
  {# TODO Correct links! #}

Adds

• Initial release

Open source modules

@apostrophecms/anchors v1.1.0

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

Adds

• Adds new annotateWidgetForExternalFront() method to both modules. This allows for options to be passed through to external frontends like Astro.

Fixes

• Fixes the anchorId field of the anchors-widget-type module so that it follows the field passed in the anchorDefault option.

Utilities

`@apostrophecms/apostrophe-astro 1.6.0

This module integrates ApostropheCMS into your Astro application.

Adds

• Adds additional handling for the @apostrophecms/anchors module to the AposWidget.astro component
• Adds handling for project-level widget options, as well as actually passing per-area options to widgets. Can be accessed through the options prop in the widget components.
• Add support for prependMain and appendMain in the aposData object, allowing for custom HTML to be injected into the <main> sections of the layout.

Fixes

• Verify that the Host header is correctly formatted and reject the request if it is not.

eslint-config-apostrophe 6.0.2 (2025-09-16)

An ESLint configuration for ApostropheCMS core and officials modules.

Fixes

• Ignore apos-build, data and public directories recursively.

6.0.1 (2025-09-09)

Fixes

• Apply vue/max-len rule to vue files only.

6.0.0 (2025-09-09)

Breaking changes

• Migration to eslint@9 and neostandard.

@apostrophecms/stylelint-no-mixed-decls 1.2.0 (2025-17-09)

A Stylelint plugin that enforces Sass's mixed-decls rule — requiring declarations and nested rules to be ordered according to Sass's updated behavior.

Adds

• New contain-nested array option to list mixins that are known to contain nested rules.

stylelint-config-apostrophe 4.4.0

A stylelint configuration for ApostropheCMS modules and projects.

Changes

• Add global mixins to the @apostrophecms/stylelint-no-mixed-decls plugin configuration.

uploadfs 1.25.2

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.

Fixes

• Fix typo in documentation (disableFileKey > disabledFileKey).