@akanjs/devkit 3.0.0-alpha.64 → 3.0.0-alpha.66

package/akanConfig/akanConfig.test.ts

@@ -64,7 +64,7 @@ describe("AkanAppConfig", () => {
     expect(config.barrelImports).toEqual(
       expect.arrayContaining(["@apps/portal/ui", "@libs/shared/server", "akanjs/common", "akanjs/server"]),
     );
-    expect(config.docker.content).toContain("ENV AKAN_PUBLIC_APP_NAME=portal");
+    expect(config.dockerfile).toContain("ENV AKAN_PUBLIC_APP_NAME=portal");
     expect(process.env.AKAN_PUBLIC_DEFAULT_LOCALE).toBe("en");
   });
 
@@ -128,9 +128,67 @@ describe("AkanAppConfig", () => {
     });
     expect(config.publicEnv).toEqual(["AKAN_PUBLIC_FEATURE"]);
     expect(config.optimizeImports).toContain("custom-icons");
-    expect(config.docker.content).toContain('CMD ["bun","server.js"]');
-    expect(config.docker.content).toContain("FROM oven/bun:amd64 AS amd64");
-    expect(config.docker.content).toContain('RUN if [ "$TARGETARCH" = "arm64"');
+    expect(config.dockerfile).toContain('CMD ["bun","server.js"]');
+    expect(config.dockerfile).toContain("FROM oven/bun:amd64 AS amd64");
+    expect(config.dockerfile).toContain('RUN if [ "$TARGETARCH" = "arm64"');
+  });
+
+  test("defaults both web surfaces on and keeps the image free of web env overrides", () => {
+    const config = new AkanAppConfig(app, [], packageJson, {}, baseDevEnv);
+
+    expect(config.web).toEqual({ ssr: true, csr: true });
+    expect(config.dockerfile).not.toContain("AKAN_SSR");
+    expect(config.dockerfile).not.toContain("AKAN_CSR");
+  });
+
+  test("bakes the disabled surface into the image env so the default matches what was built", () => {
+    const ssrOnly = new AkanAppConfig(app, [], packageJson, { web: { csr: false } }, baseDevEnv);
+    expect(ssrOnly.web).toEqual({ ssr: true, csr: false });
+    expect(ssrOnly.dockerfile).toContain("ENV AKAN_CSR=false");
+    expect(ssrOnly.dockerfile).not.toContain("ENV AKAN_SSR=false");
+
+    const apiOnly = new AkanAppConfig(app, [], packageJson, { web: false }, baseDevEnv);
+    expect(apiOnly.web).toEqual({ ssr: false, csr: false });
+    expect(apiOnly.dockerfile).toContain("ENV AKAN_SSR=false");
+    expect(apiOnly.dockerfile).toContain("ENV AKAN_CSR=false");
+
+    expect(new AkanAppConfig(app, [], packageJson, { web: true }, baseDevEnv).web).toEqual({ ssr: true, csr: true });
+  });
+
+  test("refuses a csr-less build that ships a mobile app", () => {
+    expect(
+      () => new AkanAppConfig(app, [], packageJson, { web: { csr: false }, mobile: { appName: "portal" } }, baseDevEnv),
+    ).toThrow("the Capacitor build ships that bundle");
+  });
+
+  test("installs only ca-certificates and tzdata in the default image", () => {
+    const config = new AkanAppConfig(app, [], packageJson, {}, baseDevEnv);
+
+    expect(config.dockerfile).toContain(
+      "RUN apt-get update && apt-get upgrade -y && apt-get install -y --no-install-recommends ca-certificates tzdata && rm -rf /var/lib/apt/lists/*",
+    );
+    // The Chromium/ffmpeg toolchain moved to per-app `preRuns`; keeping it here paid for it in every image.
+    for (const dropped of ["libnss3", "ffmpeg", "build-essential", "redis", "xdg-utils"])
+      expect(config.dockerfile).not.toContain(dropped);
+  });
+
+  test("keeps a declared Dockerfile string verbatim", () => {
+    const dockerfile = "FROM oven/bun:1-slim\nCOPY . .\nCMD [\"bun\",\"main.js\"]";
+    const config = new AkanAppConfig(app, [], packageJson, { docker: dockerfile }, baseDevEnv);
+
+    expect(config.docker).toBe(dockerfile);
+    expect(config.dockerfile).toBe(dockerfile);
+  });
+
+  test("resolves the image parts, defaulting the base image and the command", () => {
+    const config = new AkanAppConfig(app, [], packageJson, { docker: { preRuns: ["echo hi"] } }, baseDevEnv);
+
+    expect(config.docker).toEqual({
+      image: "oven/bun:1-slim",
+      preRuns: ["echo hi"],
+      postRuns: [],
+      command: ["bun", "main.js"],
+    });
   });
 
   test("creates production package json and reports missing external versions", () => {
@@ -396,7 +454,7 @@ describe("AkanAppConfig lib externalLibs", () => {
       { externalLibs: ["@external/runtime"] },
       baseDevEnv,
       [],
-      ["@external/runtime", "puppeteer"],
+      { externalLibs: ["@external/runtime", "puppeteer"], docker: { preRuns: [], postRuns: [] } },
     );
 
     expect(config.externalLibs).toEqual(["@external/runtime", "puppeteer"]);
@@ -429,6 +487,70 @@ describe("AkanAppConfig lib externalLibs", () => {
   });
 });
 
+
+describe("AkanAppConfig lib docker runs", () => {
+  const libDocker = (preRuns: string[], postRuns: string[] = []) => ({
+    externalLibs: [],
+    docker: { preRuns, postRuns },
+  });
+
+  test("runs lib steps before the app's own, deduped", () => {
+    const config = new AkanAppConfig(
+      app,
+      ["shared"],
+      packageJson,
+      { docker: { preRuns: ["apt-get install -y ffmpeg", "echo app"], postRuns: ["echo app-post"] } },
+      baseDevEnv,
+      [],
+      libDocker(["apt-get install -y ffmpeg", "echo lib"], ["echo lib-post"]),
+    );
+
+    expect(config.docker).toMatchObject({
+      preRuns: ["apt-get install -y ffmpeg", "echo lib", "echo app"],
+      postRuns: ["echo lib-post", "echo app-post"],
+    });
+    expect(config.dockerfile).toContain("RUN echo lib\nRUN echo app\n");
+    expect(config.dockerfile.match(/RUN apt-get install -y ffmpeg/g)).toHaveLength(1);
+  });
+
+  test("drops them when the app hands over a whole Dockerfile", () => {
+    const config = new AkanAppConfig(
+      app,
+      ["shared"],
+      packageJson,
+      { docker: "FROM scratch" },
+      baseDevEnv,
+      [],
+      libDocker(["echo lib"]),
+    );
+
+    expect(config.dockerfile).toBe("FROM scratch");
+  });
+
+  test("reads them off every workspace lib config on load", async () => {
+    const root = fs.mkdtempSync(path.join(os.tmpdir(), "akan-config-libdocker-"));
+    try {
+      fs.mkdirSync(path.join(root, "apps/extapp"), { recursive: true });
+      fs.mkdirSync(path.join(root, "libs/extlib"), { recursive: true });
+      fs.writeFileSync(path.join(root, "apps/extapp/akan.config.ts"), "export default {};\n");
+      fs.writeFileSync(
+        path.join(root, "libs/extlib/akan.config.ts"),
+        "export default { docker: { preRuns: ['echo from-lib'], postRuns: [{ arm64: 'echo arm-only' }] } };\n",
+      );
+      fs.writeFileSync(path.join(root, "package.json"), JSON.stringify({ name: "extrepo", version: "1.0.0" }));
+      fs.writeFileSync(path.join(root, ".env"), "AKAN_PUBLIC_REPO_NAME=extrepo\nAKAN_PUBLIC_SERVE_DOMAIN=ext.test\n");
+
+      const workspace = WorkspaceExecutor.fromRoot({ workspaceRoot: root, repoName: "extrepo" });
+      const config = await AppExecutor.from(workspace, "extapp").getConfig();
+
+      expect(config.dockerfile).toContain("RUN echo from-lib");
+      expect(config.dockerfile).toContain('RUN if [ "$TARGETARCH" = "arm64"');
+    } finally {
+      fs.rmSync(root, { recursive: true, force: true });
+    }
+  });
+});
+
 describe("AkanLibConfig", () => {
   test("uses empty external libs by default and preserves explicit libs", () => {
     const lib = { name: "shared" } as never;
@@ -439,6 +561,15 @@ describe("AkanLibConfig", () => {
     };
     expect(new AkanLibConfig(lib, config).externalLibs).toEqual(["firebase-admin"]);
   });
+
+  test("defaults docker runs to empty lists and preserves declared ones", () => {
+    const lib = { name: "shared" } as never;
+    expect(new AkanLibConfig(lib, {}).docker).toEqual({ preRuns: [], postRuns: [] });
+    expect(new AkanLibConfig(lib, { docker: { preRuns: ["echo lib"] } }).docker).toEqual({
+      preRuns: ["echo lib"],
+      postRuns: [],
+    });
+  });
 });
 
 describe("AkanAppConfig.importConfigModule", () => {

package/akanConfig/akanConfig.ts

@@ -11,13 +11,18 @@ import {
   type AkanMobileConfig,
   type AkanMobileTargetConfig,
   type AkanRouteConfig,
+  type AkanWebConfig,
+  type AkanWebOption,
   type AppConfigResult,
   type Arch,
   archs,
   type DatabaseMode,
   type DeepPartial,
   type DockerConfig,
+  type DockerOption,
+  type DockerRun,
   type LibConfigResult,
+  type LibDockerConfig,
 } from "./types";
 
 const DEFAULT_BARREL_IMPORTS = ["akanjs/webkit", "akanjs/common", "akanjs/ui", "akanjs/server"];
@@ -49,6 +54,7 @@ const DEFAULT_OPTIMIZE_IMPORTS = [
   "react-icons/*",
 ];
 const WORKSPACE_BARREL_FACETS = ["ui", "webkit", "common", "client", "server"] as const;
+const DEFAULT_DOCKER_IMAGE = "oven/bun:1-slim";
 const SSR_RUNTIME_PACKAGES = ["react", "react-dom", "react-server-dom-webpack"] as const;
 // The firebase client (push tokens) and the Capacitor toolchain — `@capacitor/cli` (`npx cap`),
 // `@capacitor/assets` (`npx @capacitor/assets`) plus the `@capacitor/core`/`ios`/`android` runtime
@@ -163,11 +169,38 @@ const normalizeDeepLinks = (deepLinks: DeepPartial<AkanMobileTargetConfig["deepL
   } satisfies AkanMobileTargetConfig["deepLinks"];
 };
 
+/** What `akan.config.ts` may write: the resolved shape made partial, with `docker` and `web` in their unions. */
+type AppConfigDeclaration = Omit<DeepPartial<AppConfigResult>, "docker" | "web"> & {
+  docker?: DockerOption;
+  web?: AkanWebOption;
+};
+
+/** What the workspace's libs add to an app's build, read off each `libs/<lib>/akan.config.ts`. */
+export interface LibContributions {
+  externalLibs: string[];
+  docker: LibDockerConfig;
+}
+
+const emptyLibContributions = (): LibContributions => ({
+  externalLibs: [],
+  docker: { preRuns: [], postRuns: [] },
+});
+
+/** First occurrence wins, so a step a lib and its app both declare becomes one layer. */
+const dedupeDockerRuns = (runs: DockerRun[]): DockerRun[] => {
+  const byKey = new Map<string, DockerRun>();
+  for (const run of runs) byKey.set(typeof run === "string" ? run : JSON.stringify(run), run);
+  return [...byKey.values()];
+};
+
 export class AkanAppConfig implements AppConfigResult {
   app: App;
   rootPackageJson: PackageJson;
   docker: DockerConfig;
+  /** The Dockerfile `akan build` writes: the declared string verbatim, or one assembled from the parts. */
+  dockerfile: string;
   defaultDatabaseMode: DatabaseMode;
+  web: AkanWebConfig;
   externalLibs: string[];
   barrelImports: string[];
   optimizeImports: string[];
@@ -192,10 +225,10 @@ export class AkanAppConfig implements AppConfigResult {
     app: App,
     libs: string[],
     rootPackageJson: PackageJson,
-    config: DeepPartial<AppConfigResult>,
+    config: AppConfigDeclaration,
     baseDevEnv: BaseDevEnv,
     plugins: AkanPlugin[] = [],
-    libExternalLibs: readonly string[] = [],
+    libContributions: LibContributions = emptyLibContributions(),
   ) {
     this.app = app;
     this.rootPackageJson = rootPackageJson;
@@ -204,7 +237,7 @@ export class AkanAppConfig implements AppConfigResult {
     this.plugins = plugins;
     this.#applyRoutes(config?.routes);
     this.defaultDatabaseMode = config?.defaultDatabaseMode ?? "single";
-    this.externalLibs = [...new Set([...(config?.externalLibs ?? []), ...libExternalLibs])];
+    this.externalLibs = [...new Set([...(config?.externalLibs ?? []), ...libContributions.externalLibs])];
     this.barrelImports = [
       ...DEFAULT_BARREL_IMPORTS,
       ...WORKSPACE_BARREL_FACETS.map((facet) => `@apps/${app.name}/${facet}`),
@@ -221,7 +254,18 @@ export class AkanAppConfig implements AppConfigResult {
     this.syncPageLibs = (config?.syncPageLibs as string[] | boolean | undefined) ?? false;
     this.hasMobileConfig = Boolean(config.mobile);
     this.mobile = this.#resolveMobileConfig(config.mobile);
-    this.docker = this.#makeDockerContent(config?.docker ?? {});
+    this.web = this.#resolveWebConfig(config.web);
+    this.docker = AkanAppConfig.#resolveDocker(config.docker, libContributions.docker);
+    this.dockerfile = this.#makeDockerfile();
+  }
+  #resolveWebConfig(web: AkanWebOption | undefined): AkanWebConfig {
+    const resolved = typeof web === "object" ? { ssr: true, csr: web.csr } : { ssr: web ?? true, csr: web ?? true };
+    // `akan build-ios` / `build-android` copy `dist/apps/<app>/csr/<target>.html` into the native project.
+    if (!resolved.csr && this.hasMobileConfig)
+      throw new Error(
+        `apps/${this.app.name}/akan.config.ts turns the CSR bundle off but declares mobile targets; the Capacitor build ships that bundle. Drop the mobile section or leave CSR on.`,
+      );
+    return resolved;
   }
   #resolveMobileConfig(mobile: DeepPartial<AkanMobileConfig> | undefined): AkanMobileConfig {
     const {
@@ -322,7 +366,7 @@ export class AkanAppConfig implements AppConfigResult {
         this.branches.forEach((domain) => void domains.add(`${basePath}-${domain}.${serveDomain}`));
       });
   }
-  #getDockerRunScripts(runs: (string | { [key in Arch]?: string })[]) {
+  #getDockerRunScripts(runs: DockerRun[]) {
     return runs.map((run) => {
       if (typeof run === "string") return `RUN ${run}`;
       else
@@ -339,26 +383,31 @@ export class AkanAppConfig implements AppConfigResult {
     if (typeof image === "string") return `FROM ${image}`;
     else return archs.map((arch) => `FROM ${image[arch] ?? defaultImage} AS ${arch}`).join("\n");
   }
-  #makeDockerContent(docker: DeepPartial<DockerConfig>): DockerConfig {
-    if (docker.content)
-      return {
-        content: docker.content,
-        image: {},
-        preRuns: [],
-        postRuns: [],
-        command: [],
-      };
-    const preRunScripts = this.#getDockerRunScripts(docker.preRuns ?? []);
-    const postRunScripts = this.#getDockerRunScripts(docker.postRuns ?? []);
-
-    const imageScript = docker.image
-      ? this.#getDockerImageScript(docker.image, "oven/bun:1-slim")
-      : "FROM oven/bun:1-slim";
-    const command = docker.command ?? ["bun", "main.js"];
-    const content = `${imageScript}
+  /** A declared Dockerfile string is verbatim, so a lib's steps are dropped rather than silently unapplied. */
+  static #resolveDocker(docker: DockerOption | undefined, libDocker: LibDockerConfig): DockerConfig {
+    if (typeof docker === "string") return docker;
+    return {
+      image: docker?.image ?? DEFAULT_DOCKER_IMAGE,
+      preRuns: dedupeDockerRuns([...libDocker.preRuns, ...(docker?.preRuns ?? [])]),
+      postRuns: dedupeDockerRuns([...libDocker.postRuns, ...(docker?.postRuns ?? [])]),
+      command: docker?.command ?? ["bun", "main.js"],
+    };
+  }
+  #makeDockerfile(): string {
+    if (typeof this.docker === "string") return this.docker;
+    const { image, preRuns, postRuns, command } = this.docker;
+    const preRunScripts = this.#getDockerRunScripts(preRuns);
+    const postRunScripts = this.#getDockerRunScripts(postRuns);
+    const imageScript = this.#getDockerImageScript(image, DEFAULT_DOCKER_IMAGE);
+    // The image default matches what the build actually produced; a deployment narrows it further with its
+    // own env, and can never widen it past the artifacts that are in the image.
+    const webEnvLines = [
+      ...(this.web.ssr ? [] : ["ENV AKAN_SSR=false"]),
+      ...(this.web.csr ? [] : ["ENV AKAN_CSR=false"]),
+    ].join("\n");
+    return `${imageScript}
+RUN apt-get update && apt-get upgrade -y && apt-get install -y --no-install-recommends ca-certificates tzdata && rm -rf /var/lib/apt/lists/*
 RUN ln -sf /usr/share/zoneinfo/Asia/Seoul /etc/localtime
-RUN apt-get update && apt-get upgrade -y
-RUN apt-get install -y --no-install-recommends git redis build-essential python3 ca-certificates fonts-liberation libappindicator3-1 libasound2 libatk-bridge2.0-0 libatk1.0-0 libc6 libcairo2 libcups2 libdbus-1-3 libexpat1 libfontconfig1 libgbm1 libgcc1 libglib2.0-0 libgtk-3-0 libnspr4 libnss3 libpango-1.0-0 libpangocairo-1.0-0 libstdc++6 libx11-6 libx11-xcb1 libxcb1 libxcomposite1 libxcursor1 libxdamage1 libxext6 libxfixes3 libxi6 libxrandr2 libxrender1 libxss1 libxtst6 lsb-release wget xdg-utils udev ffmpeg
 ARG TARGETARCH
 ${preRunScripts.join("\n")}
 RUN mkdir -p /workspace
@@ -377,15 +426,8 @@ ${this.basePaths.size ? `ENV AKAN_PUBLIC_BASE_PATHS=${[...this.basePaths].join("
 ENV AKAN_PUBLIC_DEFAULT_LOCALE=${this.i18n.defaultLocale}
 ENV AKAN_PUBLIC_LOCALES=${this.i18n.locales.join(",")}
 ENV AKAN_PUBLIC_OPERATION_MODE=cloud
-
+${webEnvLines}
 CMD [${command.map((c) => `"${c}"`).join(",")}]`;
-    return {
-      content,
-      image: imageScript,
-      preRuns: docker.preRuns ?? [],
-      postRuns: docker.postRuns ?? [],
-      command,
-    };
   }
   static #importGeneration = 0;
   /**
@@ -412,24 +454,34 @@ CMD [${command.map((c) => `"${c}"`).join(",")}]`;
       app.workspace.getPackageJson(),
     ]);
     const resolved = typeof configImp === "function" ? configImp(app) : configImp;
-    const { plugins, ...config } = (resolved ?? {}) as DeepPartial<AppConfigResult> & { plugins?: AkanPlugin[] };
-    const libExternalLibs = await AkanAppConfig.#collectLibExternalLibs(app, libs, bustImportCache);
-    return new AkanAppConfig(app, libs, rootPackageJson, config, baseDevEnv, plugins ?? [], libExternalLibs);
+    const { plugins, ...config } = (resolved ?? {}) as AppConfigDeclaration & { plugins?: AkanPlugin[] };
+    const libContributions = await AkanAppConfig.#collectLibContributions(app, libs, bustImportCache);
+    return new AkanAppConfig(app, libs, rootPackageJson, config, baseDevEnv, plugins ?? [], libContributions);
   }
   //* Every workspace lib is read, not just this app's lib deps: narrowing the set needs the dependency
   //* scan, and the incremental page rebundle re-reads this config on every file change.
-  static async #collectLibExternalLibs(app: App, libs: string[], bustImportCache: boolean): Promise<string[]> {
+  static async #collectLibContributions(
+    app: App,
+    libs: string[],
+    bustImportCache: boolean,
+  ): Promise<LibContributions> {
     const libConfigs = await Promise.all(
       libs.map(async (libName) =>
         LibExecutor.from(app, libName)
           .getConfig({ refresh: bustImportCache })
           .catch((error: unknown) => {
-            app.logger.warn(`Skipped libs/${libName}/akan.config.ts externalLibs: ${String(error)}`);
+            app.logger.warn(`Skipped libs/${libName}/akan.config.ts contributions: ${String(error)}`);
             return null;
           }),
       ),
     );
-    return libConfigs.flatMap((libConfig) => libConfig?.externalLibs ?? []);
+    return {
+      externalLibs: libConfigs.flatMap((libConfig) => libConfig?.externalLibs ?? []),
+      docker: {
+        preRuns: libConfigs.flatMap((libConfig) => libConfig?.docker.preRuns ?? []),
+        postRuns: libConfigs.flatMap((libConfig) => libConfig?.docker.postRuns ?? []),
+      },
+    };
   }
   #resolveProductionDependencyVersion(lib: string) {
     const rootVersion = this.rootPackageJson.dependencies?.[lib] ?? this.rootPackageJson.devDependencies?.[lib];
@@ -539,11 +591,13 @@ function mergeImageConfig(config: Partial<AkanImageConfig> = {}): AkanImageConfi
 export class AkanLibConfig implements LibConfigResult {
   lib: Lib;
   externalLibs: string[];
+  docker: LibDockerConfig;
   /** Live-only: plugins declared in this lib's `akan.config.ts` (never serialized). */
   plugins: AkanPlugin[];
   constructor(lib: Lib, config: DeepPartial<LibConfigResult>, plugins: AkanPlugin[] = []) {
     this.lib = lib;
     this.externalLibs = config?.externalLibs ?? [];
+    this.docker = { preRuns: config?.docker?.preRuns ?? [], postRuns: config?.docker?.postRuns ?? [] };
     this.plugins = plugins;
   }
   static async from(lib: Lib, { bustImportCache = false }: { bustImportCache?: boolean } = {}) {

package/akanConfig/types.ts

@@ -9,6 +9,8 @@ export type {
   AkanRouteConfig,
   AkanScanInfo,
   AkanSyncContext,
+  AkanWebConfig,
+  AkanWebOption,
   AppConfig,
   AppConfigInput,
   AppConfigResult,
@@ -17,10 +19,14 @@ export type {
   DatabaseMode,
   DeepPartial,
   DockerConfig,
+  DockerImageConfig,
+  DockerOption,
+  DockerRun,
   FileConventionScanResult,
   LibConfig,
   LibConfigInput,
   LibConfigResult,
+  LibDockerConfig,
   LibScanResult,
   MobileEnv,
   MobilePermission,

package/applicationBuildRunner.ts

@@ -77,6 +77,7 @@ export class ApplicationBuildRunner {
   async build({ spinner = false }: BuildOptions = {}): Promise<BuildResult> {
     // serial build is needed because of Bun.build is unstable for parallel build
     const phaseOptions = { spinner };
+    const { web } = await this.#app.getConfig();
     await this.#runPhase("prepare", "Preparing output directory", () => this.#app.prepareCommand("build"), undefined, {
       spinner,
     });
@@ -91,18 +92,20 @@ export class ApplicationBuildRunner {
     await this.#runPhase(
       "ssr",
       "Building SSR route artifacts",
-      () => this.#buildSsr(),
+      async () => (web.ssr ? await this.#buildSsr() : null),
       (result) =>
         result
           ? `${result.allRoutes.manifest.routeIds.length} routes, ${result.allRoutes.manifest.knownEntries.length} entries`
-          : "skipped",
+          : web.ssr
+            ? "skipped"
+            : "disabled by akan.config.ts web.ssr",
       phaseOptions,
     );
     await this.#runPhase(
       "csr",
       "Building CSR assets",
-      () => this.#buildCsr(),
-      (result) => result?.outputDir ?? "skipped",
+      async () => (web.csr ? await this.#buildCsr() : null),
+      (result) => result?.outputDir ?? (web.csr ? "skipped" : "disabled by akan.config.ts web.csr"),
       phaseOptions,
     );
     await this.#runPhase(
@@ -165,7 +168,7 @@ export class ApplicationBuildRunner {
     const akanConfig = await this.#app.getConfig();
     await Promise.all([
       this.#app.dist.writeJson("package.json", akanConfig.getProductionPackageJson()),
-      this.#app.dist.writeFile(`${this.#app.dist.cwdPath}/Dockerfile`, akanConfig.docker.content),
+      this.#app.dist.writeFile(`${this.#app.dist.cwdPath}/Dockerfile`, akanConfig.dockerfile),
     ]);
   }
 
@@ -174,6 +177,7 @@ export class ApplicationBuildRunner {
     const backendExternals = [
       ...new Set([...akanConfig.externalLibs, ...SSR_RENDER_EXTERNALS, ...AKAN_OPTIONAL_BACKEND_EXTERNALS]),
     ];
+    const { web } = akanConfig;
     const backendEntryPoints = [`${this.#app.cwdPath}/main.ts`, `${this.#app.cwdPath}/server.ts`];
     for (const entrypoint of backendEntryPoints) {
       if (!(await Bun.file(entrypoint).exists())) throw new Error(`Backend entrypoint not found: ${entrypoint}`);
@@ -187,17 +191,20 @@ export class ApplicationBuildRunner {
       define: { "process.env.NODE_ENV": JSON.stringify("production") },
       plugins: backendExternals.length > 0 ? [this.#createExternalSpecifiersPlugin(backendExternals)] : [],
     });
-    const rscWorkerResult = await this.#buildOrThrow("rsc-worker", {
-      entrypoints: [this.#resolveRscWorkerBuildEntry()],
-      outdir: this.#app.dist.cwdPath,
-      target: "bun",
-      minify: true,
-      naming: { entry: "[name].[ext]", chunk: "chunk-[hash].[ext]" },
-      conditions: ["react-server"],
-      // `akan build` must embed production react-server-dom regardless of the shell's NODE_ENV.
-      define: { "process.env.NODE_ENV": JSON.stringify("production") },
-      plugins: backendExternals.length > 0 ? [this.#createExternalSpecifiersPlugin(backendExternals)] : [],
-    });
+    // Nothing spawns the RSC worker without SSR, so an api-only image does not carry it.
+    const rscWorkerResult = web.ssr
+      ? await this.#buildOrThrow("rsc-worker", {
+          entrypoints: [this.#resolveRscWorkerBuildEntry()],
+          outdir: this.#app.dist.cwdPath,
+          target: "bun",
+          minify: true,
+          naming: { entry: "[name].[ext]", chunk: "chunk-[hash].[ext]" },
+          conditions: ["react-server"],
+          // `akan build` must embed production react-server-dom regardless of the shell's NODE_ENV.
+          define: { "process.env.NODE_ENV": JSON.stringify("production") },
+          plugins: backendExternals.length > 0 ? [this.#createExternalSpecifiersPlugin(backendExternals)] : [],
+        })
+      : null;
     const consoleRuntimeResult = await this.#buildOrThrow("console-runtime", {
       entrypoints: [this.#resolveConsoleRuntimeBuildEntry()],
       outdir: this.#app.dist.cwdPath,
@@ -208,8 +215,9 @@ export class ApplicationBuildRunner {
     });
     await this.#writeConsoleShim();
     return {
-      entrypoints: backendEntryPoints.length + 2,
-      outputs: backendResult.outputs.length + rscWorkerResult.outputs.length + consoleRuntimeResult.outputs.length + 1,
+      entrypoints: backendEntryPoints.length + (rscWorkerResult ? 2 : 1),
+      outputs:
+        backendResult.outputs.length + (rscWorkerResult?.outputs.length ?? 0) + consoleRuntimeResult.outputs.length + 1,
     };
   }
 

package/executors.ts

@@ -1371,11 +1371,20 @@ export class AppExecutor extends SysExecutor {
       await Promise.all([this.dist.mkdir("private"), this.dist.mkdir("public")]);
       //* Lib assets are symlinks in the app dir (see syncAssets). dist is the docker build context and the
       //* release tarball root, neither of which follows a link out of itself, so materialize them here.
+      //* `public/` has exactly one reader — the web router's catch-all — so an api-only build leaves it out.
       await Promise.all([
         this.cp("private", `${this.dist.cwdPath}/private`, { dereference: true }),
-        this.cp("public", `${this.dist.cwdPath}/public`, { dereference: true }),
+        ...(akanConfig.web.ssr ? [this.cp("public", `${this.dist.cwdPath}/public`, { dereference: true })] : []),
       ]);
-    } else await this.removeDir(".akan");
+    } else {
+      await this.removeDir(".akan");
+      //? `web` is a build declaration: `akan start` keeps the full dev surface because the incremental
+      //? builder is also the file watcher, so switching it off would take server-code HMR with it.
+      if (!akanConfig.web.ssr || !akanConfig.web.csr)
+        this.logger.warn(
+          `akan.config.ts disables web.${!akanConfig.web.ssr ? "ssr" : "csr"}; \`akan start\` still serves it, \`akan build\` will not`,
+        );
+    }
     //? `akan start` is the dev server, and it must say so rather than inherit an answer. Bun auto-loads the
     //? workspace `.env`, so NODE_ENV=production can reach this process without ever being exported in a shell —
     //? and a dev server that believes it is production serves from the production route cache, whose every

package/frontendBuild/ssrBaseArtifactBuilder.ts

@@ -77,6 +77,7 @@ export class SsrBaseArtifactBuilder {
       branches: [...akanConfig.branches],
       i18n: akanConfig.i18n,
       imageConfig: akanConfig.images,
+      web: akanConfig.web,
       deepLinkAssociations: Object.values(akanConfig.mobile.targets)
         .filter((target) => (target.deepLinks?.domains?.length ?? 0) > 0)
         .map((target) => ({

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@akanjs/devkit",
-  "version": "3.0.0-alpha.64",
+  "version": "3.0.0-alpha.66",
   "sourceType": "module",
   "type": "module",
   "publishConfig": {
@@ -45,7 +45,7 @@
     "@langchain/openai": "^1.4.6",
     "@tailwindcss/node": "^4.3.0",
     "@trapezedev/project": "^7.1.4",
-    "akanjs": "3.0.0-alpha.64",
+    "akanjs": "3.0.0-alpha.66",
     "chalk": "^5.6.2",
     "commander": "^14.0.3",
     "dayjs": "^1.11.20",

package/scanInfo.ts

@@ -9,6 +9,7 @@ import type {
   PkgScanResult,
   ScanResult,
 } from "./akanConfig";
+import { AkanAppConfig } from "./akanConfig";
 import { AppExecutor, LibExecutor, PkgExecutor, WorkspaceExecutor } from "./executors";
 import { isAllowedLibFacetRootFile, rootAllowedDirs, rootAllowedFiles } from "./workspaceLayout";
 
@@ -285,12 +286,11 @@ class ScanInfo {
       }),
     ]);
     const routes = exec.type === "lib" ? [] : await (exec as AppExecutor).getPageKeys();
-    const scanResult: AppScanResult | LibScanResult = {
+    const common = {
       name: exec.name,
       type: exec.type,
       repoName: exec.workspace.repoName,
       serveDomain: WorkspaceExecutor.getBaseDevEnv(path.join(exec.workspace.workspaceRoot, ".env")).serveDomain,
-      akanConfig,
       files,
       libDeps,
       pkgDeps,
@@ -298,6 +298,11 @@ class ScanInfo {
       devDependencies: npmDevDeps.filter((dep) => !isAkanFrameworkDependency(dep)),
       routes,
     };
+    //? `exec.type` and the resolved config class are correlated, which the union alone cannot express.
+    const scanResult: AppScanResult | LibScanResult =
+      akanConfig instanceof AkanAppConfig
+        ? ({ ...common, akanConfig } satisfies AppScanResult)
+        : ({ ...common, akanConfig } satisfies LibScanResult);
     return scanResult;
   }
 
@@ -462,7 +467,7 @@ export class LibInfo extends ScanInfo {
           LibInfo.libInfos.set(libName, await LibInfo.fromExecutor(libExecutor));
         }),
     );
-    const libInfo = new LibInfo(exec, scanResult);
+    const libInfo = new LibInfo(exec, scanResult as LibScanResult);
     LibInfo.libInfos.set(exec.name, libInfo);
     LibInfo.#sortedLibIndices = null;
     return libInfo;