@aligent/nx-cdk 0.0.1

package/src/generators/preset/files/vitest.global.setup.mjs.template

@@ -0,0 +1,109 @@
+import { beforeAll } from 'vitest'
+
+beforeAll(() => {
+    expect.addSnapshotSerializer(
+        replaceProperties({ property: [
+            // Replace asset storage locations in Lambda function snapshots
+            'Code.S3Bucket',
+            'Code.S3Key',
+            // Replace asset storage locations in Step Function snapshots
+            'DefinitionS3Location.Bucket',
+            'DefinitionS3Location.Key'
+        ] })
+    );
+})
+
+const PLACEHOLDER = '[SNAPSHOT_PLACEHOLDER]';
+const isObject = (val) => !!val && typeof val === 'object';
+
+// Helper function to traverse object and find properties to replace
+const findPropertiesToReplace = (
+    obj,
+    property,
+    path = []
+) => {
+    const results = [];
+
+    for (const [key, value] of Object.entries(obj)) {
+        const currentPath = [...path, key];
+        const fullPath = currentPath.join('.');
+
+        let shouldReplace = false;
+
+        if (property instanceof RegExp) {
+            shouldReplace = property.test(fullPath);
+        } else if (Array.isArray(property)) {
+            shouldReplace = property.includes(fullPath);
+        } else {
+            shouldReplace = fullPath === property;
+        }
+
+        if (shouldReplace && value !== PLACEHOLDER) {
+            results.push({ path: currentPath, value });
+        }
+
+        if (isObject(value)) {
+            results.push(...findPropertiesToReplace(value, property, currentPath));
+        }
+    }
+
+    return results;
+};
+
+// Helper function to set value at nested path
+const setValueAtPath = (obj, path, value) => {
+    let current = obj;
+
+    for (let i = 0; i < path.length - 1; i++) {
+        const key = path[i];
+        if (!isObject(current[key])) {
+            current[key] = {};
+        }
+        current = current[key];
+    }
+
+    current[path[path.length - 1]] = value;
+};
+
+/**
+ * Custom serializer for vitest snapshot tests
+ * Allows replacing properties in a snapshot with placeholder values.
+ *
+ * Properties to replace can be specified as a string, array of strings, or a single regular expression
+ * Nested properties can be specified using dot notation.
+ *
+ * @example
+ * ```
+ * beforeAll(() => {
+ *     expect.addSnapshotSerializer(
+ *         // Will replace the value of Code: { S3Bucket: '...', S3Key: '...' } anywhere in the object structure
+ *         replaceProperties({ property: ['Code.S3Bucket', 'Code.S3Key'] })
+ *     );
+ * })
+ * ```
+ *
+ * @param {{ property: string | string[] | RegExp, placeholder?: string }} input
+ * @returns
+ */
+export const replaceProperties = ({
+    property,
+    placeholder = PLACEHOLDER,
+}) => {
+    return {
+        test(val) {
+            if (!isObject(val)) return false;
+            const propertiesToReplace = findPropertiesToReplace(val, property);
+            return propertiesToReplace.length > 0;
+        },
+        serialize(val, config, indentation, depth, refs, printer) {
+            const clone = { ...val };
+            const propertiesToReplace = findPropertiesToReplace(clone, property);
+
+            for (const { path } of propertiesToReplace) {
+                setValueAtPath(clone, path, placeholder);
+            }
+
+            return printer(clone, config, indentation, depth, refs);
+        },
+    }
+};

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

@@ -0,0 +1,4 @@
+import { Tree } from '@nx/devkit';
+import { PresetGeneratorSchema } from './schema';
+export declare function presetGenerator(tree: Tree, options: PresetGeneratorSchema): Promise<void>;
+export default presetGenerator;

package/src/generators/preset/preset.js

