@aligent/nx-appbuilder 0.2.0

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

@@ -0,0 +1,164 @@
+"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, [
+    '@adobe/aio-sdk',
+    '@adobe/aio-lib-telemetry',
+]);
+const COMMERCE_DEPS = pickVersions(TEMPLATE.dependencies, [
+    '@adobe/aio-commerce-lib-app',
+    '@adobe/aio-commerce-lib-config',
+]);
+const ADMIN_UI_DEPS = pickVersions(TEMPLATE.dependencies, [
+    '@adobe/uix-guest',
+    '@adobe/exc-app',
+    '@adobe/react-spectrum',
+    'react',
+    'react-dom',
+    'react-router',
+]);
+const BASE_DEV_DEPS = pickVersions(TEMPLATE.devDependencies, [
+    '@aligent/ts-code-standards',
+    '@babel/preset-env',
+    '@babel/preset-typescript',
+    '@types/node',
+    'babel-loader',
+    'ts-loader',
+    'type-fest',
+    'typescript',
+    'vitest',
+]);
+const ADMIN_UI_DEV_DEPS = pickVersions(TEMPLATE.devDependencies, [
+    '@types/react',
+    '@types/react-dom',
+]);
+function writePackageJson(tree, options) {
+    const dependencies = { ...BASE_DEPS };
+    const devDependencies = { ...BASE_DEV_DEPS };
+    const usesCommerceLib = options.hasAdminUI || options.hasBusinessConfig || options.hasCommerceWebhooks;
+    if (usesCommerceLib) {
+        Object.assign(dependencies, COMMERCE_DEPS);
+    }
+    if (options.hasAdminUI) {
+        Object.assign(dependencies, ADMIN_UI_DEPS);
+        Object.assign(devDependencies, ADMIN_UI_DEV_DEPS);
+    }
+    // Inline tsc invocations rather than going through `npm run` so the
+    // scripts (and the nx target that wraps them) work the same under npm,
+    // yarn, pnpm, etc. — none of them need a specific package manager binary
+    // to be on PATH.
+    const TYPECHECK_ACTIONS = 'tsc --noEmit --project src/actions/tsconfig.json';
+    const TYPECHECK_TESTS = 'tsc --noEmit --project tests/tsconfig.json';
+    const TYPECHECK_WEB = 'tsc --noEmit --project src/commerce-backend-ui-1/web-src/tsconfig.json';
+    const scripts = {
+        lint: 'eslint .',
+        'lint:fix': 'eslint . --fix',
+        'check-types:actions': TYPECHECK_ACTIONS,
+        'check-types:tests': TYPECHECK_TESTS,
+        test: 'vitest run --passWithNoTests',
+    };
+    const checkTypeSteps = [TYPECHECK_ACTIONS];
+    if (options.hasAdminUI) {
+        scripts['check-types:web'] = TYPECHECK_WEB;
+        checkTypeSteps.push(TYPECHECK_WEB);
+    }
+    checkTypeSteps.push(TYPECHECK_TESTS);
+    scripts['check-types'] = checkTypeSteps.join(' && ');
+    const major = options.nodeVersion.split('.')[0];
+    const json = {
+        name: options.packageName,
+        version: '0.0.1',
+        description: options.description,
+        private: true,
+        type: 'commonjs',
+        scripts: orderScripts(scripts),
+        dependencies: sortObject(dependencies),
+        devDependencies: sortObject(devDependencies),
+        engines: { node: `>=${major}` },
+        nx: {
+            targets: {
+                'check-types': {
+                    executor: 'nx:run-commands',
+                    options: { command: scripts['check-types'], cwd: '{projectRoot}' },
+                },
+                deploy: {
+                    executor: 'nx:run-commands',
+                    options: { command: 'aio app deploy', cwd: '{projectRoot}' },
+                },
+            },
+        },
+    };
+    tree.write(`${options.appRoot}/package.json`, JSON.stringify(json, null, 4) + '\n');
+}
+function sortObject(obj) {
+    return Object.fromEntries(Object.entries(obj).sort(([a], [b]) => a.localeCompare(b)));
+}
+function orderScripts(scripts) {
+    const order = [
+        'lint',
+        'lint:fix',
+        'check-types',
+        'check-types:actions',
+        'check-types:web',
+        'check-types:tests',
+        'test',
+    ];
+    const ordered = {};
+    for (const key of order) {
+        const value = scripts[key];
+        if (value !== undefined)
+            ordered[key] = value;
+    }
+    for (const [key, value] of Object.entries(scripts)) {
+        if (!(key in ordered))
+            ordered[key] = value;
+    }
+    return ordered;
+}

