[Docs Review] Chapter 14 CLI — Technical Accuracy Issues

[lcharette]

Chapter 14: CLI — Technical Accuracy Review

Cross-referenced against userfrosting/monorepo. All issues verified against source code.

---

🔴 CRITICAL — assets:build aliases webpack and build-assets do not exist

File: app/pages/6.0/14.cli/01.commands/docs.md, line 39

"assets:build (alias : webpack & build-assets)"

Verification: AssetsBuildCommand.php only calls setName('assets:build') with no setAliases(). No WebpackCommand.php or BuildAssetsCommand.php file exists anywhere in the Bakery directory.

These aliases existed in older versions of UserFrosting but have been removed in UF6. Running php bakery webpack or php bakery build-assets will throw a "command not found" error.

Fix: Remove (alias : \webpack` & `build-assets`)` from the command description.

---

🔴 CRITICAL — assets:build described as combining assets:install + assets:webpack (wrong for default Vite)

File: app/pages/6.0/14.cli/01.commands/docs.md, lines 39–40

"It combines assets:install and assets:webpack into a single command."

Actual behavior (from AssetsBuildCommandListener.php):

• Vite (default bundler, assets.vite.dev = true): Runs only assets:install. No build step.
• Vite (production, assets.vite.dev = false): Runs assets:install then assets:vite.
• Webpack bundler: Runs assets:install then assets:webpack.

The command is event-driven and adapts to your bundler configuration. For the default Vite setup, assets:webpack is never called.

Fix: Rewrite the description to explain the configurable/event-driven nature, e.g.:

"assets:build is a meta-command that installs frontend dependencies and triggers a production build. The exact commands run depend on your configured bundler (Vite or Webpack). For Vite (the default), it runs assets:install and optionally assets:vite depending on the environment."

---

🔴 CRITICAL — assets:webpack npm script names are wrong

File: app/pages/6.0/14.cli/01.commands/docs.md, lines 68–71

The table shows:

Option	Alias of
(default)	npm run dev
--production	npm run build
--watch	npm run watch

Actual (AssetsWebpackCommand.php):

default  => 'npm run webpack:dev',
prod     => 'npm run webpack:build',
--server => 'npm run webpack:server',
--watch  => 'npm run webpack:watch',

The webpack: prefix is required. The scripts dev, build, and watch do not exist in the skeleton's package.json. Also missing: the --server / -s option for the HMR dev server.

Fix: Update the table to show npm run webpack:dev, npm run webpack:build, npm run webpack:watch, and add a row for --server / npm run webpack:server.

---

🟡 MINOR — bake description includes create:admin-user as a default command

File: app/pages/6.0/14.cli/01.commands/docs.md, line 104

The description says bake combines: "setup:db, setup:mail, debug, migrate, create:admin-user, assets:build and clear-cache"

Actual (BakeCommand.php):

protected array $commands = [
    'setup:db', 'setup:mail', 'debug', 'migrate', 'assets:build', 'clear-cache',
];

create:admin-user is not a default command — it's added by the Account sprinkle's event listener. The following NOTE in the docs correctly explains this, but the opening description is misleading.

Fix: Remove create:admin-user from the main description; the NOTE that follows already handles the Account sprinkle case correctly.

---

🟡 MINOR — assets:install described as using packages.lock

File: app/pages/6.0/14.cli/01.commands/docs.md, line ~57

The docs mention packages.lock as the lock file. The correct filename is package-lock.json (confirmed in AssetsInstallCommand.php which explicitly references package-lock.json).

Fix: Replace packages.lock with package-lock.json.

---

Overall Assessment: Chapter 14

Score: 3 critical, 2 minor. The three critical issues all center on the assets:* commands: stale alias names that will throw runtime errors, a fundamentally incorrect description of how assets:build works for Vite setups (the default), and entirely wrong npm script names for assets:webpack. Anyone following the docs for Webpack-based assets will run the wrong npm commands. The bake and assets:install minor issues are low-risk but add noise.