@aligent/nx-appbuilder 0.2.1 → 0.4.0

package/README.md

@@ -96,16 +96,15 @@ The app generator always renders a **base** subtree into `<app-name>/`:
   - `package.json` - Pinned dependencies and `lint` / `lint:fix` / `check-types` / `test` scripts (per-target variants for actions, web and tests)
   - `package.json` `nx.targets` block - declares the custom `check-types` and `deploy` targets; `lint` and `test` are inferred by the `@nx/eslint/plugin` and `@nx/vitest` plugins from `eslint.config.mjs` and `vitest.config.ts`
   - `tsconfig.json` / `tsconfig.base.json` - TypeScript project config
-  - `babel.actions.config.js` - Babel preset for App Builder actions
-  - `eslint.config.mjs` / `prettier.config.mjs` - Lint and formatter config (`@aligent/ts-code-standards`)
+  - `eslint.config.mjs` / `prettier.config.mjs` - Lint and formatter config (`@aligent/ts-code-standards`). The eslint preset is `react` when `hasAdminUI=true` and `base` otherwise, so action-only apps don't load the React/JSX/a11y rules.
   - `vitest.config.ts` - Vitest config
   - `.editorconfig`, `.nvmrc`, `.gitignore`, `README.md`
 
 - **Action and test scaffolding**:
   - `src/actions/tsconfig.json` - TypeScript config for the App Builder actions