@@ -0,0 +1,35 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.presetGenerator = presetGenerator;
+const devkit_1 = require("@nx/devkit");
+const path_1 = require("path");
+const nxJson_1 = require("../helpers/configs/nxJson");
+const utilities_1 = require("../helpers/utilities");
+async function presetGenerator(tree, options) {
+    const { name, destination, nodeVersion } = options;
+    const [nodeVersionMajor] = nodeVersion.split('.');
+    const nameParts = (0, utilities_1.splitInputName)(name);
+    const projectName = nameParts.join(' ');
+    (0, devkit_1.generateFiles)(tree, (0, path_1.join)(__dirname, 'files'), '.', {
+        ...options,
+        projectName,
+        folderName: destination || name,
+        nodeRuntime: `Runtime.NODEJS_${nodeVersionMajor}_X`,
+        template: '',
+    });
+    (0, devkit_1.updateNxJson)(tree, { ...nxJson_1.NX_JSON });
+    const packageJson = (0, utilities_1.constructPackageJsonFile)({
+        name: options.name,
+        projectName,
+        version: (0, utilities_1.getGeneratorVersion)(),
+        nodeVersion,
+    });
+    (0, devkit_1.writeJson)(tree, 'package.json', packageJson);
+    // Generate application's tsconfigs
+    const { tsConfig, tsConfigLib, tsConfigSpec } = (0, utilities_1.constructProjectTsConfigFiles)('application');
+    (0, devkit_1.writeJson)(tree, 'application/tsconfig.json', tsConfig);
+    (0, devkit_1.writeJson)(tree, 'application/tsconfig.lib.json', tsConfigLib);
+    (0, devkit_1.writeJson)(tree, 'application/tsconfig.spec.json', tsConfigSpec);
+    await (0, devkit_1.formatFiles)(tree);
+}
+exports.default = presetGenerator;

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

@@ -0,0 +1,7 @@
+/* v8 ignore start */
+export interface PresetGeneratorSchema {
+    name: string;
+    nodeVersion: string;
+    // FIXME: [MI-281] Add this into schema.json once we move to our own cli tool
+    destination?: string;
+}

package/src/generators/preset/schema.json

@@ -0,0 +1,32 @@
+{
+    "$schema": "https://json-schema.org/schema",
+    "$id": "Preset",
+    "title": "",
+    "type": "object",
+    "properties": {
+        "name": {
+            "type": "string",
+            "description": "The name of the project/application",
+            "$default": {
+                "$source": "argv",
+                "index": 0
+            },
+            "x-prompt": "What is the name of the project?",
+            "pattern": "^[a-z0-9-]+$",
+            "patternErrorMessage": "Project name must contain only lowercase alphanumeric characters and dashes"
+        },
+        "nodeVersion": {
+            "type": "string",
+            "description": "The target Node.js version",
+            "$default": {
+                "$source": "argv",
+                "index": 1
+            },
+            "default": "24.11.0",
+            "x-prompt": "What is the target Node.js version the project?",
+            "pattern": "^[0-9]+\\.[0-9]+\\.[0-9]+$",
+            "patternErrorMessage": "Node.js version must be a valid semantic version (semver), e.g. 22.10.0 or 24.10.0"
+        }
+    },
+    "required": ["name"]
+}

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

@@ -0,0 +1,29 @@
+# <%= serviceName %>
+
+This is a CDK service generated using `@aligent/nx-cdk` for Nx.
+
+## Architecture
+
+<!-- Add your architecture documentation here -->
+
+# Technical Decisions
+
+<!-- Add your notes and technical decisions here -->
+
+## Development
+
+### Type Checking
+
+```bash
+npx nx check-types <%= name %>
+```
+
+### Testing
+
+```bash
+npx nx test <%= name %>
+```
+
+## Deployment
+
+This service is deployed as part of the CDK application. See the main README for deployment instructions.

package/src/generators/service/files/eslint.config.mjs.template

@@ -0,0 +1,20 @@
+import eslintPluginImport from 'eslint-plugin-import';
+import baseConfig from '../../eslint.config.mjs';
+
+export default [
+    ...baseConfig,
+    {
+        files: ['**/*.ts'],
+        plugins: { import: eslintPluginImport },
+        rules: {
+            'import/no-extraneous-dependencies': [
+                'warn',
+                {
+                    optionalDependencies: false,
+                    peerDependencies: false,
+                    packageDir: ['.', '..', '../..'],
+                },
+            ],
+        },
+    },
+];

package/src/generators/service/files/package.json.template

