Merge pull request #203 from aligent/feat/MI-251-nx-cdk-improvements

MI-251: Extract vite-plugin-handler and improve nx-cdk preset

Author: kai-nguyen-aligent

.nx/version-plans/version-plan-1782434440905.md

@@ -0,0 +1,6 @@
+---
+vite-plugin-handler: minor
+nx-cdk: minor
+---
+
+Extract Lambda handler bundling into a standalone Vite plugin (`@aligent/vite-plugin-handler`) and update the nx-cdk preset to use it instead of inline vite config.

CLAUDE.md

@@ -15,6 +15,7 @@ Aligent's TypeScript monorepo for microservice development utilities.
 | `packages/nx-appbuilder`         | Nx plugin with generators for Adobe App Builder apps          |
 | `packages/nx-cdk`                | Nx plugin with generators for AWS CDK projects                |
 | `packages/nx-openapi`            | Nx plugin with generators for OpenAPI client generation       |
+| `packages/vite-plugin-handler`   | Vite plugin for bundling Lambda handlers as ESM               |
 
 ## Commands
 
@@ -65,6 +66,7 @@ npx nx g @tools/generators:package
   ```
 
   Common mappings: `Core.Logger` → `@adobe/aio-lib-core-logging`, `Core.Config` → `@adobe/aio-lib-core-config`, `Events` → `@adobe/aio-lib-events`, `State` → `@adobe/aio-lib-state`, `Files` → `@adobe/aio-lib-files`. The generated app's `eslint.config.mjs` ships a `no-restricted-imports` rule that enforces this.
+
 - **Don't read `process.env` inside action handlers.** App Builder routes runtime configuration through OpenWhisk `params` (declared as `inputs:` in `app.config.yaml`); `process.env` is not reliably propagated between activations. The generated app's eslint config flags `process.env.*` reads under `src/**/actions/**`.
 
 ## Workflow

README.md

@@ -11,6 +11,7 @@ Aligent's monorepo for Microservice Development Utilities. For more details abou
 - [Nx App Builder](/packages/nx-appbuilder/README.md)
 - [Nx CDK](/packages/nx-cdk/README.md)
 - [Nx Openapi](/packages/nx-openapi/README.md)
+- [Vite Plugin Handler](/packages/vite-plugin-handler/README.md)
 
 # Development
 
@@ -48,6 +49,7 @@ microservice-development-utilities/
 │   ├── nx-appbuilder/          # Nx plugin with generators for Adobe App Builder apps
 │   ├── nx-cdk/                 # Nx plugin for CDK project generation
 │   ├── nx-openapi/             # Nx plugin for OpenAPI code generation
+│   ├── vite-plugin-handler/    # Vite plugin for bundling Lambda handlers
 └── package.json                # Root package configuration
 ```
 

package-lock.json

@@ -27,14 +27,14 @@
   },
   "devDependencies": {
     "@aligent/ts-code-standards": "^4.2.0",
-    "@nx/devkit": "22.7.5",
-    "@nx/eslint": "22.7.5",
-    "@nx/eslint-plugin": "22.7.5",
-    "@nx/js": "22.7.5",
-    "@nx/plugin": "22.7.5",
-    "@nx/rollup": "22.7.5",
-    "@nx/vitest": "22.7.5",
-    "@nx/web": "22.7.5",
+    "@nx/devkit": "22.7.6",
+    "@nx/eslint": "22.7.6",
+    "@nx/eslint-plugin": "22.7.6",
+    "@nx/js": "22.7.6",
+    "@nx/plugin": "22.7.6",
+    "@nx/rollup": "22.7.6",
+    "@nx/vitest": "22.7.6",
+    "@nx/web": "22.7.6",
     "@smithy/util-stream": "^3.2.1",
     "@swc-node/register": "1.11.1",
     "@swc/core": "1.15.41",
@@ -44,26 +44,26 @@
     "@vitest/coverage-v8": "4.1.8",
     "@vitest/ui": "4.1.8",
     "aws-sdk-client-mock": "^4.1.0",
-    "create-nx-workspace": "22.7.5",
+    "create-nx-workspace": "22.7.6",
     "eslint": "^9.39.0",
     "eslint-config-prettier": "10.1.8",
     "eslint-plugin-import": "^2.32.0",
     "jiti": "2.7.0",
     "jsonc-eslint-parser": "^2.4.1",
-    "nx": "22.7.5",
+    "nx": "22.7.6",
     "oauth-sign": "^0.9.0",
     "openapi-fetch": "0.17.0",
     "openapi-typescript-helpers": "0.1.0",
     "prettier": "^3.8.4",
     "prompts": "^2.4.2",
     "rollup": "^4.62.0",
-    "tslib": "^2.3.0",
-    "typedoc": "^0.28.14",
+    "tslib": "^2.8.1",
+    "typedoc": "^0.28.19",
     "typedoc-plugin-markdown": "^4.12.0",
     "typescript": "^5.9.3",
     "verdaccio": "6.7.2",
-    "vite": "7.3.1",
-    "vitest": "4.1.8",
+    "vite": "^8.0.14",
+    "vitest": "^4.1.7",
     "yargs": "^18.0.0"
   },
   "overrides": {

package.json

@@ -11,21 +11,22 @@
     "typecheck": "nx affected -t typecheck",
     "typecheck:all": "nx run-many -t typecheck",
     "audit": "nx run-many -t lint typecheck test --configuration coverage --skip-nx-cache",
-    "pg:synth": "nx run application:pg:synth --mode=development --profile playground",
-    "pg:deploy": "nx run application:pg:deploy --mode=development --method=direct --require-approval never --profile playground",
-    "pg:diff": "nx run application:pg:diff --mode=development --profile playground",
-    "pg:destroy": "nx run application:pg:destroy --mode=development --profile playground",
+    "pg:synth": "nx run application:cdk -- synth '**' --mode=development --profile playground",
+    "pg:deploy": "nx run application:cdk -- deploy '**' --mode=development --method=direct --require-approval never --profile playground",
+    "pg:diff": "nx run application:cdk -- diff '**' --mode=development --profile playground",
+    "pg:destroy": "nx run application:cdk -- destroy '**' --mode=development --profile playground",
     "postinstall": "[ -d .git ] && git config core.hooksPath '.git-hooks' && chmod +x .git-hooks/* || true"
   },
   "dependencies": {
-    "@aligent/microservice-util-lib": "^1.2.0"
+    "@aligent/microservice-util-lib": "^1.6.0"
   },
   "devDependencies": {
     "@aligent/cdk-aspects": "^0.6.3",
     "@aligent/cdk-nodejs-function-from-entry": "^0.2.3",
     "@aligent/cdk-step-function-from-file": "^0.5.3",
     "@aligent/nx-openapi": "^2.1.2",
     "@aligent/ts-code-standards": "^5.0.0",
+    "@aligent/vite-plugin-handler": "^0.1.0",
     "@nx/eslint": "22.7.3",
     "@nx/eslint-plugin": "22.7.3",
     "@nx/js": "22.7.3",
@@ -65,5 +66,5 @@
     "libs/*",
     "services/*"
   ],
-  "packageManager": "yarn@4.16.0+sha512.5374c94eb4ef6aa8188fb112f20c1aa6569f248d676c5e576e1fd2a1a4d8d87a96df65d9dfe1c2a0252cbe38bda46cf18d955005b81b43cc7607a5c9d56fd2b6"
+  "packageManager": "yarn@4.17.0+sha512.c2957de2f9025ab14d63b24d0d8be1f1655810e22c341042c27f7ecd017b180ec12db73d69ac366d71b304ef9f069349ce462de96f04f8f1da317f4f762c95ae"
 }

packages/nx-cdk/src/generators/helpers/configs/base-package/package.json

@@ -1,8 +1,10 @@
 import { NxJsonConfiguration } from '@nx/devkit';
 import { SERVICES_SCOPE } from '../../constants';
 
-export const NX_JSON: NxJsonConfiguration & { $schema: string } = {
+export const NX_JSON: NxJsonConfiguration = {
     $schema: './node_modules/nx/schemas/nx-schema.json',
+    neverConnectToCloud: true,
+    analytics: false,
     defaultBase: 'origin/staging',
     sync: { applyChanges: true },
     plugins: [
@@ -40,8 +42,5 @@ export const NX_JSON: NxJsonConfiguration & { $schema: string } = {
         cdk: {
             dependsOn: [{ target: 'build', params: 'forward', projects: `${SERVICES_SCOPE}/*` }],
         },
-        pg: {
-            dependsOn: [{ target: 'build', params: 'forward', projects: `${SERVICES_SCOPE}/*` }],
-        },
     },
 } as const;

packages/nx-cdk/src/generators/helpers/configs/nxJson.ts

@@ -20,67 +20,44 @@ This application manages the deployment of microservices and their shared infras
 
 ```bash
 # Synthesize for default environment/stage (dev)
-yarn pg:synth --args="dev/**"
+yarn pg:synth
 
 # Synthesize for a custom environment/stage
-yarn pg:synth --args="plg/** -c environment=plg"
+yarn pg:synth -c environment=plg
 ```
 
 ##### Deploy
 
 ```bash
 # Deploy for default environment/stage (dev)
-yarn pg:deploy --args="dev/**"
+yarn pg:deploy
 
 # Deploy to a custom environment/stage
-yarn pg:deploy --args="plg/** -c environment=plg"
+yarn pg:deploy -c environment=plg
 ```
 
 ##### Diff
 
 ```bash
 # Diff checking for default environment/stage (dev)
-yarn pg:diff --args="dev/**"
+yarn pg:diff
 
 # Diff checking for a custom environment/stage
-yarn pg:diff --args="plg/** -c environment=plg"
+yarn pg:diff -c environment=plg
 ```
 
 ##### Destroy
 
 ```bash
 # Destroy default environment/stage (dev)
-yarn pg:destroy --args="dev/**"
+yarn pg:destroy
 
 # Destroy a custom environment/stage
-yarn pg:destroy --args="plg/** -c environment=plg"
+yarn pg:destroy -c environment=plg
 ```
 
 ### Direct Nx Commands
 
 ```bash
-yarn nx run application:cdk <command> <args>
-```
-
-## Testing
-
-### Mock Services
-
-The application may include mock services for testing integrations without external dependencies.
-
-<!-- list mock services here -->
-
-Change the value of the `/application/dev/url` SSM Parameter to switch between real and mock endpoints
-
-### Local Development
-
-```bash
-# Type checking
-yarn typecheck
-
-# Testing
-yarn test
-
-# Linting
-yarn lint
+yarn nx run application:cdk -- <command> <args>
 ```

packages/nx-cdk/src/generators/preset/files/application/README.md.template

@@ -16,27 +16,6 @@
           "command": "cdk",
           "cwd": "{projectRoot}"
         }
-      },
-      "pg": {
-        "executor": "nx:run-commands",
-        "configurations": {
-          "synth": {
-            "command": "cdk synth"
-          },
-          "deploy": {
-            "command": "cdk deploy"
-          },
-          "diff": {
-            "command": "cdk diff"
-          },
-          "destroy": {
-            "command": "cdk destroy"
-          }
-        },
-        "options": {
-          "color": true,
-          "cwd": "{projectRoot}"
-        }
       }
     }
   }

packages/nx-cdk/src/generators/preset/files/application/package.json.template

@@ -1,6 +1,4 @@
-import { globSync } from 'node:fs';
-import { builtinModules } from 'node:module';
-import { extname, resolve } from 'node:path';
+import { resolve } from 'node:path';
 import { defineConfig } from 'vite';
 
 export const baseConfig = defineConfig(() => {
@@ -38,69 +36,3 @@ export const baseConfig = defineConfig(() => {
         },
     };
 });
-
-// ESM doesn't define __dirname/__filename. This shim ensures bundled CJS dependencies
-// that reference them won't throw a ReferenceError at runtime.
-// TODO: [MI-251] Support shims only when needed instead consider looking at tsup, tsdown and rollup shims plugins
-const shimBanner = `import { fileURLToPath as __shim_fileURLToPath } from 'node:url';
-import { dirname as __shim_dirname } from 'node:path';
-const __filename = __shim_fileURLToPath(import.meta.url);
-const __dirname = __shim_dirname(__filename);`;
-
-/**
- * Creates Vite environments for bundling Lambda handlers using the Vite Environment API.
- * Each handler file gets its own environment that outputs to dist/<entryName>/index.mjs.
- *
- * This uses Vite's built-in `mode` to control build behaviour.
- * See https://vite.dev/guide/env-and-mode
- */
-export function defineLambdaEnvironments(subPath, options = {}, envPrefix = 'lambda') {
-    // When running vitest, skip the Lambda environments entirely
-    if (process.env.VITEST === 'true') return {};
-
-    if (subPath.includes('..')) throw new Error('Invalid path provided');
-
-    const handlersPath = resolve(process.cwd(), subPath);
-    const handlers = globSync(`${handlersPath}/**/*.ts`);
-
-    const environments = {};
-    for (const handler of handlers) {
-        const bundledPath = handler.replace(`${handlersPath}/`, '');
-        const entryName = bundledPath.replace(extname(bundledPath), '');
-        const envName = `${envPrefix}_${entryName.replace(/[\\/]/g, '_')}`;
-
-        environments[envName] = {
-            resolve: { noExternal: true },
-            build: {
-                outDir: `dist/${entryName}`,
-                minify: options.mode === 'development' ? 'oxc' : false,
-                sourcemap: options.mode !== 'production',
-                platform: 'node',
-                rollupOptions: {
-                    input: { index: handler },
-                    moduleTypes: { ...options.moduleTypes },
-                    external: [...builtinModules, ...builtinModules.map(m => `node:${m}`)],
-                    output: {
-                        entryFileNames: 'index.mjs',
-                        format: 'esm',
-                        comments: { legal: false },
-                        codeSplitting: false,
-                        banner: shimBanner,
-                    },
-                },
-            },
-        };
-    }
-
-    return {
-        environments,
-        builder: {
-            buildApp: async builder => {
-                const lambdaEnvs = Object.entries(builder.environments)
-                    .filter(([name]) => name.startsWith(`${envPrefix}_`))
-                    .map(([, env]) => env);
-                await Promise.all(lambdaEnvs.map(env => builder.build(env)));
-            },
-        },
-    };
-}