Apostrophe 4.28.0: Static Builds for Astro, Pretty URLs for PDFs and Security Fixes

[BoDonkey]

Hello Apostrophe Community!

Apostrophe 4.28.0 brings a significant expansion to our Astro integration with support for static site builds, a cleaner URL experience for uploaded PDFs, and a round of stability improvements. This release also includes several community-contributed fixes.

Static Builds for Astro + ApostropheCMS Projects in Beta

Teams using Astro as their frontend can now take advantage of static site generation. This means you can now pre-render your Astro frontend and deploy it to any CDN or static host — no Node.js server required — reducing hosting costs and complexity while improving performance and security. The @apostrophecms/apostrophe-astro integration module has been updated to support static builds, and new features in our core @apostrophecms/url module handle URL generation for static contexts. When the relevant option is switched on, ApostropheCMS now generates URLs differently for filtering and pagination. For instance, to ensure they are static -friendly, URLs like /blog?page=2 now read like: /blog/page/2. The @apostrophecms/sitemap module has also been updated accordingly, so piece filter and pagination URLs are now included in generated sitemaps. The static build feature is currently in beta, and we encourage you to share your feedback.

To learn more, check out the new Static Builds with ApostropheCMS + Astro tutorial.

Pretty URLs for Uploaded Files

The file library now supports a prettyUrls: true option for @apostrophecms/file. When enabled, PDFs are served at readable, slug-based URLs rather than the internal attachment filename. You can customize the URL by editing the slug field directly in the file manager. There is a small performance trade-off to be aware of, which is noted in the option documentation. Note that pretty URLs for files are not yet compatible with static builds — this will be addressed in the next release.

Additional Improvements

This release includes several stability and UX fixes worth noting:

• Area widgets now render inside an inner wrapper that creates a separate z-index context, resolving conflicts between widget controls and the Apostrophe UI.
• A fix for rich text links where the "open in new tab" checkbox could not be unchecked.
• Relationship suggestion dropdowns now dismiss correctly when a choice is clicked, restoring behavior that had regressed in 4.27.1.

Community Contributions

We're grateful to community members who contributed fixes in this release cycle:

Eduardo Correal fixed a bug where the getOne API endpoint could not correctly retrieve documents that are not localized. Thanks, Eduardo!

Additionally, the sanitize-html dependency has been updated to resolve a security issue in the underlying htmlparser2 library, which previously failed to correctly detect javascript: URLs encoded with zero-padded numeric character references. This fix also resolves double-encoding of entities inside textarea and option elements. Thanks to alex-rantos for this contribution.

Important security updates

This release addresses two security vulnerabilities. Depending on your setup, one or both of these may warrant an urgent upgrade:

OxEr3n reported a vulnerability in the @apostrophecms/import-export module that could allow a user with permission to edit the global settings document to write files to the public/ folder or overwrite site code accessible to the server process (CVE-2026-32731). The vulnerability was not publicly disclosed prior to this fix. If you are using the import-export module, upgrading promptly is required. Thanks to OxEr3n for responsible disclosure and for providing test cases.

0xkakashi reported a previously undisclosed vulnerability that allowed a compromised password to be used to perform CMS actions without 2FA (CVE-2026-32730). The vulnerability was not publicly disclosed prior to this fix. Sites not using two-factor authentication are unaffected, but if you are using @apostrophecms/login-totp or a similar module, upgrading immediately is strongly recommended. Thanks to 0xkakashi for reporting the issue and recommending a fix.

---

This release contains important security fixes — we encourage all users to upgrade promptly with npm update, and particularly urge those using the @apostrophecms/import-export or @apostrophecms/login-totp modules to treat this as an urgent update. Let us know what you think on our roadmap.

🚀 Happy coding!

Apostrophe 4.28.0

4.28.0

Adds

• Adds support for static URLs and static external frontend builds.
• Adds widget graph store, accessible in the admin UI.
• Support for the new prettyUrls: true option for @apostrophecms/file, which enables "pretty URLs" for PDFs and other items in the file library, in exchange for a small performance impact. Edit the slug field to adjust the pretty URL
• Adds inner wrapper to area widget that creates a separate z-index context for the user, fixing widget/apostrophe UI conflicts

Fixes

