@adobe/aem-cli 16.16.33 → 16.17.0

package/CHANGELOG.md

@@ -1,3 +1,10 @@
+# [16.17.0](https://github.com/adobe/helix-cli/compare/v16.16.33...v16.17.0) (2026-04-07)
+
+
+### Features
+
+* **html-folder:** Add --html-mount flag to control URL path for html-folder serving ([#2697](https://github.com/adobe/helix-cli/issues/2697)) ([4ed1f4b](https://github.com/adobe/helix-cli/commit/4ed1f4bea996e2afcf79dd1fc94f2809689ed772))
+
 ## [16.16.33](https://github.com/adobe/helix-cli/compare/v16.16.32...v16.16.33) (2026-04-06)
 
 

package/README.md

@@ -79,13 +79,17 @@ This feature is especially helpful when:
 The `--html-folder` option enables serving HTML files without extensions, useful for previewing content changes when you don't have access to the authoring system.
 
 ```
-$ aem up --html-folder content
+$ aem up --html-folder drafts                      # serves at /drafts/*
+$ aem up --html-folder content --html-mount /       # serves at /* (root)
+$ aem up --html-folder drafts --html-mount /preview # serves at /preview/*
 ```
 
+Use `--html-mount` to control the URL path where files are served. Without it, files are served at `/FOLDER/*`.
+
 This enables two features:
 
-1. **Extension-less URLs**: Access `/content/page` to serve `content/page.html`
-2. **Plain HTML with metadata**: Create `content/page.plain.html` files that are automatically wrapped with proper HTML structure and metadata processing
+1. **Extension-less URLs**: Access `/drafts/page` (or `/page` with root mount) to serve the corresponding `.html` file
+2. **Plain HTML with metadata**: Create `.plain.html` files that are automatically wrapped with proper HTML structure and metadata processing
 
 #### Plain HTML files (.plain.html)
 
@@ -181,7 +185,8 @@ If present, `ALL_PROXY` is used as fallback if there is no other match.
 | `--livereload`    | `AEM_LIVERELOAD`    | `true`      | Enable automatic reloading of modified sources in browser.  |
 | `--no-livereload` | `AEM_NO_LIVERELOAD` | `false`     | Disable live-reload.                                        |
 | `--forward-browser-logs` | `AEM_FORWARD_BROWSER_LOGS` | `false` | Forward browser console logs to terminal.            |
-| `--html-folder`   | `AEM_HTML_FOLDER`   | undefined   | Serve HTML files from folder without extensions. Supports .html and .plain.html files. |
+| `--html-folder`   | `AEM_HTML_FOLDER`   | undefined   | Serve HTML files from folder without extensions. |
+| `--html-mount`    | `AEM_HTML_MOUNT`    | `/FOLDER`   | URL path where html-folder files are served. |
 | `--open`          | `AEM_OPEN`          | `/`         | Open a browser window at specified path after server start. |
 | `--no-open`       | `AEM_NO_OPEN`       | `false`     | Disable automatic opening of browser window.                |
 | `--tls-key`       | `AEM_TLS_KEY`       | undefined   | Path to .key file (for enabling TLS)                        |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adobe/aem-cli",
-  "version": "16.16.33",
+  "version": "16.17.0",
   "description": "AEM CLI",
   "main": "index.js",
   "type": "module",

package/src/server/HelixProject.js

@@ -86,16 +86,16 @@ export class HelixProject extends BaseProject {
       if (path.isAbsolute(value) || value.includes('..') || value.startsWith('/')) {
         throw new Error(`Invalid HTML folder name: ${value} only folders within the current workspace are allowed`);
       }
-
-      this._htmlFolder = value;
-      this._server.withHtmlFolder(value);
-    } else {
       this._htmlFolder = value;
-      this._server.withHtmlFolder(value);
     }
     return this;
   }
 
+  withHtmlMount(value) {
+    this._htmlMount = value;
+    return this;
+  }
+
   get proxyUrl() {
     return this._proxyUrl;
   }
@@ -142,6 +142,10 @@ export class HelixProject extends BaseProject {
   }
 
   async init() {
+    if (this._htmlFolder) {
+      const mount = this._htmlMount || `/${this._htmlFolder}`;
+      this._server.withHtmlFolder(this._htmlFolder, mount);
+    }
     await super.init();
     this._indexer = new Indexer()
       .withLogger(this._logger)
@@ -206,7 +210,7 @@ export class HelixProject extends BaseProject {
         await lstat(htmlFolderPath);
         this.log.debug(`Registered HTML folder for live-reload: ${this._htmlFolder}`);
         // Watch all HTML files in the folder - only .html extension
-        this.liveReload.registerFiles([`${htmlFolderPath}/**/*.html`], `/${this._htmlFolder}/`);
+        this.liveReload.registerFiles([`${htmlFolderPath}/**/*.html`], this._server.mountPrefix);
       } catch (e) {
         this.log.error(`HTML folder '${this._htmlFolder}' does not exist`);
         throw new Error(`HTML folder '${this._htmlFolder}' does not exist`);

package/src/server/HelixServer.js

@@ -63,12 +63,17 @@ export class HelixServer extends BaseServer {
     return this;
   }
 
-  withHtmlFolder(value) {
-    // It's now sanitized in HelixProject.withHtmlFolder
-    this._htmlFolder = value;
+  withHtmlFolder(folder, mount) {
+    this._htmlFolder = folder;
+    this._htmlMount = mount;
+    this._mountPrefix = mount.endsWith('/') ? mount : `${mount}/`;
     return this;
   }
 
+  get mountPrefix() {
+    return this._mountPrefix;
+  }
+
   async handleLogin(req, res) {
     const userAgent = req.headers['user-agent']?.toLowerCase();
     if (userAgent?.includes('safari') && !userAgent?.includes('chrome')) {
@@ -262,22 +267,15 @@ export class HelixServer extends BaseServer {
    * @param {Function} next next middleware
    */
   async handleHtmlFolderRequest(req, res, next) {
-    if (!this._htmlFolder) {
-      return next();
-    }
-
-    // Use Express's req.path for pathname extraction
     const pathname = req.path;
-    const folderPrefix = `/${this._htmlFolder}/`;
 
-    // Check if the request is for the HTML folder
-    if (!pathname.startsWith(folderPrefix)) {
+    let relativePath;
+    if (pathname.startsWith(this._mountPrefix)) {
+      relativePath = pathname.slice(this._mountPrefix.length);
+    } else {
       return next();
     }
 
-    // Extract the path within the HTML folder
-    let relativePath = pathname.slice(folderPrefix.length);
-
     // Handle directory requests (trailing slash) by appending 'index'
     if (relativePath === '' || relativePath.endsWith('/')) {
       relativePath = `${relativePath}index`.replace(/\/+/g, '/');
@@ -452,10 +450,9 @@ export class HelixServer extends BaseServer {
 
     // Add HTML folder handler before the general proxy handler
     if (this._htmlFolder) {
-      // Only handle GET requests for the HTML folder path
-      const htmlFolderPattern = new RegExp(`^/${this._htmlFolder}/.*`);
-      this.app.get(htmlFolderPattern, asyncHandler(this.handleHtmlFolderRequest.bind(this)));
-      this.log.info(`Serving HTML files from folder: ${this._htmlFolder}`);
+      const mountPattern = new RegExp(`^${this._mountPrefix}.*`);
+      this.app.get(mountPattern, asyncHandler(this.handleHtmlFolderRequest.bind(this)));
+      this.log.info(`Serving HTML files from folder: ${this._htmlFolder} at ${this._htmlMount}`);
     }
 
     const handler = asyncHandler(this.handleProxyModeRequest.bind(this));

package/src/up.cmd.js

@@ -56,11 +56,15 @@ export default class UpCommand extends AbstractServerCommand {
   }
 
   withHtmlFolder(value) {
-    // Basic validation - detailed validation done in HelixProject
     this._htmlFolder = value;
     return this;
   }
 
+  withHtmlMount(value) {
+    this._htmlMount = value;
+    return this;
+  }
+
   async doStop() {
     await super.doStop();
     if (this._watcher) {
@@ -113,7 +117,8 @@ export default class UpCommand extends AbstractServerCommand {
       .withAllowInsecure(this._allowInsecure)
       .withSiteToken(this._siteToken)
       .withCookies(this._cookies)
-      .withHtmlFolder(this._htmlFolder);
+      .withHtmlFolder(this._htmlFolder)
+      .withHtmlMount(this._htmlMount);
 
     this.log.info(chalk`{yellow     ___    ________  ___                          __      __ v${pkgJson.version}}`);
     this.log.info(chalk`{yellow    /   |  / ____/  |/  /  _____(_)___ ___  __  __/ /___ _/ /_____  _____}`);

package/src/up.js

@@ -117,7 +117,12 @@ export default function up() {
         })
         .option('html-folder', {
           alias: 'htmlFolder',
-          describe: 'Serve HTML files from this folder without extensions (e.g., /folder/file serves folder/file.html or folder/file.plain.html) use this to preview content changes if you do not have access to the authoring system',
+          describe: 'Serve HTML files from this folder without extensions. Defaults to serving at /FOLDER.',
+          type: 'string',
+        })
+        .option('html-mount', {
+          alias: 'htmlMount',
+          describe: 'URL path where html-folder files are served (e.g., / for root). Defaults to /FOLDER.',
           type: 'string',
         })
 
@@ -147,6 +152,7 @@ export default function up() {
         .withCache(argv.alphaCache)
         .withCookies(argv.cookies)
         .withHtmlFolder(argv.htmlFolder)
+        .withHtmlMount(argv.htmlMount)
         .run();
     },
   };