package/src/generators/app/lib/normalize-options.d.ts

@@ -0,0 +1,3 @@
+import type { Tree } from '@nx/devkit';
+import type { AppGeneratorSchema, NormalizedSchema } from '../schema';
+export declare function normalizeOptions(tree: Tree, options: AppGeneratorSchema): NormalizedSchema;

package/src/generators/app/lib/normalize-options.js

@@ -0,0 +1,67 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.normalizeOptions = normalizeOptions;
+const SEMVER = /^v?(\d+\.\d+\.\d+)\s*$/m;
+const DEFAULT_NODE_VERSION = '24.0.1';
+const SIDEBAR_TITLES = {
+    catalog: 'Catalog Apps',
+    sales: 'Sales Apps',
+    customers: 'Customer Apps',
+    content: 'Content Apps',
+};
+function normalizeOptions(tree, options) {
+    // Name shape (kebab-case) is enforced by the schema's `pattern` field,
+    // which Nx validates before this function runs.
+    if (tree.exists(options.name)) {
+        throw new Error(`Path "${options.name}" already exists in the workspace.`);
+    }
+    const hasAdminUI = options.hasAdminUI ?? false;
+    const hasBusinessConfig = options.hasBusinessConfig ?? false;
+    const sidebarCategory = hasAdminUI
+        ? (options.sidebarCategory ?? 'none')
+        : 'none';
+    const displayName = options.displayName ?? toTitleCase(options.name);
+    const camel = toCamelCase(options.name);
+    return {
+        name: options.name,
+        description: options.description ?? '',
+        displayName,
+        hasAdminUI,
+        sidebarCategory,
+        hasBusinessConfig,
+        hasCommerceWebhooks: options.hasCommerceWebhooks ?? false,
+        hasEvents: options.hasEvents ?? false,
+        hasRestActions: options.hasRestActions ?? false,
+        hasScheduledActions: options.hasScheduledActions ?? false,
+        hasCustomInstallSteps: options.hasCustomInstallSteps ?? false,
+        appRoot: options.name,
+        packageName: `@aligent/${options.name}`,
+        runtimePackageName: camel,
+        appSlug: options.name.replace(/-/g, '_'),
+        extensionId: `${camel}Extension`,
+        sidebarCategoryTitle: sidebarCategory === 'none' ? '' : SIDEBAR_TITLES[sidebarCategory],
+        nodeVersion: readNodeVersion(tree),
+    };
+}
+/**
+ * Reads the workspace's `.nvmrc` and extracts the Node version. Falls back to
+ * a sensible default if the file is missing or doesn't contain a parseable
+ * semver — keeping the .nvmrc as the single source of truth without making
+ * the app generator brittle to non-AppBuilder workspaces.
+ */
+function readNodeVersion(tree) {
+    const raw = tree.read('.nvmrc', 'utf-8');
+    if (raw === null)
+        return DEFAULT_NODE_VERSION;
+    const match = SEMVER.exec(raw);
+    return match?.[1] ?? DEFAULT_NODE_VERSION;
+}
+function toCamelCase(input) {
+    return input.replace(/-([a-z0-9])/g, (_, c) => c.toUpperCase());
+}
+function toTitleCase(input) {
+    return input
+        .split('-')
+        .map(part => part.charAt(0).toUpperCase() + part.slice(1))
+        .join(' ');
+}

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

