feat: introduce BuildParams ext (webiny#4904)

Co-authored-by: Copilot <198982749+Copilot@users.noreply.github.com>
Co-authored-by: adrians5j <5121148+adrians5j@users.noreply.github.com>

Author: adrians5j

extensions/MyApiKeyAfterUpdate.ts

@@ -1,18 +1,32 @@
-import { ApiKeyAfterUpdateHandler } from "webiny/api/security/features/UpdateApiKey";
-
+import { ApiKeyAfterUpdateHandler } from "webiny/api/security/apiKey";
 import { Logger } from "webiny/api/logger";
+import { BuildParams } from "webiny/api/buildParams";
 
 class MyApiKeyAfterUpdateImpl implements ApiKeyAfterUpdateHandler.Interface {
-    constructor(private logger: Logger.Interface) {}
+    constructor(
+        private logger: Logger.Interface,
+        private buildParams: BuildParams.Interface
+    ) {}
 
     async handle() {
         this.logger.warn("An API key was updated!");
+
+        // Read build params
+        const param1 = this.buildParams.get<string>("MY_CUSTOM_BUILD_PARAM");
+        const param2 = this.buildParams.get<{ myKey: number; nested: { foo: string } }>(
+            "MY_CUSTOM_BUILD_PARAM-2"
+        );
+
+        console.log("---- Build Params ----");
+
+        console.log(`Build param 1: ${param1}`);
+        console.log(`Build param 2:`, param2);
     }
 }
 
 const MyApiKeyAfterUpdate = ApiKeyAfterUpdateHandler.createImplementation({
     implementation: MyApiKeyAfterUpdateImpl,
-    dependencies: [Logger]
+    dependencies: [Logger, BuildParams]
 });
 
 export default MyApiKeyAfterUpdate;

packages/api-core/package.json

@@ -75,6 +75,7 @@
     "minimatch": "^5.1.6",
     "pino": "^9.14.0",
     "pino-lambda": "^4.4.1",
+    "ts-morph": "^27.0.2",
     "zod": "^3.25.76"
   },
   "devDependencies": {

packages/api-core/src/ApiCoreFeature.ts

@@ -9,13 +9,15 @@ import { AdminUsersFeature } from "~/features/users/AdminUsersFeature.js";
 import type { ApiCoreStorageOperations } from "~/types/core.js";
 import { IdpAuthenticatorFeature } from "~/idp/feature.js";
 import { KeyValueStoreFeature } from "~/features/keyValueStore/feature.js";
+import { BuildParamsFeature } from "~/features/buildParams/feature.js";
 
 export const ApiCoreFeature = createFeature({
     name: "ApiCore",
     register(container: Container, config: ApiCoreStorageOperations) {
         // Register features
         LoggerFeature.register(container);
         EventPublisherFeature.register(container);
+        BuildParamsFeature.register(container);
         TenancyFeature.register(container, config.tenancyStorageOperations);
         SecurityFeature.register(container, config.securityStorageOperations);
         AdminUsersFeature.register(container, config.usersStorageOperations);

packages/api-core/src/exports/api/buildParams.ts

@@ -0,0 +1 @@
+export { BuildParam, BuildParams } from "~/features/buildParams/index.js";

packages/api-core/src/extensions/BuildParam.ts

@@ -0,0 +1,137 @@
+import { z } from "zod";
+import { Node, Project, ArrayLiteralExpression } from "ts-morph";
+import { defineExtension } from "@webiny/project/defineExtension";
+import crypto from "crypto";
+import path from "path";
+import fs from "fs";
+
+export const BuildParam = defineExtension({
+    type: "Api/BuildParam",
+    tags: { runtimeContext: "app-build", appName: "api" },
+    description: "Add build-time parameter to API app.",
+    multiple: true,
+    paramsSchema: () => {
+        return z.object({
+            paramName: z.string(),
+            value: z.union([
+                z.string(),
+                z.record(z.any()),
+                z.array(z.any()),
+                z.number(),
+                z.boolean()
+            ])
+        });
+    },
+    async build(params, ctx) {
+        const extensionsTsFilePath = ctx.project.paths.workspaceFolder
+            .join("apps", "api", "graphql", "src", "extensions.ts")
+            .toString();
+
+        const buildParamsDir = ctx.project.paths.workspaceFolder
+            .join("apps", "api", "graphql", "src", "buildParams")
+            .toString();
+
+        const { paramName, value } = params;
+
+        // Serialize value to a TypeScript literal.
+        const valueStr = JSON.stringify(value, null, 4);
+
+        // Generate a unique class name based on the paramName.
+        const hash = crypto.createHash("sha256").update(paramName).digest("hex");
+        const className = `BuildParam_${hash.slice(-10)}`;
+        const fileName = `${className}.ts`;
+        const filePath = path.join(buildParamsDir, fileName);
+
+        // Ensure buildParams directory exists.
+        if (!fs.existsSync(buildParamsDir)) {
+            fs.mkdirSync(buildParamsDir, { recursive: true });
+        }
+
+        // Check if file already exists.
+        if (fs.existsSync(filePath)) {
+            // File exists, just ensure it's imported in extensions.ts
+        } else {
+            // Create the BuildParam implementation file.
+            const fileContent = `import { BuildParam } from "webiny/api/buildParams";
+
+class ${className} implements BuildParam.Interface {
+    key = "${paramName}";
+    value = ${valueStr};
+}
+
+export default BuildParam.createImplementation({
+    implementation: ${className},
+    dependencies: []
+});
+`;
+            fs.writeFileSync(filePath, fileContent, "utf8");
+        }
+
+        // Now update extensions.ts to import and register this BuildParam.
+        const project = new Project();
+        project.addSourceFileAtPath(extensionsTsFilePath);
+
+        const source = project.getSourceFileOrThrow(extensionsTsFilePath);
+
+        // Calculate import path relative to extensions.ts.
+        let importPath = path
+            .relative(path.dirname(extensionsTsFilePath), filePath)
+            .replace(/\.tsx?$/, ".js");
+
+        // Ensure the path starts with ./
+        if (!importPath.startsWith(".")) {
+            importPath = "./" + importPath;
+        }
+
+        // Check if import already exists.
+        const existingImportDeclaration = source.getImportDeclaration(importPath);
+        if (existingImportDeclaration) {
+            return;
+        }
+
+        let index = 1;
+
+        const importDeclarations = source.getImportDeclarations();
+        if (importDeclarations.length) {
+            const last = importDeclarations[importDeclarations.length - 1];
+            index = last.getChildIndex() + 1;
+        }
+
+        // Add import for the BuildParam implementation.
+        source.insertImportDeclaration(index, {
+            defaultImport: className,
+            moduleSpecifier: importPath
+        });
+
+        // Add the registration to the plugins array.
+        const pluginsArray = source.getFirstDescendant(node =>
+            Node.isArrayLiteralExpression(node)
+        ) as ArrayLiteralExpression;
+
+        pluginsArray.addElement(
+            `\ncreateContextPlugin(ctx => {\n\tregisterExtension(ctx.container, ${className});\n})`
+        );
+
+        {
+            let index = 1;
+
+            const importDeclarations = source.getImportDeclarations();
+            if (importDeclarations.length) {
+                const last = importDeclarations[importDeclarations.length - 1];
+                index = last.getChildIndex() + 1;
+            }
+
+            const contextPluginImportPath = "@webiny/api/plugins/ContextPlugin";
+            const existingContextPluginImport =
+                source.getImportDeclaration(contextPluginImportPath);
+            if (!existingContextPluginImport) {
+                source.insertImportDeclaration(index, {
+                    namedImports: ["createContextPlugin"],
+                    moduleSpecifier: contextPluginImportPath
+                });
+            }
+        }
+
+        await source.save();
+    }
+});

packages/api-core/src/extensions/index.ts

@@ -38,9 +38,11 @@ import {
 
 // Generic extension that supports any API abstraction.
 import { GenericExtension } from "./GenericExtension.js";
+import { BuildParam } from "./BuildParam.js";
 
 // Exports.
 export { GenericExtension };
+export { BuildParam };
 export { ApiKeyBeforeCreate };
 export { ApiKeyAfterCreate };
 export { ApiKeyBeforeUpdate };
@@ -85,6 +87,7 @@ export { SystemInstalled };
 // Definitions (used internally). 👇
 export const definitions = [
     GenericExtension.def,
+    BuildParam.def,
     ApiKeyBeforeCreate.def,
     ApiKeyAfterCreate.def,
     ApiKeyBeforeUpdate.def,

packages/api-core/src/features/buildParams/BuildParams.ts

@@ -0,0 +1,15 @@
+import { BuildParam, BuildParams as BuildParamsAbstraction } from "./abstractions.js";
+
+export class BuildParamsImpl implements BuildParamsAbstraction.Interface {
+    constructor(private params: BuildParam.Interface[]) {}
+
+    get<T = any>(key: string): T | null {
+        const param = this.params.find(p => p.key === key);
+        return param ? param.value : null;
+    }
+}
+
+export const BuildParams = BuildParamsAbstraction.createImplementation({
+    implementation: BuildParamsImpl,
+    dependencies: [[BuildParam, { multiple: true }]]
+});

packages/api-core/src/features/buildParams/abstractions.ts

@@ -0,0 +1,22 @@
+import { createAbstraction } from "@webiny/feature/api";
+
+export interface IBuildParam {
+    key: string;
+    value: any;
+}
+
+export const BuildParam = createAbstraction<IBuildParam>("BuildParam");
+
+export namespace BuildParam {
+    export type Interface = IBuildParam;
+}
+
+export interface IBuildParams {
+    get<T = any>(key: string): T | null;
+}
+
+export const BuildParams = createAbstraction<IBuildParams>("BuildParams");
+
+export namespace BuildParams {
+    export type Interface = IBuildParams;
+}

packages/api-core/src/features/buildParams/feature.ts

@@ -0,0 +1,10 @@
+import { createFeature } from "@webiny/feature/api";
+import { Container } from "@webiny/di";
+import { BuildParams } from "./BuildParams.js";
+
+export const BuildParamsFeature = createFeature({
+    name: "BuildParamsFeature",
+    register(container: Container) {
+        container.register(BuildParams);
+    }
+});

packages/api-core/src/features/buildParams/index.ts

@@ -0,0 +1 @@
+export { BuildParam, BuildParams } from "./abstractions.js";