-  - `src/actions/webpack-config.cjs` - Webpack config used by the `aio` CLI to compile actions via `babel-loader`
+  - `src/actions/webpack-config.cjs` - Webpack config used by the `aio` CLI to compile actions via `esbuild-loader` (targets the workspace's Node major)
   - `tests/tsconfig.json` - TypeScript config for the test suite
-  - `hooks/check-action-types.sh` - `pre-app-build` hook that type-checks actions before deploy
+  - `hooks/check-action-types.sh` - Wired as the application-level `pre-app-build` hook in `app.config.yaml` so the action TypeScript is type-checked before every deploy. Custom (non-Adobe) actions also live under `application.runtimeManifest` in `app.config.yaml`; the scaffolded `ext.config.yaml` files are left for Adobe-generated content only.
   - `global-types/@adobe/aio-sdk/*.d.ts` - Local type augmentations for the Adobe AIO SDK
 
 - **Root updates**:
@@ -113,16 +112,16 @@ The app generator always renders a **base** subtree into `<app-name>/`:
 
 Additional subtrees are layered on top depending on the selected flags:
 
-| Flag                                                            | Subtree rendered                          | Notable additions                                                                                                                                                                                                 |
-|-----------------------------------------------------------------|-------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
-| any of `hasAdminUI`, `hasBusinessConfig`, `hasCommerceWebhooks` | `commerce-extensibility/`                 | `app.commerce.config.ts`, `install.yaml`, `commerce/extensibility/1` extension config; pulls in `@adobe/aio-commerce-lib-app` / `-config`.                                                                        |
-| `hasAdminUI`                                                    | `commerce-backend-ui/`                    | React 19 + Spectrum admin UI under `src/commerce-backend-ui-1/`, `web-src/` entry point, action utils, registration, `pre-app-build` web type-check hook.                                                         |
-| `hasBusinessConfig`                                             | `commerce-config/`                        | `commerce/configuration/1` extension config wired into `app.commerce.config.ts`; adds a `businessConfig.schema` block to `app.commerce.config.ts`.                                                                |
-| `hasCommerceWebhooks`                                           | none (modifies `commerce-extensibility/`) | Adds a `webhooks` section to `app.commerce.config.ts` for binding Commerce extensibility hooks to runtime actions or external URLs. No new files; relies on the `commerce-extensibility/` subtree being rendered. |
-| `hasRestActions`                                                | `rest-actions/`                           | `src/actions/rest-sample.ts` registered as a web action in `app.config.yaml`.                                                                                                                                     |
-| `hasEvents`                                                     | `events/`                                 | `src/actions/handle-sample-event.ts`, sample Commerce + external event subscriptions, `aio-lib-events` global types.                                                                                              |
-| `hasScheduledActions`                                           | `scheduled/`                              | `src/actions/cron-sample.ts` plus the `triggers`/`rules` entries that fire it on a cron schedule.                                                                                                                 |
-| `hasCustomInstallSteps`                                         | `install-steps/`                          | `scripts/install/sample-step.js` and an `installation.customInstallationSteps` entry in `app.commerce.config.ts`.                                                                                                 |
+| Flag                                                            | Subtree rendered                          | Notable additions                                                                                                                                                                                                                                                        |
+|-----------------------------------------------------------------|-------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| any of `hasAdminUI`, `hasBusinessConfig`, `hasCommerceWebhooks` | `commerce-extensibility/`                 | `app.commerce.config.ts`, `install.yaml`, `commerce/extensibility/1` extension config; pulls in `@adobe/aio-commerce-lib-app` / `-config`.                                                                                                                               |
+| `hasAdminUI`                                                    | `commerce-backend-ui/`                    | React 19 + Spectrum admin UI under `src/commerce-backend-ui-1/`, `web-src/` entry point (with `module: Preserve` / `moduleResolution: Bundler` so the webpack/esbuild pipeline sees ESM-style imports), action utils, registration, `pre-app-build` web type-check hook. |
+| `hasBusinessConfig`                                             | `commerce-config/`                        | `commerce/configuration/1` extension config wired into `app.commerce.config.ts`; adds a `businessConfig.schema` block to `app.commerce.config.ts`.                                                                                                                       |
+| `hasCommerceWebhooks`                                           | none (modifies `commerce-extensibility/`) | Adds a `webhooks` section to `app.commerce.config.ts` for binding Commerce extensibility hooks to runtime actions or external URLs. No new files; relies on the `commerce-extensibility/` subtree being rendered.                                                        |
+| `hasRestActions`                                                | `rest-actions/`                           | `src/actions/rest-sample.ts` registered as a web action in `app.config.yaml`.                                                                                                                                                                                            |
+| `hasEvents`                                                     | `events/`                                 | `src/actions/handle-sample-event.ts`, sample Commerce + external event subscriptions, `aio-lib-events` global types.                                                                                                                                                     |
+| `hasScheduledActions`                                           | `scheduled/`                              | `src/actions/cron-sample.ts` plus the `triggers`/`rules` entries that fire it on a cron schedule.                                                                                                                                                                        |
+| `hasCustomInstallSteps`                                         | `install-steps/`                          | `scripts/install/sample-step.js` and an `installation.customInstallationSteps` entry in `app.commerce.config.ts`.                                                                                                                                                        |
 
 #### Example
 
@@ -179,6 +178,15 @@ npx nx build nx-appbuilder
 
 The `@nx/js:tsc` build executor compiles `src/**/*.ts` to `dist/src/` and copies the templates under `src/generators/<gen>/files/` verbatim. Template files use the `.template` suffix (e.g. `app.commerce.config.ts.template`) so they aren't picked up by lint or `tsc`; `@nx/devkit`'s `generateFiles` strips the suffix at generation time.
 
+#### Dependency version pins
+
+Each generator reads the npm version specs it injects into generated files from a real `package.json` at `src/generators/<gen>/template-package/package.json`:
+
+- `preset/template-package/package.json` pins the workspace-level devDeps (`nx`, `@nx/*` plugins, `eslint`, `prettier`, `typescript`, `vitest`, `@aligent/ts-code-standards`).
+- `app/template-package/package.json` pins the per-app deps (`@adobe/aio-*`, React + Spectrum, lint/test tooling, etc.).
+
+Both files are tracked by Dependabot (see `.github/dependabot.yml`) so version bumps land via PR. To add a new pin, add it to the relevant template-package and reference it from `pickVersions()` in `preset.ts` / `compose-package-json.ts`. The shared helper at `src/generators/helpers/template-package.ts` enforces that every requested key exists in the template file, so missing pins fail loudly at runtime.
+
 ### Running tests / lint / type-check
 
 ```bash

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aligent/nx-appbuilder",
-  "version": "0.2.1",
+  "version": "0.4.0",
   "type": "commonjs",
   "main": "./src/index.js",
   "typings": "./src/index.d.ts",

package/src/generators/app/files/base/eslint.config.mjs.template

@@ -1,7 +1,7 @@
 import { eslintConfigs } from '@aligent/ts-code-standards';
 
 export default [
-    ...eslintConfigs.react,
+    ...eslintConfigs.<%= hasAdminUI ? 'react' : 'base' %>,
     {
         ignores: ['**/*.js', '**/*.cjs', '**/*.mjs', '**/coverage'],
     },

package/src/generators/app/files/base/src/actions/webpack-config.cjs.template

@@ -1,6 +1,8 @@
-// Webpack configuration required to compile typescript action and web source code
-// using the Adobe aio CLI. Adapted from https://github.com/adobe/aio-cli-plugin-app-dev, then switched to babel-loader
-// Appbuilder documentation: https://developer.adobe.com/app-builder/docs/guides/configuration/webpack-configuration/
+// Webpack config for action source. esbuild-loader strips the TypeScript and
+// targets the same Node version as the OpenWhisk runtime declared in
+// ext.config.yaml. aio's webpack pipeline emits a CommonJS bundle
+// (libraryTarget: 'commonjs2') which OpenWhisk loads via require().
+// Appbuilder docs: https://developer.adobe.com/app-builder/docs/guides/configuration/webpack-configuration/
 
 const path = require('path');
 
@@ -18,15 +20,12 @@ module.exports = {
     module: {
         rules: [
             {
-                // Test for .ts - in theory actions should never use .tsx
                 test: /\.ts$/,
                 exclude: /node_modules/,
-                loader: 'babel-loader',
+                loader: 'esbuild-loader',
                 options: {
-                    // Point to the babel config for actions
-                    // This is done to avoid Parcel reading the config file
-                    // while building web code
-                    configFile: './babel.actions.config.js',
+                    loader: 'ts',
+                    target: 'node<%= nodeMajor %>',
                 },
             },
         ],

package/src/generators/app/files/commerce-backend-ui/src/commerce-backend-ui-1/web-src/tsconfig.json.template

@@ -1,6 +1,8 @@
 {
     "extends": "@aligent/ts-code-standards/tsconfigs-react",
     "compilerOptions": {
+        "module": "Preserve",
+        "moduleResolution": "Bundler",
         "allowImportingTsExtensions": true,
         "resolveJsonModule": true,
         "baseUrl": "../../..",

package/src/generators/app/lib/compose-package-json.js

@@ -1,62 +1,26 @@
 "use strict";
-var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
-    if (k2 === undefined) k2 = k;
-    var desc = Object.getOwnPropertyDescriptor(m, k);
-    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
-      desc = { enumerable: true, get: function() { return m[k]; } };
-    }
-    Object.defineProperty(o, k2, desc);
-}) : (function(o, m, k, k2) {
-    if (k2 === undefined) k2 = k;
-    o[k2] = m[k];
-}));
-var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
-    Object.defineProperty(o, "default", { enumerable: true, value: v });
-}) : function(o, v) {
-    o["default"] = v;
-});
-var __importStar = (this && this.__importStar) || (function () {
-    var ownKeys = function(o) {
-        ownKeys = Object.getOwnPropertyNames || function (o) {
-            var ar = [];
-            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
-            return ar;
-        };
-        return ownKeys(o);
-    };
-    return function (mod) {
-        if (mod && mod.__esModule) return mod;
-        var result = {};
-        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
-        __setModuleDefault(result, mod);
-        return result;
-    };
-})();
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.writePackageJson = writePackageJson;
-const devkit_1 = require("@nx/devkit");
-const path = __importStar(require("path"));
-const TEMPLATE = (0, devkit_1.readJsonFile)(path.join(__dirname, 'template-package', 'package.json'));
-function pickVersions(source, names) {
-    const result = {};
-    for (const name of names) {
-        const version = source?.[name];
-        if (version === undefined) {
-            throw new Error(`Missing "${name}" in template-package.json`);
-        }
-        result[name] = version;
-    }
-    return result;
-}
-const BASE_DEPS = pickVersions(TEMPLATE.dependencies, [
+const template_package_1 = require("../../helpers/template-package");
+/**
+ * Builds the new app's package.json based on selected flags.
+ *
+ * Versions are sourced from `template-package/package.json` (a real package.json
+ * that Dependabot watches) — bumping a dependency there flows into every app
+ * scaffolded thereafter without code changes. The manifest lives in its own
+ * directory because Dependabot's npm ecosystem only discovers files named
+ * exactly `package.json`.
+ */
+const TEMPLATE = (0, template_package_1.loadTemplatePackage)(__dirname);
+const BASE_DEPS = (0, template_package_1.pickVersions)(TEMPLATE.dependencies, [
     '@adobe/aio-sdk',
     '@adobe/aio-lib-telemetry',
 ]);
-const COMMERCE_DEPS = pickVersions(TEMPLATE.dependencies, [
+const COMMERCE_DEPS = (0, template_package_1.pickVersions)(TEMPLATE.dependencies, [
     '@adobe/aio-commerce-lib-app',
     '@adobe/aio-commerce-lib-config',
 ]);
-const ADMIN_UI_DEPS = pickVersions(TEMPLATE.dependencies, [
+const ADMIN_UI_DEPS = (0, template_package_1.pickVersions)(TEMPLATE.dependencies, [
     '@adobe/uix-guest',
     '@adobe/exc-app',
     '@adobe/react-spectrum',
@@ -64,18 +28,23 @@ const ADMIN_UI_DEPS = pickVersions(TEMPLATE.dependencies, [
     'react-dom',
     'react-router',
 ]);
-const BASE_DEV_DEPS = pickVersions(TEMPLATE.devDependencies, [
+const BASE_DEV_DEPS = (0, template_package_1.pickVersions)(TEMPLATE.devDependencies, [
     '@aligent/ts-code-standards',
-    '@babel/preset-env',
-    '@babel/preset-typescript',
     '@types/node',
-    'babel-loader',
+    'esbuild-loader',
+    // `eslint` is also pinned at the workspace root; declaring it here keeps
+    // the app's `lint` script resolvable independent of npm workspace hoisting.
+    'eslint',
+    // `prettier` is required as a peer dep of `eslint-plugin-prettier`, which
+    // is wired in via `@aligent/ts-code-standards`. Without an explicit
+    // declaration the lint run can hang in the dynamic-import fallback path.
+    'prettier',
     'ts-loader',
     'type-fest',
     'typescript',
     'vitest',
 ]);
-const ADMIN_UI_DEV_DEPS = pickVersions(TEMPLATE.devDependencies, [
+const ADMIN_UI_DEV_DEPS = (0, template_package_1.pickVersions)(TEMPLATE.devDependencies, [
     '@types/react',
     '@types/react-dom',
 ]);

package/src/generators/app/lib/template-package/package.json

@@ -17,12 +17,12 @@
   },
   "devDependencies": {
     "@aligent/ts-code-standards": "^4.2.0",
-    "@babel/preset-env": "^7.26.9",
-    "@babel/preset-typescript": "^7.27.0",
     "@types/node": "^22.14.0",
     "@types/react": "^19.1.0",
     "@types/react-dom": "^19.1.2",
-    "babel-loader": "^10.0.0",
+    "esbuild-loader": "^4.3.0",
+    "eslint": "^9.0.0",
+    "prettier": "^3.8.1",
     "ts-loader": "^9.5.2",
     "type-fest": "^4.39.1",
     "typescript": "^5.8.3",

package/src/generators/helpers/template-package.d.ts

@@ -0,0 +1,20 @@
+export interface TemplatePackageJson {
+    dependencies?: Record<string, string>;
+    devDependencies?: Record<string, string>;
+}
+/**
+ * Read a generator's `template-package/package.json`. Each generator keeps its
+ * version pins in a real package.json (rather than hard-coding versions in TS)
+ * so Dependabot can track and bump them via PR.
+ *
+ * `generatorDir` is the directory containing the generator's compiled code —
+ * pass `__dirname` from the caller. The template lives at
+ * `<generatorDir>/template-package/package.json`.
+ */
+export declare function loadTemplatePackage(generatorDir: string): TemplatePackageJson;
+/**
+ * Extract the requested entries from a dependency map, preserving the version
+ * spec. Throws if any requested name is missing — keeps the template-package
+ * file as the single source of truth and surfaces drift loudly.
+ */
+export declare function pickVersions(source: Record<string, string> | undefined, names: readonly string[]): Record<string, string>;

package/src/generators/helpers/template-package.js

@@ -0,0 +1,33 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.loadTemplatePackage = loadTemplatePackage;
+exports.pickVersions = pickVersions;
+const devkit_1 = require("@nx/devkit");
+/**
+ * Read a generator's `template-package/package.json`. Each generator keeps its
+ * version pins in a real package.json (rather than hard-coding versions in TS)
+ * so Dependabot can track and bump them via PR.
+ *
+ * `generatorDir` is the directory containing the generator's compiled code —
+ * pass `__dirname` from the caller. The template lives at
+ * `<generatorDir>/template-package/package.json`.
+ */
+function loadTemplatePackage(generatorDir) {
+    return (0, devkit_1.readJsonFile)(`${generatorDir}/template-package/package.json`);
+}
+/**
+ * Extract the requested entries from a dependency map, preserving the version
+ * spec. Throws if any requested name is missing — keeps the template-package
+ * file as the single source of truth and surfaces drift loudly.
+ */
+function pickVersions(source, names) {
+    const result = {};
+    for (const name of names) {
+        const version = source?.[name];
+        if (version === undefined) {
+            throw new Error(`Missing "${name}" in template-package.json`);
+        }
+        result[name] = version;
+    }
+    return result;
+}

package/src/generators/preset/preset.js

@@ -36,8 +36,21 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.default = presetGenerator;
 const devkit_1 = require("@nx/devkit");
 const path = __importStar(require("path"));
+const template_package_1 = require("../helpers/template-package");
 const nx_json_1 = require("./nx-json");
 const DEFAULT_NODE_VERSION = '24.0.1';
+const TEMPLATE = (0, template_package_1.loadTemplatePackage)(__dirname);
+const WORKSPACE_DEV_DEPS = (0, template_package_1.pickVersions)(TEMPLATE.devDependencies, [
+    '@aligent/ts-code-standards',
+    '@nx/eslint',
+    '@nx/js',
+    '@nx/vitest',
+    'eslint',
+    'nx',
+    'prettier',
+    'typescript',
+    'vitest',
+]);
 /**
  * Preset generator invoked by `create-nx-workspace --preset=@aligent/nx-appbuilder`.
  *
@@ -65,6 +78,20 @@ async function presetGenerator(tree, options) {
  * devDependencies so the lockfile written by create-nx-workspace stays in sync
  * with what the preset declares — otherwise npm fails the post-preset install
  * with an arborist "must provide string spec" error.
+ *
+ * Most devDependency versions are sourced from `template-package/package.json`
+ * (a real package.json that Dependabot watches). The self-version of
+ * `@aligent/nx-appbuilder` is read from the generator's own package.json since
+ * Dependabot can't track that.
+ *
+ * Notes on why each dep is pinned at the workspace root:
+ * - `@aligent/ts-code-standards` is resolved by the workspace tsconfig's
+ *   `extends` line and by every generated app's tsconfig chain.
+ * - The `@nx/*` plugin packages need to be installed at the workspace root so
+ *   the plugins declared in nx.json can load.
+ * - `eslint` and `prettier` are also declared at the app level (so each app is
+ *   self-sufficient), but pinning here ensures npm workspaces hoists a single
+ *   shared version.
  */
 function buildWorkspacePackageJson(name, nodeVersion) {
     const major = nodeVersion.split('.')[0];
@@ -85,24 +112,15 @@ function buildWorkspacePackageJson(name, nodeVersion) {
             'build:all': 'nx run-many -t build',
         },
         workspaces: [],
-        devDependencies: {
+        devDependencies: sortObject({
             '@aligent/nx-appbuilder': getGeneratorVersion(),
-            // Resolved by the workspace's tsconfig.json's `extends` line and
-            // by every generated app's tsconfig chain. Pinned at the workspace
-            // root so all apps share one resolution.
-            '@aligent/ts-code-standards': '^4.2.0',
-            // The @nx plugin packages need to be installed at the workspace
-            // root so the plugins declared in nx.json can actually load.
-            '@nx/eslint': '^22.4.5',
-            '@nx/js': '^22.4.5',
-            '@nx/vitest': '^22.4.5',
-            eslint: '^9.0.0',
-            nx: '^22.4.5',
-            typescript: '^5.8.3',
-            vitest: '^2.1.8',
-        },
+            ...WORKSPACE_DEV_DEPS,
+        }),
     };
 }