@@ -0,0 +1,31 @@
+{
+  "name": "@aligent/nx-appbuilder-generated-app-deps",
+  "version": "0.0.0",
+  "private": true,
+  "description": "Version pins for the deps that the app generator injects into a generated app's package.json. Tracked by Dependabot so version bumps land via PR; consumed at runtime by compose-package-json.ts.",
+  "dependencies": {
+    "@adobe/aio-sdk": "^6.0.0",
+    "@adobe/aio-lib-telemetry": "^1.1.3",
+    "@adobe/aio-commerce-lib-app": "^1.2.0",
+    "@adobe/aio-commerce-lib-config": "^1.1.0",
+    "@adobe/uix-guest": "^1.1.5",
+    "@adobe/exc-app": "^1.4.13",
+    "@adobe/react-spectrum": "^3.46.1",
+    "react": "^19.1.0",
+    "react-dom": "^19.1.0",
+    "react-router": "^7.13.0"
+  },
+  "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",
+    "ts-loader": "^9.5.2",
+    "type-fest": "^4.39.1",
+    "typescript": "^5.8.3",
+    "vitest": "^2.1.8"
+  }
+}

package/src/generators/app/lib/update-root-package.d.ts

@@ -0,0 +1,6 @@
+import type { Tree } from '@nx/devkit';
+import type { NormalizedSchema } from '../schema';
+/**
+ * Adds the new app to the root package.json's workspaces array.
+ */
+export declare function updateRootPackageJson(tree: Tree, options: NormalizedSchema): void;

package/src/generators/app/lib/update-root-package.js

@@ -0,0 +1,23 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.updateRootPackageJson = updateRootPackageJson;
+/**
+ * Adds the new app to the root package.json's workspaces array.
+ */
+function updateRootPackageJson(tree, options) {
+    const rootPath = 'package.json';
+    if (!tree.exists(rootPath)) {
+        throw new Error('No root package.json found — is this an Nx workspace?');
+    }
+    const raw = tree.read(rootPath, 'utf-8');
+    if (raw === null) {
+        throw new Error('Failed to read root package.json');
+    }
+    const json = JSON.parse(raw);
+    const workspaces = Array.isArray(json.workspaces) ? json.workspaces : [];
+    if (workspaces.includes(options.name))
+        return;
+    workspaces.push(options.name);
+    json.workspaces = workspaces;
+    tree.write(rootPath, JSON.stringify(json, null, 4) + '\n');
+}

package/src/generators/app/lib/update-root-tsconfig.d.ts

@@ -0,0 +1,8 @@
+import type { Tree } from '@nx/devkit';
+import type { NormalizedSchema } from '../schema';
+/**
+ * Adds the new app to the workspace tsconfig.json's references array. Skips
+ * silently when the workspace tsconfig.json is absent so existing workspaces
+ * scaffolded before this template was added aren't forced to migrate.
+ */
+export declare function addTsConfigReference(tree: Tree, options: NormalizedSchema): void;

package/src/generators/app/lib/update-root-tsconfig.js

@@ -0,0 +1,24 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.addTsConfigReference = addTsConfigReference;
+/**
+ * Adds the new app to the workspace tsconfig.json's references array. Skips
+ * silently when the workspace tsconfig.json is absent so existing workspaces
+ * scaffolded before this template was added aren't forced to migrate.
+ */
+function addTsConfigReference(tree, options) {
+    const rootPath = 'tsconfig.json';
+    if (!tree.exists(rootPath))
+        return;
+    const raw = tree.read(rootPath, 'utf-8');
+    if (raw === null)
+        return;
+    const json = JSON.parse(raw);
+    const references = Array.isArray(json.references) ? json.references : [];
+    const refPath = `./${options.name}`;
+    if (references.some(ref => ref.path === refPath))
+        return;
+    references.push({ path: refPath });
+    json.references = references;
+    tree.write(rootPath, JSON.stringify(json, null, 4) + '\n');
+}

package/src/generators/app/schema.d.ts

@@ -0,0 +1,32 @@
+export type SidebarCategory = 'catalog' | 'sales' | 'customers' | 'content' | 'none';
+
+export interface AppGeneratorSchema {
+    name: string;
+    description?: string;
+    displayName?: string;
+    hasAdminUI?: boolean;
+    sidebarCategory?: SidebarCategory;
+    hasBusinessConfig?: boolean;
+    hasCommerceWebhooks?: boolean;
+    hasEvents?: boolean;
+    hasRestActions?: boolean;
+    hasScheduledActions?: boolean;
+    hasCustomInstallSteps?: boolean;
+}
+
+export interface NormalizedSchema extends Required<AppGeneratorSchema> {
+    /** Path of the generated app relative to the workspace root, e.g. "my-app" */
+    appRoot: string;
+    /** Scoped npm package name, e.g. "@aligent/my-app" */
+    packageName: string;
+    /** lower-camel-case identifier for runtime manifest packages */
+    runtimePackageName: string;
+    /** snake_case slug used inside the registration menu item id (e.g. "my_app") */
+    appSlug: string;
+    /** camelCase identifier with "Extension" suffix used as the EXTENSION_ID constant */
+    extensionId: string;
+    /** Title-cased section title for the sidebar (e.g. "Content Apps") */
+    sidebarCategoryTitle: string;
+    /** Full Node.js version read from the workspace's .nvmrc, e.g. "24.0.1" */
+    nodeVersion: string;
+}