@@ -0,0 +1,32 @@
+{
+  "name": "<%= name %>",
+  "type": "module",
+  "main": "./src/index.ts",
+  "types": "./src/index.ts",
+  "exports": {
+    ".": {
+      "types": "./src/index.ts",
+      "import": "./src/index.ts",
+      "default": "./src/index.ts"
+    },
+    "./package.json": "./package.json"
+  },
+  "bundleDependencies": [
+    "clients"
+  ],
+  "nx": {
+    "targets": {
+      "build": {
+        "executor": "nx:run-commands",
+        "options": {
+          "command": "rolldown -c rolldown.config.mjs",
+          "color": true,
+          "cwd": "{projectRoot}"
+        }
+      }
+    },
+    "tags": [
+      "scope:services"
+    ]
+  }
+}

package/src/generators/service/files/rolldown.config.mjs.template

@@ -0,0 +1,3 @@
+import { defineLambdaConfig } from '../../rolldown.config.base.mjs';
+
+export default defineLambdaConfig('src/runtime/handlers');

package/src/generators/service/files/src/index.ts.template

@@ -0,0 +1,75 @@
+import { Stack, StackProps, Stage, Tags } from 'aws-cdk-lib';
+import { Code } from 'aws-cdk-lib/aws-lambda';
+import { Construct } from 'constructs';
+import path from 'node:path';
+
+/**
+* @important
+* Due to the immutable nature of CloudFormation,
+* CDK will generate new CloudFormation template and deploy if you change stack name
+*/
+export const <%= constant %> = {
+    NAME: '<%= name %>',
+    DESCRIPTION: '<%= name %> service description'
+} as const;
+
+type Id = typeof <%= constant %>.NAME | (string & {});
+interface Props extends StackProps {
+    description: string;
+}
+
+/**
+ * Entrypoint for the <%= name %> service
+ *
+ * Instantiate in a CDK Application Stage to deploy to AWS.
+ *
+ * Use 'resolve' helpers below when referencing lambda handlers, step function files etc.
+ */
+export class <%= stack %> extends Stack {
+    constructor(scope: Construct, id: Id, props?: Props) {
+        super(scope, id, props);
+
+        const STAGE = Stage.of(this)?.stageName;
+        if (!STAGE) {
+            throw new Error('This construct must be used within a CDK Stage');
+        }
+
+        Tags.of(this).add('SERVICE', id);
+    }
+}
+
+/**
+ * Resolves a path to infra assets relative to this stack
+ *
+ * @param assetPath - The path to the asset.
+ * @returns The resolved path.
+ */
+export function resolveAssetPath(assetPath: `${'infra/'}${string}`) {
+    return path.resolve(import.meta.dirname, assetPath);
+}
+
+/**
+ * Return an object with the default bundled code asset and
+ * handler property for use with the NodejsFunction construct.
+ *
+ * @example
+ * ```ts
+ * new NodejsFunction(this, 'FetchData', {
+ *     ...resolveLambdaHandler('runtime/handlers/fetch-data.ts'),
+ * });
+ * ```
+ *
+ * @param assetPath - The path to the typescript handler file.
+ * @returns The resolved bundled code path and handler name.
+ */
+export function resolveLambdaHandler(assetPath: `${'runtime/handlers/'}${string}${'.ts'}`) {
+    // Replace 'runtime/handlers/' with '..dist/' and remove the file extension
+    const bundledPath = assetPath.replace(
+        /^runtime\/handlers\/(?<path>.*)\.ts$/,
+        '../dist/$<path>'
+    );
+    return {
+        code: Code.fromAsset(path.resolve(import.meta.dirname, bundledPath)),
+        handler: 'index.handler',
+    };
+}

package/src/generators/service/files/vitest.config.mjs.template

@@ -0,0 +1,18 @@
+import { defineConfig, mergeConfig } from 'vitest/config';
+import { vitestBaseConfig } from '../../vitest.config.base.mjs';
+
+export default defineConfig(configEnv => {
+    return mergeConfig(
+        vitestBaseConfig(configEnv),
+        defineConfig({
+            cacheDir: '../../node_modules/.vite/<%= name %>',
+            test: {
+                env: {
+                    NODE_ENV: 'test',
+                    YOUR_ENV_VAR: 'environment-variable',
+                },
+                unstubEnvs: true,
+            },
+        })
+    );
+});