+function sortObject(obj) {
+    return Object.fromEntries(Object.entries(obj).sort(([a], [b]) => a.localeCompare(b)));
+}
 function getGeneratorVersion() {
     const packagePath = path.join(__dirname, '../../../package.json');
     const packageJson = (0, devkit_1.readJsonFile)(packagePath);

package/src/generators/preset/template-package/package.json

@@ -0,0 +1,17 @@
+{
+  "name": "@aligent/nx-appbuilder-generated-workspace-deps",
+  "version": "0.0.0",
+  "private": true,
+  "description": "Version pins for the deps that the preset generator injects into a generated workspace's package.json. Tracked by Dependabot so version bumps land via PR; consumed at runtime by preset.ts.",
+  "devDependencies": {
+    "@aligent/ts-code-standards": "^4.2.0",
+    "@nx/eslint": "^22.4.5",
+    "@nx/js": "^22.4.5",
+    "@nx/vitest": "^22.4.5",
+    "eslint": "^9.0.0",
+    "nx": "^22.4.5",
+    "prettier": "^3.8.1",
+    "typescript": "^5.8.3",
+    "vitest": "^2.1.8"
+  }
+}

package/src/generators/app/files/base/babel.actions.config.js.template

@@ -1,6 +0,0 @@
-// Babel configuration allowing compilation of typescript files in both
-// test and src/action folders
-module.exports = {
-    presets: [['@babel/preset-env', { targets: { node: 'current' } }], '@babel/preset-typescript'],
-    ignore: ['**/src/web/**', '**/node_modules/**'],
-};