package/src/generators/app/schema.json

@@ -0,0 +1,73 @@
+{
+    "$schema": "http://json-schema.org/schema",
+    "$id": "AligentAppBuilderApp",
+    "title": "Adobe App Builder app",
+    "description": "Scaffolds a new Adobe App Builder app",
+    "type": "object",
+    "properties": {
+        "name": {
+            "type": "string",
+            "description": "App name (kebab-case, used as directory name and package name suffix)",
+            "$default": { "$source": "argv", "index": 0 },
+            "x-prompt": "What is the app name? (kebab-case, e.g. 'my-app')",
+            "pattern": "^[a-z][a-z0-9-]*$"
+        },
+        "description": {
+            "type": "string",
+            "description": "Short description of the app",
+            "x-prompt": "Short description of the app"
+        },
+        "displayName": {
+            "type": "string",
+            "description": "Human-readable display name (defaults to title-cased app name)"
+        },
+        "hasAdminUI": {
+            "type": "boolean",
+            "description": "Does the app need a Commerce admin UI (custom pages, sidebar menu items)?",
+            "default": false,
+            "x-prompt": "Will the app add an admin UI in Commerce (custom pages or menu items)?"
+        },
+        "sidebarCategory": {
+            "type": "string",
+            "description": "Commerce admin sidebar category for the menu item (only used when hasAdminUI=true). Prompted when hasAdminUI=true and the value isn't passed on the CLI.",
+            "enum": ["catalog", "sales", "customers", "content", "none"]
+        },
+        "hasBusinessConfig": {
+            "type": "boolean",
+            "description": "Does the app expose business configuration in the Commerce admin?",
+            "default": false,
+            "x-prompt": "Will the app store business configuration?"
+        },
+        "hasCommerceWebhooks": {
+            "type": "boolean",
+            "description": "Will the app receive Adobe Commerce webhooks? Implies the commerce lib (app management) is required.",
+            "default": false,
+            "x-prompt": "Will the app receive Adobe Commerce webhooks?"
+        },
+        "hasEvents": {
+            "type": "boolean",
+            "description": "Will the app subscribe to Adobe IO events?",
+            "default": false,
+            "x-prompt": "Will the app subscribe to Adobe IO events?"
+        },
+        "hasRestActions": {
+            "type": "boolean",
+            "description": "Will the app expose custom REST actions?",
+            "default": false,
+            "x-prompt": "Will the app expose custom REST actions?"
+        },
+        "hasScheduledActions": {
+            "type": "boolean",
+            "description": "Will the app run scheduled (cron-triggered) actions?",
+            "default": false,
+            "x-prompt": "Will the app run scheduled actions?"
+        },
+        "hasCustomInstallSteps": {
+            "type": "boolean",
+            "description": "Does the app need custom installation steps? (only relevant when commerce extensions are used)",
+            "default": false,
+            "x-prompt": "Does the app need custom installation steps?"
+        }
+    },
+    "required": ["name"]
+}

package/src/generators/preset/files/.gitignore.template

@@ -0,0 +1,30 @@
+# Dependencies
+node_modules/
+
+# Parcel
+.parcel-cache/
+
+# Nx
+.nx/installation
+.nx/cache
+.nx/workspace-data
+
+# Build outputs
+dist/
+
+# IDE
+.idea/
+.vscode/
+
+# OS
+.DS_Store
+
+# Logs
+*.log
+
+# Environment
+.env
+.env.local
+
+# Adobe AppBuilder
+.aio

package/src/generators/preset/files/.npmrc.template

@@ -0,0 +1,2 @@
+@aligent:registry=https://npm.corp.aligent.consulting/
+//npm.corp.aligent.consulting/:_authToken=${NPM_TOKEN}

