apostrophe 4.20.0 → 4.21.1

package/CHANGELOG.md

@@ -1,5 +1,41 @@
 # Changelog
 
+## 4.21.1 (2025-09-26)
+
+### Adds
+
+* The `exit` option to the main `apostrophe()` function now supports the new string value `exit: 'throw'`. If this value is specified and the apostrophe startup procedure fails with an error, the actual error is re-thrown for the benefit of the caller.
+* For backwards compatibility, the existing `exit: false` option to the main `apostrophe()` function is still supported, but now logs the error that took place before returning `undefined` as before. This is more useful than the previous behavior, but `exit: 'throw'` is the more logical choice if you need to avoid a process exit.
+* The default behavior is still to log the error and exit the process, which isthe only sensible move in most single-site projects.
+
+## 4.21.0 (2025-09-03)
+
+### 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`.
+
 ## 4.20.0 (2025-08-06)
 
 ### Adds
@@ -9,8 +45,11 @@
 
 ### Changes
 
+* A `clone-widget.js` file has been factored out, providing a universal way to return a clone of an existing widget which is distinct from the original.
+* 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 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 awkawrd text selection.
+* Interacting with the text inside a rich text widget will hide the widget controls to prevent awkward text selection.
 
 ### Fixes
 

package/README.md

@@ -1,60 +1,142 @@
-![Unit Tests](https://github.com/apostrophecms/apostrophe/actions/workflows/main.yml/badge.svg)
-[![Chat on Discord](https://img.shields.io/discord/517772094482677790.svg)](https://chat.apostrophecms.org)
-
-<p align="center">
+<div align="center">
   <a href="https://github.com/apostrophecms/apostrophe">
     <img src="logo.svg" alt="ApostropheCMS logo" width="80" height="80">
   </a>
 
-  <h3 align="center">ApostropheCMS 3</h3>
+  <h1>ApostropheCMS</h1>
+
+  <p>
+    <a aria-label="Join the community on Discord" href="http://chat.apostrophecms.org">
+      <img alt="" src="https://img.shields.io/discord/517772094482677790?color=5865f2&label=Join%20the%20Discord&logo=discord&logoColor=fff&labelColor=000&style=for-the-badge&logoWidth=20" />
+    </a>
+    <a aria-label="License" href="https://github.com/apostrophecms/apostrophe/blob/main/LICENSE.md">
+      <img alt="" src="https://img.shields.io/static/v1?style=for-the-badge&labelColor=000000&label=License&message=MIT&color=3DA639" />
+    </a>
+  </p>
 
-  <p align="center">
-    ApostropheCMS is a full-featured, open source CMS built with Node.js that seeks to empower organizations by combining in-context editing and headless architecture in a full-stack JS environment.
+  <p>
+    <strong>Full-stack CMS for developers and content teams</strong><br />
+    Build websites with in-context editing and headless flexibility using Node.js and MongoDB.
     <br />
-    <a href="https://v3.docs.apostrophecms.org/"><strong>Documentation »</strong></a>
+    <a href="https://docs.apostrophecms.org/"><strong>Documentation »</strong></a>
     <br />
     <br />
     <a href="http://demo.apostrophecms.com">Demo</a>
     ·
-    <a href="https://portal.productboard.com/apostrophecms/1-product-roadmap/tabs/2-planned">Roadmap</a>
+    <a href="https://productlane.com/edit-roadmap">Roadmap</a>
     ·
     <a href="https://github.com/apostrophecms/apostrophe/issues/new?assignees=&labels=bug,3.0&template=bug_report.md&title=">Report Bug</a>
   </p>
-</p>
+</div>
+
+## About
+
+ApostropheCMS is a full-stack content management system built with Node.js and MongoDB. Content creators can edit directly on live pages without switching between admin interfaces, while developers can build with modern JavaScript or use it headlessly with any frontend framework.
+
+### Key Features
+
+- **🎯 In-Context Editing** - Content creators edit directly on the live page, seeing changes instantly
+- **⚡ Headless-Ready** - Use any frontend framework while keeping the powerful admin experience
+- **🛠️ Developer-First** - Built with Node.js and MongoDB for full-stack JavaScript development
+- **📈 Scales Beautifully** - From small sites to enterprise applications handling millions of pages
+- **🔐 Enterprise Features** - Advanced permissions, workflow management, automated translations, and more
+
+## System Requirements
+
+| Requirement | Version | Installation Notes |
+|-------------|---------|-------------------|
+| **Node.js** | 20.x+ | Use [NVM](https://github.com/nvm-sh/nvm) for version management |
+| **MongoDB** | 6.0+ | [MongoDB Atlas](https://www.mongodb.com/atlas) (cloud) or local install |
+| **npm** | 10.x+ | Included with Node.js |
+
+See our [setup guides](https://docs.apostrophecms.org/guide/development-setup.html) for installation instructions.
+
+## Quick Start
+
+Get ApostropheCMS running locally in minutes:
+
+```bash
+# Option 1: Install CLI globally (recommended for multiple projects)
+npm install -g @apostrophecms/cli
+apos create my-website
+cd my-website
+npm run dev
+
+# Option 2: Use npx for one-time project creation
+npx @apostrophecms/cli create my-website
+cd my-website
+npm run dev
+```
 
-## About ApostropheCMS
+Your new ApostropheCMS site will be available at `http://localhost:3000` with a powerful admin interface at `/login`.
 
-ApostropheCMS is content software for everyone in an organization. It helps teams of all sizes create dynamic digital experiences with elegance and efficiency by blending powerful features, developer happiness, and a low learning curve for content creators. Apostrophe has powered websites and web apps for organizations large and small for over a decade.
+### Prefer to Go Headless?
 
-#### Built With
+**Get started with Astro integration** - the easiest way to build headless sites while keeping visual editing:
 
-* [Node](https://nodejs.org/en/)
-* [MongoDB](https://www.mongodb.com/)
-* [Nunjucks](https://mozilla.github.io/nunjucks/)
+- **[Apollo Starter Kit (Astro)](https://apostrophecms.com/starter-kits/apollo-starter-kit-for-astro-cms)** - Production-ready foundation with beautiful design system and rich content features
+- **[Essentials Starter Kit (Astro)](git clone https://github.com/apostrophecms/starter-kit-astro-essentials)** - Minimal, clean foundation for building custom designs from scratch
 
-## Getting Started
+Both starter kits provide headless CMS power with in-context editing, letting content creators edit directly on the live site while you build with modern frontend tools. Our Astro integration handles all the content fetching automatically—no REST API calls to write.
 
-To get started with Apostrophe 3, follow these steps to set up a local development environment. For more detail, refer to the [A3 getting started guide](https://a3.docs.apostrophecms.org/guide/setting-up.html) in the documentation.
+**Desire a different frontend framework?** Use our REST APIs with React, Vue, Svelte, or any other framework:
 
-#### Prerequisites
+- **[REST API Documentation](https://docs.apostrophecms.org/reference/api/pieces.html)** - Complete API reference
+- **[Headless CMS Guide](https://docs.apostrophecms.org/guide/headless-cms.html)** - Integration walkthrough for any framework
 
-We recommend installing the following with [Homebrew](https://brew.sh/) on macOS. If you're on Linux, you should use your package manager (apt or yum). If you're on Windows, we recommend the Windows Subsystem for Linux.
+### Hosting & Deployment
 
-| Software | Minimum Version | Notes
-| ------------- | ------------- | -----
-| Node.js | 12.x | Or better
-| npm  | 6.x  | Or better
-| MongoDB  | 3.6  | Or better
-| Imagemagick  | Any | Faster image uploads, GIF support (optional)
+Choose [ApostropheCMS hosting](https://apostrophecms.com/hosting) for turnkey solutions with optimized performance and dedicated support, or deploy to [any platform where Node.js runs](https://docs.apostrophecms.org/guide/hosting.html).
 
-## Community
+## Built With Modern Tech
 
-[Discord](https://discord.com/invite/XkbRNq7) - [Twitter](https://twitter.com/apostrophecms) - [Discussions](https://github.com/apostrophecms/apostrophe/discussions)
+- **[Node.js](https://nodejs.org/)** - JavaScript runtime for server-side development
+- **[MongoDB](https://www.mongodb.com/)** - Flexible document database for content storage
+- **ESM Modules** - Native ES6 module support for modern JavaScript
+- **Vite** - Lightning-fast build tool and development server
+- **Modern JavaScript** - ES6+, async/await, and contemporary development patterns
+
+## Community & Support
+
+**Join other developers and content creators using ApostropheCMS:**
+
+- **[Discord](https://discord.com/invite/XkbRNq7)** - Get help, share projects, and connect with other users
+- **[GitHub Discussions](https://github.com/apostrophecms/apostrophe/discussions)** - Feature requests, technical discussions, and community support
+- **[Documentation](https://docs.apostrophecms.org/)** - Comprehensive guides, tutorials, and API references
 
 ## Contributing
 
-We eagerly welcome open source contributions. Before submitting a PR, please read through our [Contribution Guide](https://github.com/apostrophecms/apostrophe/blob/main/CONTRIBUTING.md)
+We welcome contributions from the community! Whether you're fixing bugs, adding features, or improving documentation, your help makes ApostropheCMS better for everyone.
+
+- **[Contribution Guide](https://github.com/apostrophecms/apostrophe/blob/main/CONTRIBUTING.md)** - How to contribute code, documentation, and feedback
+- **[Good First Issues](https://github.com/apostrophecms/apostrophe/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22)** - Perfect starting points for new contributors
+
+
+## Pro Features
+
+**For teams and organizations requiring additional features:**
+
+- **🔐 Advanced User Management** - Granular permissions, user groups, and access controls
+- **🌍 Automated Translation** - AI-powered translation with DeepL, Google Translate, and Azure
+- **📊 Analytics & SEO** - Built-in SEO optimization and content analytics
+- **⚡ Performance Optimization** - Advanced caching, CDN integration, and performance monitoring
+- **🏢 Multisite Management** - Manage multiple sites from a single dashboard with shared resources
+- **💼 Professional Support** - Dedicated support, training, and consultation services
+
+[Explore all the pro extensions](https://apostrophecms.com/extensions?autocomplete=&license=assembly&license=pro) and [sign up](https://app.apostrophecms.com/login) for a Pro license in our self-service Apostrophe Workspaces, or [contact us](https://apostrophecms.com/contact-us) to learn about licensing and support options.
 
 ## License
 
-ApostropheCMS is released under the [ MIT License](https://github.com/apostrophecms/apostrophe/blob/main/LICENSE.md).
+ApostropheCMS is open source software licensed under the [MIT License](https://github.com/apostrophecms/apostrophe/blob/main/LICENSE.md). This means you're free to use, modify, and distribute it for both personal and commercial projects.
+
+---
+
+<div align="center">
+  <p>
+    <strong>Ready to build something amazing?</strong><br>
+    <a href="https://docs.apostrophecms.org/">Get started with our documentation</a> or <a href="https://apostrophecms.com/contact-us">talk to our team</a>
+  </p>
+  <p>
+    <em>Built with ❤️ by the <a href="https://apostrophecms.com">ApostropheCMS team</a></em>
+  </p>
+</div>

package/index.js

@@ -350,7 +350,16 @@ async function apostrophe(options, telemetry, rootSpan) {
 
     return self;
   } catch (e) {
-    if (options.exit !== false) {
+    if (options.exit === false) {
+      console.error('apostrophe: error occurred during startup, continuing:');
+      console.error(e);
+      // returns undefined, for legacy reasons
+    } else if (options.exit === 'throw') {
+      // A more sensible approach for those who want to do something
+      // if initialization fails
+      throw e;
+    } else {
+      // Longstanding default behavior
       console.error(e);
       await self._exit(1, e);
     }

package/modules/@apostrophecms/admin-bar/ui/apos/components/TheAposAdminBarMenu.vue

@@ -72,6 +72,7 @@
           :is="item.options.component"
           v-if="item.options.component"
           :key="`${item.name}.component`"
+          :action="item.action"
         />
         <AposButton
           v-else

package/modules/@apostrophecms/area/index.js

@@ -88,6 +88,7 @@ module.exports = {
 
     self.enableBrowserData();
     self.addDeduplicateWidgetIdsMigration();
+    self.createWidgetOperations = [];
   },
   apiRoutes(self) {
     return {
@@ -382,8 +383,8 @@ module.exports = {
               return;
             }
             // We're only rendering areas on the document, not ancestor or
-            // child page documents.
-            const regex = /^_(ancestors|children)|\._(ancestors|children)/;
+            // child page or related documents.
+            const regex = /^_|\._/;
             if (dotPath.match(regex)) {
               return;
             }
@@ -786,7 +787,6 @@ module.exports = {
             manager.options.initialModal !== false;
           contextualWidgetDefaultData[name] = manager.options.defaultData || {};
         });
-
         return {
           components: {
             editor: 'AposAreaEditor',
@@ -799,7 +799,8 @@ module.exports = {
           widgetPreview,
           contextualWidgetDefaultData,
           widgetManagers,
-          action: self.action
+          action: self.action,
+          createWidgetOperations: self.createWidgetOperations
         };
       },
       async addDeduplicateWidgetIdsMigration() {
@@ -825,6 +826,9 @@ module.exports = {
             }
           });
         });
+      },
+      addCreateWidgetOperation(operation) {
+        self.createWidgetOperations.push(operation);
       }
     };
   },

package/modules/@apostrophecms/area/lib/custom-tags/area.js

@@ -69,7 +69,7 @@ module.exports = function(self) {
           items: []
         };
         doc[name] = area;
-        const docId = doc._docId || doc._id;
+        const docId = doc._docId || ((doc.metaType === 'doc') ? doc._id : null);
         if (docId) {
           let mainDoc = await self.apos.doc.db.findOne({ _id: docId });
           if (!mainDoc) {

package/modules/@apostrophecms/area/ui/apos/components/AposAreaContextualMenu.vue

@@ -72,7 +72,7 @@
                   <AposAreaMenuItem
                     :item="child"
                     :tabbable="itemIndex === active"
-                    @click="add(child)"
+                    @click="action(child)"
                     @up="switchItem(`child-${itemIndex}-${childIndex - 1}`, -1)"
                     @down="switchItem(`child-${itemIndex}-${childIndex + 1}`, 1)"
                   />
@@ -83,7 +83,7 @@
           <AposAreaMenuItem
             v-else
             :item="item"
-            @click="add(item)"
+            @click="action(item)"
             @up="switchItem(`item-${itemIndex - 1}`, -1)"
             @down="switchItem(`item-${itemIndex + 1}`, 1)"
           />
@@ -130,6 +130,10 @@ export default {
         return {};
       }
     },
+    fieldId: {
+      type: String,
+      required: true
+    },
     menuId: {
       type: String,
       default() {
@@ -196,8 +200,14 @@ export default {
         // If the menu is not open, we don't need to compute it right now
         return [];
       }
-      const clipboard = apos.area.widgetClipboard.get();
       const menu = [ ...this.contextMenuOptions.menu ];
+      for (const createWidgetOperation of this.moduleOptions.createWidgetOperations) {
+        menu.unshift({
+          type: 'operation',
+          ...createWidgetOperation
+        });
+      }
+      const clipboard = apos.area.widgetClipboard.get();
       if (clipboard) {
         const widget = clipboard;
         const matchingChoice = menu.find(option => option.name === widget.type);
@@ -226,7 +236,24 @@ export default {
     this.inContext = !apos.util.closest(this.$el, '[data-apos-schema-area]');
   },
   methods: {
-    async add(item) {
+    async action(item) {
+      if (item.type === 'operation') {
+        const props = {
+          ...item.props,
+          options: this.options,
+          fieldId: this.fieldId
+        };
+        this.$refs.contextMenu.hide();
+        const widget = await apos.modal.execute(item.modal, props);
+        if (widget) {
+          // Insert the widget at the appropriate insertion point, like we normally would
+          this.$emit('add', {
+            widget,
+            index: this.index
+          });
+        }
+        return;
+      }
       // Potential TODO: If we find ourselves manually flipping these bits in
       // other AposContextMenu overrides we should consider refactoring
       // contextmenus to be able to self close when any click takes place within

package/modules/@apostrophecms/area/ui/apos/components/AposAreaEditor.vue

@@ -32,6 +32,7 @@
           :empty="true"
           :index="0"
           :options="options"
+          :field-id="fieldId"
           :max-reached="maxReached"
           :disabled="field && field.readOnly"
           :widget-options="options.widgets"
@@ -80,9 +81,9 @@
 
 <script>
 import { createId } from '@paralleldrive/cuid2';
-import { klona } from 'klona';
 import AposThemeMixin from 'Modules/@apostrophecms/ui/mixins/AposThemeMixin';
 import newInstance from 'apostrophe/modules/@apostrophecms/schema/lib/newInstance.js';
+import cloneWidget from 'Modules/@apostrophecms/area/lib/clone-widget.js';
 
 export default {
   name: 'AposAreaEditor',
@@ -546,12 +547,7 @@ export default {
       }
     },
     clone(index) {
-      const widget = klona(this.next[index]);
-      delete widget._id;
-      this.regenerateIds(
-        apos.modules[apos.area.widgetManagers[widget.type]].schema,
-        widget
-      );
+      const widget = cloneWidget(this.next[index]);
       this.insert({
         widget,
         index: index + 1
@@ -572,30 +568,6 @@ export default {
         }
       }
     },
-    // Regenerate all array item, area, object and widget ids so they are considered
-    // new. Useful when copying a widget with nested content.
-    regenerateIds(schema, object) {
-      object._id = createId();
-      for (const field of schema) {
-        if (field.type === 'array') {
-          for (const item of (object[field.name] || [])) {
-            this.regenerateIds(field.schema, item);
-          }
-        } else if (field.type === 'object') {
-          this.regenerateIds(field.schema, object[field.name] || {});
-        } else if (field.type === 'area') {
-          if (object[field.name]) {
-            object[field.name]._id = createId();
-            for (const item of (object[field.name].items || [])) {
-              const schema = apos.modules[apos.area.widgetManagers[item.type]].schema;
-              this.regenerateIds(schema, item);
-            }
-          }
-        }
-        // We don't want to regenerate attachment ids. They correspond to
-        // actual files, and the reference count will update automatically
-      }
-    },
     async update(updated, { autosave = true, reverting = false } = {}) {
       if (!reverting) {
         updated.aposPlaceholder = false;
@@ -616,22 +588,30 @@ export default {
       });
       this.edited[updated._id] = true;
     },
-    // Add a widget into an area.
+    // Add a widget into an area. index is required, along
+    // with one and only one of name, widget or clipboard.
+    // If widget is passed it is inserted directly. If
+    // clipboard is passed it is cloned and inserted.
     async add({
       index,
       name,
+      widget,
       clipboard
     }) {
       if (clipboard) {
-        this.regenerateIds(
-          apos.modules[apos.area.widgetManagers[clipboard.type]].schema,
-          clipboard
-        );
+        clipboard = cloneWidget(clipboard);
         return this.insert({
           widget: clipboard,
           index
         });
-      } else if (this.widgetIsContextual(name)) {
+      }
+      if (widget) {
+        return this.insert({
+          widget,
+          index
+        });
+      }
+      if (this.widgetIsContextual(name)) {
         return this.insert({
           widget: {
             type: name,
@@ -640,35 +620,36 @@ export default {
           },
           index
         });
-      } else if (!this.widgetHasInitialModal(name)) {
-        const widget = this.newWidget(name);
+      }
+      if (!this.widgetHasInitialModal(name)) {
+        const newWidget = this.newWidget(name);
         return this.insert({
           widget: {
-            ...widget,
+            ...newWidget,
             aposPlaceholder: this.widgetHasPlaceholder(name)
           },
           index
         });
-      } else {
-        const componentName = this.widgetEditorComponent(name);
-        apos.area.activeEditor = this;
-        const preview = this.widgetPreview(name, index, true);
-        const widget = await apos.modal.execute(componentName, {
-          modelValue: null,
-          options: this.widgetOptionsByType(name),
-          type: name,
-          docId: this.docId,
-          areaFieldId: this.fieldId,
-          parentFollowingValues: this.followingValues,
-          preview
+      }
+
+      const componentName = this.widgetEditorComponent(name);
+      apos.area.activeEditor = this;
+      const preview = this.widgetPreview(name, index, true);
+      const newWidget = await apos.modal.execute(componentName, {
+        modelValue: null,
+        options: this.widgetOptionsByType(name),
+        type: name,
+        docId: this.docId,
+        areaFieldId: this.fieldId,
+        parentFollowingValues: this.followingValues,
+        preview
+      });
+      apos.area.activeEditor = null;
+      if (newWidget) {
+        return this.insert({
+          widget: newWidget,
+          index
         });
-        apos.area.activeEditor = null;
-        if (widget) {
-          return this.insert({
-            widget,
-            index
-          });
-        }
       }
     },
     widgetOptionsByType(name) {