package/src/generators/service/generator.d.ts

@@ -0,0 +1,4 @@
+import { Tree } from '@nx/devkit';
+import { ServiceGeneratorSchema } from './schema';
+export declare function serviceGenerator(tree: Tree, options: ServiceGeneratorSchema): Promise<void>;
+export default serviceGenerator;

package/src/generators/service/generator.js

@@ -0,0 +1,43 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.serviceGenerator = serviceGenerator;
+const devkit_1 = require("@nx/devkit");
+const path_1 = require("path");
+const utilities_1 = require("../helpers/utilities");
+const SERVICES_FOLDER = 'services';
+function addTsConfigReference(tree, referencePath) {
+    (0, devkit_1.updateJson)(tree, 'tsconfig.json', json => {
+        json.references ??= [];
+        if (json.references.some((r) => r.path === referencePath)) {
+            throw new Error(`You already have a library using the import path "${referencePath}". Make sure to specify a unique one.`);
+        }
+        json.references.push({ path: referencePath });
+        return json;
+    });
+}
+async function serviceGenerator(tree, options) {
+    const projectRoot = `${SERVICES_FOLDER}/${options.name}`;
+    const nameParts = (0, utilities_1.splitInputName)(options.name);
+    const constant = nameParts.map(name => name.toUpperCase()).join('_');
+    const stack = `${nameParts.join('')}Stack`;
+    if (!tree.exists(SERVICES_FOLDER)) {
+        tree.write(`${SERVICES_FOLDER}/.gitkeep`, '');
+    }
+    (0, devkit_1.generateFiles)(tree, (0, path_1.join)(__dirname, 'files'), projectRoot, {
+        ...options,
+        serviceName: nameParts.join(' '),
+        constant,
+        stack,
+        template: '',
+    });
+    // Generate service's tsconfigs
+    const { tsConfig, tsConfigLib, tsConfigSpec } = (0, utilities_1.constructProjectTsConfigFiles)('service');
+    (0, devkit_1.writeJson)(tree, `${projectRoot}/tsconfig.json`, tsConfig);
+    (0, devkit_1.writeJson)(tree, `${projectRoot}/tsconfig.lib.json`, tsConfigLib);
+    (0, devkit_1.writeJson)(tree, `${projectRoot}/tsconfig.spec.json`, tsConfigSpec);
+    // Integrate the new service with the root application
+    addTsConfigReference(tree, `./${projectRoot}`);
+    (0, utilities_1.addServiceStackToMainApplication)(tree, { name: options.name, constant, stack }, 'application');
+    await (0, devkit_1.formatFiles)(tree);
+}
+exports.default = serviceGenerator;

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

@@ -0,0 +1,4 @@
+/* v8 ignore start */
+export interface ServiceGeneratorSchema {
+    name: string;
+}

package/src/generators/service/schema.json

@@ -0,0 +1,20 @@
+{
+    "$schema": "http://json-schema.org/schema",
+    "$id": "ServiceGenerator",
+    "title": "Nx Generator for bootstrapping Serverless Framework services",
+    "type": "object",
+    "properties": {
+        "name": {
+            "type": "string",
+            "description": "The name of the service",
+            "$default": {
+                "$source": "argv",
+                "index": 0
+            },
+            "x-prompt": "What is the name of the service?",
+            "pattern": "^(?!.*[Ss]tack|.*[Ss]ervice).*$",
+            "patternErrorMessage": "Service name cannot contain '[Ss]tack' or '[Ss]ervice'"
+        }
+    },
+    "required": ["name"]
+}

package/src/index.d.ts

@@ -0,0 +1,2 @@
+export * from './generators/preset/preset';
+export * from './generators/service/generator';

package/src/index.js

@@ -0,0 +1,19 @@
+"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 __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+/* v8 ignore next 2 */
+__exportStar(require("./generators/preset/preset"), exports);
+__exportStar(require("./generators/service/generator"), exports);