package/src/generators/preset/files/.nvmrc.template

@@ -0,0 +1 @@
+v<%= nodeVersion %>

package/src/generators/preset/files/README.md.template

@@ -0,0 +1,38 @@
+# <%= name %>
+
+An Aligent Adobe App Builder monorepo, scaffolded with `@aligent/nx-appbuilder`.
+
+## Prerequisites
+
+This monorepo uses packages from the Aligent private npm registry at
+`https://npm.corp.aligent.consulting/`. Set `NPM_TOKEN` in your shell before
+installing dependencies:
+
+```bash
+export NPM_TOKEN=<your-token>
+```
+
+(Generate the token by signing in to the registry with your GitHub account.)
+
+Then install with whichever package manager you prefer — `npm install`,
+`yarn install`, or `pnpm install` all work.
+
+## Adding a new app
+
+```bash
+npx nx g @aligent/nx-appbuilder:app <app-name>
+```
+
+The generator will prompt for the app's shape (admin UI, business config,
+events, scheduled actions, etc.) and scaffold the appropriate files.
+
+## Day-to-day commands
+
+```bash
+npx nx affected -t lint           # lint affected projects
+npx nx run-many -t lint           # lint every project
+npx nx affected -t test           # test affected projects
+npx nx affected -t check-types    # type-check affected projects
+npx nx run <app>:deploy           # deploy a specific app via aio
+npx nx graph                      # visualise the project graph
+```

package/src/generators/preset/files/tsconfig.json.template

@@ -0,0 +1,6 @@
+{
+    "extends": "@aligent/ts-code-standards/tsconfigs-extend",
+    "compileOnSave": false,
+    "files": [],
+    "references": []
+}

package/src/generators/preset/nx-json.d.ts

@@ -0,0 +1,4 @@
+import type { NxJsonConfiguration } from '@nx/devkit';
+export declare const NX_JSON: NxJsonConfiguration & {
+    $schema: string;
+};

package/src/generators/preset/nx-json.js

@@ -0,0 +1,36 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.NX_JSON = void 0;
+exports.NX_JSON = {
+    $schema: './node_modules/nx/schemas/nx-schema.json',
+    defaultBase: 'origin/main',
+    installation: {
+        version: '22.4.5',
+    },
+    plugins: [
+        { plugin: '@nx/eslint/plugin', options: {} },
+        // App Builder apps drive their own multi-tsconfig type-checking via a
+        // `check-types` script (one tsc invocation per actions/web/tests
+        // subtree). The plugin's inferred `typecheck` target only runs against
+        // a single root tsconfig, so it's disabled here to avoid surfacing a
+        // useless target alongside our custom one.
+        { plugin: '@nx/js/typescript', options: { build: false, typecheck: false } },
+        { plugin: '@nx/vitest', options: {} },
+    ],
+    namedInputs: {
+        default: ['{projectRoot}/**/*', 'sharedGlobals'],
+        sharedGlobals: [],
+        production: [
+            'default',
+            '!{projectRoot}/**/*.spec.ts',
+            '!{projectRoot}/**/*.test.ts',
+            '!{projectRoot}/tests/**/*',
+        ],
+    },
+    targetDefaults: {
+        lint: { inputs: ['default'], cache: true },
+        'check-types': { inputs: ['default'], cache: true },
+        test: { inputs: ['default'], cache: true },
+        build: { inputs: ['production'], cache: true, dependsOn: ['^build'] },
+    },
+};

package/src/generators/preset/preset.d.ts

@@ -0,0 +1,13 @@
+import { type Tree } from '@nx/devkit';
+import type { PresetGeneratorSchema } from './schema';
+/**
+ * Preset generator invoked by `create-nx-workspace --preset=@aligent/nx-appbuilder`.
+ *
+ * Scaffolds the workspace shell — root package.json, nx.json, .npmrc, etc. —
+ * but does NOT scaffold any apps. Apps are added afterwards via the `app`
+ * generator (`npx nx g @aligent/nx-appbuilder:app <name>`).
+ *
+ * Name shape (kebab-case) and nodeVersion semver are enforced by the schema's
+ * `pattern` fields before this function runs.
+ */
+export default function presetGenerator(tree: Tree, options: PresetGeneratorSchema): Promise<void>;