• Fix a bug related to links in rich text in which the "open in new tab" checkbox can't be cleared once selected and saved.
• Ensures the getOne API can correctly retrieve documents that are not localized. Thanks to Eduardo Correal.
• Clicking a choice should dismiss the relationship suggestions dropdown. This regression was caused by part of the patch in release 4.27.1.
• Fixes a bug in which the Layout Widget's mode erroneously switches states.
• Fixes a bug in which the Layout Widget's synthetic column styles were not reaching their children
• Fixes styles being sanitized as HTML (breaks quotes) and resolves duplicate styles on the page.
• Fix subtle bug in AposPermissionGrid that causes unrelated clicks to be "swallowed" due to a race condition at low network speeds.
• Fixes two conditions where slow internet speed could cause input to lose focus before a selection can be registered.
• Raise the user's widget z-index context only when focused
• Clicking a choice should dismiss the relationship suggestions dropdown. This regression was caused by part of the patch in release 4.27.1.

Changes

• Improve re-rendering UX while keeping the performance optimization
• Refine in-context focus states for calmer UX
• Simplifies some in-context UI rendering checks
• Hide add content buttons on rich text editing, like widget controls

Security

• This previously undisclosed security vulnerability allowed users who had compromised a password to perform actions in the CMS without 2FA. For sites not using 2FA (e.g. our @apostrophecms/login-totp module), this changes nothing. But for those using our TOTP module or similar, upgrading to this release is urgent. Thanks to 0xkakashi for reporting the issue and recommending a fix.
• Fixed vulnerability that allowed any user with permission to edit the global settings document, e.g. headers, footers, etc., to potentially deface the site by writing files to the public/ folder or overwrite site code accessible to the same Linux account that runs the server process. This vulnerability was not publicly disclosed prior to the release of this fix. Upgrading immediately is strongly recommended for those using the import-export module. Thanks to 0xEr3n for reporting the vulnerability and providing test cases.

Pro modules

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

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

• Add additional clicks to focus layout widgets properly

Fixes

• Adjust click target of useWidgetFocus to avoid inner widget UI

Free modules

@apostrophecms/apostrophe-astro 1.10.0

This module integrates ApostropheCMS into your Astro application.

Adds

• Adds support for static builds. Introduces relevant helpers.

@apostrophecms/seo 1.4.0

Comprehensive SEO module providing meta field management and Schema.org structured data generation (JSON-LD) for all pages and pieces.

Adds

• Adds support for static URLs and static build. Refactoring performed to use core internal URL enumeration. Piece filters and pagination URLs will be included in sitemap now.

Fixes

• Fixes README error in fieldMappings option

@apostrophecms/sitemap 1.3.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 support for static URLs and static build. Refactoring performed to use core internal URL enumeration. Piece filters and pagination URLs will be included in sitemap now.

Utilities

@apostrophecms/code-upgrader 1.1.0 (2026-03-02)

The Code Upgrader handles a portion of the required modifications for an Apostrophe 2 (A2) codebase to run Apostrophe 3 (A3). It will also identify many specific lines and sections of code that a developer will need to convert manually.

Changes

• Includes Agent Skill (aka Claude Skill). The Agent Skill is now the strongly recommended method of code migration.

@apostrophecms/content-upgrader 1.1.0 (2026-03-02)

A tool to migrate your content from Apostrophe 2.x to Apostrophe 3.x. That is, it creates a new database in the A3 format, and copies over the uploaded media. This tool does not upgrade your source code.

Changes

• Updated misleading references to alpha status in README.
• Updated legacy references to A3. You should migrate directly to A4.
• Provided code migration AI agent skill. The @apostrophecms/code-upgrader module is no longer recommended.

1.0.0 (2023-03-16)

Changes

• Declared stable. No code changes.
• Decision made to start official releases with 1.0.0 for consistency.

postcss-viewport-to-container-toggle 2.3.0

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

Adds

• Adds support for media queries that change :root variable values

sanitize-html 2.17.2

This module provides a simple HTML sanitizer with a clear API.

Fixes

• Upgrade htmlparser2 from 8.x to 10.1.0. This improves security by correctly decoding zero-padded numeric character references (e.g., &#0000001) that previously bypassed javascript: URL detection. Also fixes double-encoding of entities inside raw text elements like textarea and option. Thanks to [Alexandros Rantos] (https://github.com/alex-rantos) for this update.

uploadfs 1.26.1

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

• Fixes azure copyIn to correctly recognize file extensions for blacklisting