apostrophe 3.5.0 → 3.8.1

package/.eslintrc

@@ -10,6 +10,10 @@
     "no-var": "error",
     "no-console": 0,
     "multiline-ternary": "off",
+    "no-unused-vars": [
+      "error",
+      { "varsIgnorePattern": "^_.", "args": "none" }
+    ],
     "vue/no-deprecated-destroyed-lifecycle": 0,
     "vue/v-on-event-hyphenation": 1,
     "vue/custom-event-name-casing": ["warn", "kebab-case"],

package/.scratch.md

@@ -0,0 +1,2 @@
+- `/deep/ .apos-button` to `:deep(.apos-button)`
+- Remove v-popover, v-tooltip, VueClickOutsideElement

package/CHANGELOG.md

@@ -1,9 +1,102 @@
 # Changelog
 
-## 3.5.0 - 2021-09-23
+## 3.8.1 - 2021-11-23
+
+### Fixes
+
+* The search field of the pieces manager modal works properly. Thanks to [Miro Yovchev](https://github.com/myovchev) for pointing out the issue and providing a solution.
+* Fixes a bug in `AposRichTextWidgetEditor.vue` when a rich text widget was specifically configured with an empty array as the `styles` option. In that case a new empty rich text widget will initiate with an empty paragraph tag.
+* The`fieldsPresent` method that is used with the `presentFieldsOnly` option in doc-type was broken, looking for properties in strings and wasn't returning anything.
+
+## 3.8.0 - 2021-11-15
+
+### Adds
+
+* Checkboxes for pieces are back, a main checkbox allows to select all page items. When all pieces on a page are checked, a banner where the user can select all pieces appears. A launder for mongo projections has been added.
+* Registered `batchOperations` on a piece-type will now become buttons in the manager batch operations "more menu" (styled as a kebab icon). Batch operations should include a label, `messages` object, and `modalOptions` for the confirmation modal.
+* `batchOperations` can be grouped into a single button with a menu using the `group` cascade subproperty.
+* `batchOperations` can be conditional with an `if` conditional object. This allows developers to pass a single value or an array of values.
+* Piece types can have `utilityOperations` configured as a top-level cascade property. These operations are made available in the piece manager as new buttons.
+* Notifications may now include an `event` property, which the AposNotification component will emit on mount. The `event` property should be set to an object with `name` (the event name) and optionally `data` (data included with the event emission).
+* Adds support for using the attachments query builder in REST API calls via the query string.
+* Adds contextual menu for pieces, any module extending the piece-type one can add actions in this contextual menu.
+* When clicking on a batch operation, it opens a confirmation modal using modal options from the batch operation, it also works for operations in grouped ones. operations name property has been renamed in action to work with AposContextMenu component.
+* Beginning with this release, a module-specific static asset in your project such as `modules/mymodulename/public/images/bg.png` can always be referenced in your `.scss` and `.css` files as `/modules/mymodulename/images/bg.png`, even if assets are actually being deployed to S3, CDNs, etc. Note that `public` and `ui/public` module subdirectories have separate functions. See the documentation for more information.
+* Adds AposFile.vue component to abstract file dropzone UI, uses it in AposInputAttachment, and uses it in the confirmation modal for pieces import.
+* Optionally add `dimensionAttrs` option to image widget, which sets width & height attributes to optimize for Cumulative Layout Shift. Thank you to [Qiao Lin](https://github.com/qclin) for the contribution.
+
+### Fixes
+
+* The `apos.util.attachmentUrl` method now works correctly. To facilitate that, `apos.uploadsUrl` is now populated browser-side at all times as the frontend logic originally expected. For backwards compatibility `apos.attachment.uploadsUrl` is still populated when logged in.
+* Widget players are now prevented from being played twice by the implementing vue component.
+
+### Changes
+* Removes Apostrophe 2 documentation and UI configuration from the `@apostrophecms/job` module. These options were not yet in use for A3.
+* Renames methods and removes unsupported routes in the `@apostrophecms/job` module that were not yet in use. This was not done lightly, but specifically because of the minimal likelihood that they were in use in project code given the lack of UI support.
+  * The deprecated `cancel` route was removed and will likely be replaced at a later date.
+  * `run` was renamed `runBatch` as its purpose is specifically to run processes on a "batch selected" array of pieces or pages.
+  * `runNonBatch` was renamed to `run` as it is the more generic job-running method. It is likely that `runBatch` will eventually be refactored to use this method.
+  * The `good` and `bad` methods are renamed `success` and `failure`, respectively. The expected methods used in the `run` method were similarly renamed. They still increment job document properties called `good` and `bad`.
+* Comments out the unused `batchSimpleRoute` methods in the page and piece-type modules to avoid usage before they are fully implemented.
+* Optionally add `dimensionAttrs` option to image widget, which sets width & height attributes to optimize for Cumulative Layout Shift.
+* Temporarily removes `npm audit` from our automated tests because of a sub-dependency of uploadfs that doesn't actually cause a security vulnerability for apostrophe.
+
+## 3.7.0 - 2021-10-28
+
+### Adds
+
+* Schema select field choices can now be populated by a server side function, like an API call. Set the `choices` property to a method name of the calling module. That function should take a single argument of `req`, and return an array of objects with `label` and `value` properties. The function can be async and will be awaited.
+* Apostrophe now has built-in support for the Node.js cluster module. If the `APOS_CLUSTER_PROCESSES` environment variable is set to a number, that number of child processes are forked, sharing the same listening port. If the variable is set to `0`, one process is forked for each CPU core, with a minimum of `2` to provide availability during restarts. If the variable is set to a negative number, that number is added to the number of CPU cores, e.g. `-1` is a good way to reserve one core for MongoDB if it is running on the same server. This is for production use only (`NODE_ENV=production`). If a child process fails it is restarted automatically.
 
 ### Fixes
 
+* Prevents double-escaping interpolated localization strings in the UI.
+* Rich text editor style labels are now run through a localization method to get the translated strings from their l10n keys.
+* Fixes README Node version requirement (Node 12+).
+* The text alignment buttons now work immediately in a new rich text widget. Previously they worked only after manually setting a style or refreshing the page. Thanks to Michelin for their support of this fix.
+* Users can now activate the built-in date and time editing popups of modern browsers when using the `date` and `time` schema field types.
+* Developers can now `require` their project `app.js` file in the Node.js REPL for debugging and inspection. Thanks to [Matthew Francis Brunetti](https://github.com/zenflow).
+* If a static text phrase is unavailable in both the current locale and the default locale, Apostrophe will always fall back to the `en` locale as a last resort, which ensures the admin UI works if it has not been translated.
+* Developers can now `require` their project `app.js` in the Node.js REPL for debugging and inspection
+* Ensure array field items have valid _id prop before storing. Thanks to Thanks to [Matthew Francis Brunetti](https://github.com/zenflow).
+
+### Changes
+
+* In 3.x, `relationship` fields have an optional `builders` property, which replaces `filters` from 2.x, and within that an optional `project` property, which replaces `projection` from 2.x (to match MongoDB's `cursor.project`). Prior to this release leaving the old syntax in place could lead to severe performance problems due to a lack of projections. Starting with this release the 2.x syntax results in an error at startup to help the developer correct their code.
+* The `className` option from the widget options in a rich text area field is now also applied to the rich text editor itself, for a consistently WYSIWYG appearance when editing and when viewing. Thanks to [Max Mulatz](https://github.com/klappradla) for this contribution.
+* Adds deprecation notes to doc module `afterLoad` events, which are deprecated.
+* Removes unused `afterLogin` method in the login module.
+
+## 3.6.0 - 2021-10-13
+
+### Adds
+
+* The `context-editing` apostrophe admin UI bus event can now take a boolean parameter, explicitly indicating whether the user is actively typing or performing a similar active manipulation of controls right now. If a boolean parameter is not passed, the existing 1100-millisecond debounced timeout is used.
+* Adds 'no-search' modifier to relationship fields as a UI simplification option.
+* Fields can now have their own `modifiers` array. This is combined with the schema modifiers, allowing for finer grained control of field rendering.
+* Adds a Slovak localization file. Activate the `sk` locale to use this. Many thanks to [Michael Huna](https://github.com/Miselrkba) for the contribution.
+* Adds a Spanish localization file. Activate the `es` locale to use this. Many thanks to [Eugenio Gonzalez](https://github.com/egonzalezg9) for the contribution.
+* Adds a Brazilian Portuguese localization file. Activate the `pt-BR` locale to use this. Many thanks to [Pietro Rutzen](https://github.com/pietro-rutzen) for the contribution.
+
+### Fixes
+
+* Fixed missing translation for "New Piece" option on the "more" menu of the piece manager, seen when using it as a chooser.
+* Piece types with relationships to multiple other piece types may now be configured in any order, relative to the other piece types. This sometimes appeared to be a bug in reverse relationships.
+* Code at the project level now overrides code found in modules that use `improve` for the same module name. For example, options set by the `@apostrophecms/seo-global` improvement that ships with `@apostrophecms/seo` can now be overridden at project level by `/modules/@apostrophecms/global/index.js` in the way one would expect.
+* Array input component edit button label is now propertly localized.
+* A memory leak on each request has been fixed, and performance improved, by avoiding the use of new Nunjucks environments for each request. Thanks to Miro Yovchev for pointing out the leak.
+* Fragments now have access to `__t()`, `getOptions` and other features passed to regular templates.
+* Fixes field group cascade merging, using the original group label if none is given in the new field group configuration.
+* If a field is conditional (using an `if` option), is required, but the condition has not been met, it no longer throws a validation error.
+* Passing `busy: true` to `apos.http.post` and related methods no longer produces an error if invoked when logged out, however note that there will likely never be a UI for this when logged out, so indicate busy state in your own way.
+* Bugs in document modification detection have been fixed. These bugs caused edge cases where modifications were not detected and the "Update" button did not appear, and could cause false positives as well.
+
+### Changes
+
+* No longer logs a warning about no users if `testModule` is true on the app.
+
+## 3.5.0 - 2021-09-23
+
 * Pinned dependency on `vue-material-design-icons` to fix `apos-build.js` build error in production.
 * The file size of uploaded media is visible again when selected in the editor, and media information such as upload date, dimensions and file size is now properly localized.
 * Fixes moog error messages to reflect the recommended pattern of customization functions only taking `self` as an argument.
@@ -18,6 +111,7 @@
 ### Changes
 
 * Cascade grouping (e.g., grouping fields) will now concatenate a group's field name array with the field name array of an existing group of the same name. Put simply, if a new piece module adds their custom fields to a `basics` group, that field will be added to the default `basics` group fields. Previously the new group would have replaced the old, leaving inherited fields in the "Ungrouped" section.
+* AposButton's `block` modifier now less login-specific
 
 ### Adds
 
@@ -133,8 +227,7 @@ No changes. Publishing to correctly mark the latest 3.x release as "latest" in n
 can include the widget on the clipboard, a special Clipboard widget will appear in area's Add UI. This works across pages as well.
 
 ### Changes
-* Apostrophe's Global's UI (the @apostrophecms/global singleton has moved from the admin bar's content controls to
-the admin utility tray under a cog icon.
+* Apostrophe's Global's UI (the @apostrophecms/global singleton has moved from the admin bar's content controls to the admin utility tray under a cog icon.
 * The context bar's document Edit button, which was a cog icon, has been rolled into the doc's context menu.
 
 ## 3.1.3 - 2021-07-16

package/README.md

@@ -43,7 +43,7 @@ We recommend installing the following with [Homebrew](https://brew.sh/) on macOS
 
 | Software | Minimum Version | Notes
 | ------------- | ------------- | -----
-| Node.js | 10.x | Or better
+| Node.js | 12.x | Or better
 | npm  | 6.x  | Or better
 | MongoDB  | 3.6  | Or better
 | Imagemagick  | Any | Faster image uploads, GIF support (optional)

package/index.js

@@ -2,11 +2,43 @@ const path = require('path');
 const _ = require('lodash');
 const argv = require('boring')({ end: true });
 const fs = require('fs');
+const { stripIndent } = require('common-tags');
+const cluster = require('cluster');
+const { cpus } = require('os');
+const process = require('process');
 const npmResolve = require('resolve');
+
 let defaults = require('./defaults.js');
-const { stripIndent } = require('common-tags');
 
-// **Awaiting the Apostrophe function is optional**
+// ## Top-level options
+//
+// `cluster`
+//
+// If set to `true`, Apostrophe will spawn as many processes as
+// there are CPU cores on the server, or a minimum of 2, and balance
+// incoming connections among them. This ensures availability while one
+// process is restarting due to a crash and also increases scalability if
+// the server has multiple CPU cores.
+//
+// If set to an object with a `processes` property, that many
+// processes are started. If `processes` is 0 or a negative number,
+// it is added to the number of CPU cores reported by the server.
+// Notably, `-1` can be a good way to reserve one CPU core for MongoDB
+// in a single-server deployment.
+//
+// However when in cluster mode no fewer than 2 processes will be
+// started as there is no availability benefit without at least 2.
+//
+// If a child process exits with a failure status code it will be
+// restarted. However, if it exits in less than 20 seconds after
+// startup there will be a 20 second delay to avoid flooding logs
+// and pinning the CPU.
+//
+// Alternatively the `APOS_CLUSTER_PROCESSES` environment variable
+// can be set to a number, which will effectively set the cluster
+// option to `cluster: { processes: n }`.
+//
+// ## Awaiting the Apostrophe function
 //
 // The apos function is async, but in typical cases you do not
 // need to await it. If you simply call it, Apostrophe will
@@ -21,8 +53,63 @@ const { stripIndent } = require('common-tags');
 // To avoid exiting on errors, pass the `exit: false` option.
 // This can option also can be used to allow awaiting a command line
 // task, as they also normally exit on completion.
+//
+// If `options.cluster` is truthy, the function quickly resolves to
+// `null` in the primary process. In the child process it resolves as
+// documented above.
 
 module.exports = async function(options) {
+  const guardTime = 20000;
+  if (process.env.APOS_CLUSTER_PROCESSES) {
+    options.cluster = {
+      processes: parseInt(process.env.APOS_CLUSTER_PROCESSES)
+    };
+  }
+  if (options.cluster && (process.env.NODE_ENV !== 'production')) {
+    console.log('NODE_ENV is not set to production, disabling cluster mode');
+    options.cluster = false;
+  }
+  if (options.cluster && !argv._.length) {
+    // For bc with node 14 and below we need to check both
+    if (cluster.isPrimary || cluster.isMaster) {
+      let processes = options.cluster.processes || cpus().length;
+      if (processes <= 0) {
+        processes = cpus().length + processes;
+      }
+      let capped = '';
+      if (processes > cpus().length) {
+        processes = cpus().length;
+        capped = ' (capped to number of CPU cores)';
+      }
+      if (processes < 2) {
+        processes = 2;
+        if (capped) {
+          capped = ' (less than 2 cores, capped to minimum of 2)';
+        } else {
+          capped = ' (using minimum of 2)';
+        }
+      }
+      console.log(`Starting ${processes} cluster child processes${capped}`);
+      for (let i = 0; i < processes; i++) {
+        clusterFork();
+      }
+      cluster.on('exit', (worker, code, signal) => {
+        if (code !== 0) {
+          if ((Date.now() - worker.bornAt) < guardTime) {
+            console.error(`Worker process ${worker.process.pid} failed in ${seconds(Date.now() - worker.bornAt)}, waiting ${seconds(guardTime)} before restart`);
+            setTimeout(() => {
+              respawn(worker);
+            }, guardTime);
+          } else {
+            respawn(worker);
+          }
+        }
+      });
+      return null;
+    } else {
+      console.log(`Cluster worker ${process.pid} started`);
+    }
+  }
 
   // The core is not a true moog object but it must look enough like one
   // to participate as an async event emitter
@@ -174,7 +261,7 @@ module.exports = async function(options) {
   function getRoot() {
     let _module = module;
     let m = _module;
-    while (m.parent) {
+    while (m.parent && m.parent.filename) {
       // The test file is the root as far as we are concerned,
       // not mocha itself
       if (m.parent.filename.match(/\/node_modules\/mocha\//)) {
@@ -334,6 +421,10 @@ module.exports = async function(options) {
       synth.define(name, options);
     });
 
+    // Apostrophe prefers that any improvements to @apostrophecms/global
+    // be applied before any project level version of @apostrophecms/global
+    synth.applyImprovementsBeforeProjectLevel();
+
     return synth;
   }
 
@@ -514,3 +605,17 @@ module.exports.bundle = {
   modules: abstractClasses.concat(_.keys(defaults.modules)),
   directory: 'modules'
 };
+
+function seconds(msec) {
+  return (Math.round(msec / 100) / 10) + ' seconds';
+}
+
+function clusterFork() {
+  const worker = cluster.fork();
+  worker.bornAt = Date.now();
+}
+
+function respawn(worker) {
+  console.error(`Respawning worker process ${worker.process.pid}`);
+  clusterFork();
+}

package/lib/moog-require.js

@@ -202,5 +202,28 @@ module.exports = function(options) {
     return _.has(self.improvements, name);
   };
 
+  self.applyImprovementsBeforeProjectLevel = () => {
+    for (const [ name, definition ] of Object.entries(self.definitions)) {
+      // At this stage the complete definition of a type is a linked list of `extend`
+      // properties starting from what should be project level, unless there
+      // are improvements. Shuffle project level to be the first in the
+      // linked list
+      if (definition.__meta.name !== self.originalToMy(name)) {
+        let candidate = definition;
+        let predecessor = null;
+        while (candidate.extend && ((typeof candidate.extend) === 'object')) {
+          predecessor = candidate;
+          candidate = candidate.extend;
+          if (candidate.__meta.name === self.originalToMy(name)) {
+            predecessor.extend = candidate.extend;
+            candidate.extend = definition;
+            self.definitions[name] = candidate;
+            break;
+          }
+        }
+      }
+    }
+  };
+
   return self;
 };

package/lib/moog.js

@@ -211,6 +211,7 @@ module.exports = function(options) {
             for (const [ key, value ] of Object.entries(properties.group)) {
               if (groups[key] && Array.isArray(groups[key].fields)) {
                 value.fields = groups[key].fields.concat(value.fields);
+                value.label = value.label || groups[key].label;
               }
             }
 

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

@@ -259,20 +259,32 @@ export default {
       // So that areas revert to being editable
       await this.refresh();
     },
-    async onContextEditing() {
-      // Accept a hint that someone is actively typing in a
-      // rich text editor and a context-edited event is likely
-      // coming; allows continuity of the "Saving..." indicator
-      // so it doesn't flicker once a second as you type
-      this.editing = true;
-      if (this.editingTimeout) {
-        clearTimeout(this.editingTimeout);
+    // Accept a hint that a user is actively typing and/or manipulating controls
+    // and it would best not to enable a save button or a "...Saved" indication yet
+    // to avoid a frenetic display and/or a situation where not everything is ready
+    // to be saved yet.
+    //
+    // If the event is emitted with a boolean value of `true`, the emitter takes
+    // responsibility for later emitting `false` to indicate active typing/manipulating
+    // is no longer in progress. If the event is emitted with no value then there is a
+    // 1100-millisecond, debounced timeout.
+
+    async onContextEditing(state) {
+      if ((typeof state) === 'boolean') {
+        this.editing = state;
+      } else {
+        if (!this.editing) {
+          this.editing = true;
+        }
+        if (this.editingTimeout) {
+          clearTimeout(this.editingTimeout);
+        }
+        this.editingTimeout = setTimeout(() => {
+          this.editing = false;
+          // Wait slightly longer than the rich text editor does
+          // before sending us a context-edited event
+        }, 1100);
       }
-      this.editingTimeout = setTimeout(() => {
-        this.editing = false;
-        // Wait slightly longer than the rich text editor does
-        // before sending us a context-edited event
-      }, 1100);
     },
     async onPublish(e) {
       if (!this.canPublish) {
@@ -451,7 +463,11 @@ export default {
       }
     },
     async onContentChanged(e) {
-      if (e.doc && (e.doc._id === this.context._id)) {
+
+      if (
+        (e.doc && (e.doc._id === this.context._id)) ||
+        (e.docIds && e.docIds.includes(this.context._id))
+      ) {
         if (e.action === 'delete') {
           if (!this.contextStack.length) {
             // With the current page gone, we need to move to safe ground

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

@@ -46,7 +46,7 @@ module.exports = function(self) {
       return { args };
     },
     async run(context, doc, name, _with) {
-      const req = context.env.opts.req;
+      const req = context.ctx.__req;
       let area;
       if ((!doc) || ((typeof doc) !== 'object')) {
         throw usage('You must pass an existing doc or widget as the first argument.');

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

@@ -40,7 +40,7 @@ module.exports = function(self) {
       return { args };
     },
     async run(context, item, options, _with) {
-      const req = context.env.opts.req;
+      const req = context.ctx.__req;
       if (!item) {
         self.apos.util.warn('a null widget was encountered.');
         return '';

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

@@ -615,8 +615,8 @@ export default {
   }
 
   .apos-area-widget-wrapper--foreign .apos-area-widget-inner .apos-area-widget__breadcrumbs {
-    background-color: var(--a-primary);
-    & ::v-deep .apos-button {
+    background-color: var(--a-background-inverted);
+    & ::v-deep .apos-button__content {
       color: var(--a-text-inverted);
     }
   }

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

@@ -73,6 +73,12 @@ module.exports = {
           await fs.remove(buildDir);
           await fs.mkdirp(buildDir);
 
+          // Static asset files in `public` subdirs of each module are copied
+          // to the same relative path `/public/apos-frontend/namespace/modules/modulename`.
+          // Inherited files are also copied, with the deepest subclass overriding in the
+          // event of a conflict
+          await moduleOverrides(`${bundleDir}/modules`, 'public');
+
           for (const [ name, options ] of Object.entries(self.builds)) {
             // If the option is not present always rebuild everything
             let rebuild = argv && !argv['check-apos-build'];
@@ -122,12 +128,17 @@ module.exports = {
           // just `public` and `apos`) by examining those specified as
           // targets for the various builds
           const scenes = [ ...new Set(Object.values(self.builds).map(options => options.scenes).flat()) ];
-          let bundles = [];
+          let deployFiles = [];
           for (const scene of scenes) {
-            bundles = [ ...bundles, ...merge(scene) ];
+            deployFiles = [ ...deployFiles, ...merge(scene) ];
           }
-
-          await deploy(bundles);
+          // enumerate public assets and include them in deployment if appropriate
+          const publicAssets = glob.sync('modules/**/*', {
+            cwd: bundleDir,
+            mark: true
+          }).filter(match => !match.endsWith('/'));
+          deployFiles = [ ...deployFiles, ...publicAssets ];
+          await deploy(deployFiles);
 
           if (process.env.APOS_BUNDLE_ANALYZER) {
             return new Promise((resolve, reject) => {
@@ -162,7 +173,7 @@ module.exports = {
             for (const name of names) {
               const moduleDir = `${modulesDir}/${name}`;
               for (const dir of directories[name]) {
-                const srcDir = `${dir}/ui/${source}`;
+                const srcDir = `${dir}/${source}`;
                 if (fs.existsSync(srcDir)) {
                   await fs.copy(srcDir, moduleDir);
                 }
@@ -176,7 +187,7 @@ module.exports = {
             }));
             const modulesDir = `${buildDir}/${name}/modules`;
             const source = options.source || name;
-            await moduleOverrides(modulesDir, source);
+            await moduleOverrides(modulesDir, `ui/${source}`);
 
             let iconImports, componentImports, tiptapExtensionImports, appImports, indexJsImports, indexSassImports;
             if (options.apos) {
@@ -233,7 +244,8 @@ module.exports = {
               // Remove previous build artifacts, as some pipelines won't build all artifacts
               // if there is no input, and we don't want stale output in the bundle
               fs.removeSync(`${bundleDir}/${outputFilename}`);
-              fs.removeSync(`${bundleDir}/${outputFilename}`.replace(/\.js$/, '.css'));
+              const cssPath = `${bundleDir}/${outputFilename}`.replace(/\.js$/, '.css');
+              fs.removeSync(cssPath);
               await Promise.promisify(webpackModule)(require(`./lib/webpack/${name}/webpack.config`)(
                 {
                   importFile,
@@ -243,6 +255,11 @@ module.exports = {
                 },
                 self.apos
               ));
+              if (fs.existsSync(cssPath)) {
+                fs.writeFileSync(cssPath, self.filterCss(fs.readFileSync(cssPath, 'utf8'), {
+                  modulesPrefix: `${self.getAssetBaseUrl()}/modules`
+                }));
+              }
               if (options.apos) {
                 const now = Date.now().toString();
                 fs.writeFileSync(`${bundleDir}/${name}-build-timestamp.txt`, now);
@@ -269,7 +286,9 @@ module.exports = {
                 const publicImports = getImports(name, '*.css', { });
                 fs.writeFileSync(`${bundleDir}/${name}-build.css`,
                   publicImports.paths.map(path => {
-                    return fs.readFileSync(path, 'utf8');
+                    return self.filterCss(fs.readFileSync(path, 'utf8'), {
+                      modulesPrefix: `${self.getAssetBaseUrl()}/modules`
+                    });
                   }).join('\n')
                 );
               }
@@ -358,7 +377,19 @@ module.exports = {
             return [ jsModules, jsNoModules, css ];
           }
 
-          async function deploy(bundles) {
+          // If NODE_ENV is production, this function will copy the given
+          // array of asset files from `${bundleDir}/${file}` to
+          // the same relative location in the appropriate release subdirectory in
+          // `/public/apos-frontend/releases`, or in `/apos-frontend/releases` in
+          // uploadfs if `APOS_UPLOADFS_ASSETS` is present.
+          //
+          // If NODE_ENV is not production this function does nothing and
+          // the assets are served directly from `/public/apos-frontend/${file}`.
+          //
+          // The namespace (e.g. default) should be part of each filename given.
+          // A leading slash should NOT be passed.
+
+          async function deploy(files) {
             if (process.env.NODE_ENV !== 'production') {
               return;
             }
@@ -373,17 +404,23 @@ module.exports = {
             } else {
               // The right choice with Docker if uploadfs is just the local filesystem
               // mapped to a volume (a Docker build step can't access that)
-              copyIn = fs.copyFile;
+              copyIn = fsCopyIn;
               releaseDir = `${self.apos.rootDir}/public/apos-frontend/releases/${releaseId}/${namespace}`;
               await fs.mkdirp(releaseDir);
             }
-            for (const bundle of bundles) {
-              const src = `${bundleDir}/${bundle}`;
-              await copyIn(src, `${releaseDir}/${bundle}`);
+            for (const file of files) {
+              const src = `${bundleDir}/${file}`;
+              await copyIn(src, `${releaseDir}/${file}`);
               await fs.remove(src);
             }
           }
 
+          async function fsCopyIn(from, to) {
+            const base = path.dirname(to);
+            await fs.mkdirp(base);
+            return fs.copyFile(from, to);
+          }
+
           function getImports(folder, pattern, options) {
             let components = [];
             const seen = {};
@@ -650,6 +687,30 @@ module.exports = {
         if (!self.options.es5) {
           delete self.builds['src-es5'];
         }
+      },
+      // Filter the given css performing any necessary transformations,
+      // such as support for the /modules path regardless of where
+      // static assets are actually deployed
+      filterCss(css, { modulesPrefix }) {
+        return self.filterCssUrls(css, url => {
+          if (url.startsWith('/modules')) {
+            return url.replace('/modules', modulesPrefix);
+          }
+          return url;
+        });
+      },
+      // Run all URLs in CSS through a filter function
+      filterCssUrls(css, filter) {
+        css = css.replace(/url\(([^'"].*?)\)/g, function(s, url) {
+          return 'url(' + filter(url) + ')';
+        });
+        css = css.replace(/url\("([^"]+?)"\)/g, function(s, url) {
+          return 'url("' + filter(url) + '")';
+        });
+        css = css.replace(/url\('([^']+?)'\)/g, function(s, url) {
+          return 'url(\'' + filter(url) + '\')';
+        });
+        return css;
       }
     };
   },
@@ -667,6 +728,9 @@ module.exports = {
         }
         const script = fs.readFileSync(path.join(__dirname, '/lib/refresh-on-restart.js'), 'utf8');
         return self.apos.template.safe(`<script data-apos-refresh-on-restart="${self.action}/restart-id">\n${script}</script>`);
+      },
+      url(path) {
+        return `${self.getAssetBaseUrl()}${path}`;
       }
     };
   },

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

@@ -1038,6 +1038,7 @@ module.exports = {
           action: self.action,
           fileGroups: self.fileGroups,
           name: self.name,
+          // for bc
           uploadsUrl: self.uploadfs.getUrl(),
           croppable: self.croppable,
           sized: self.sized

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

@@ -1,4 +1,4 @@
-// This module establishes `apos.db`, the mongodb driver connection object.
+// This module establishes `apos.db`, the MongoDB database object.
 //
 // ## Options
 //
@@ -20,8 +20,7 @@
 //
 // ### `client`
 //
-// An existing MongoDB connection (MongoClient) object. If present, a new
-// connection instance is created that reuses the same sockets,
+// An existing MongoDB connection (MongoClient) object. If present, it is used
 // and `uri`, `host`, `connect`, etc. are ignored.
 //
 // ### `versionCheck`
@@ -40,7 +39,7 @@
 // allow other modules to drop related non-MongoDB resources at the
 // same time, if desired.
 //
-// Note that `apos.db` is the mongodb database object, not this module.
+// Note that `apos.db` is the MongoDB database object, not this module.
 // You shouldn't need to talk to this module after startup, but you can
 // access it as `apos.modules['@apostrophecms/db']` if you wish. You can
 // also access `apos.dbClient` if you need the MongoClient object.
@@ -81,8 +80,8 @@ module.exports = {
   },
   methods(self) {
     return {
-      // Open the database connection. Always use MongoClient with its
-      // sensible defaults. Build a URI if we need to, so we can call it
+      // Open the database connection. Always uses MongoClient with its
+      // sensible defaults. Builds a URI if necessary, so we can call it
       // in a consistent way.
       //
       // One default we override: if the connection is lost, we keep