@akanjs/devkit 2.3.0 → 2.3.1-rc.0

package/commandDecorators/command.ts

@@ -336,7 +336,7 @@ It may cause unexpected behavior. Run \`akan update\` to update latest akanjs.`,
         };
 
         programCommand.action(async (...args: unknown[]) => {
-          Logger.rawLog();
+          if (!targetMeta.targetOption.stdio) Logger.rawLog();
           const cmdArgs = args.slice(0, args.length - 2);
           const opt = args[args.length - 2] as Record<string, unknown>;
           const commandArgs = [] as unknown[];
@@ -364,7 +364,7 @@ It may cause unexpected behavior. Run \`akan update\` to update latest akanjs.`,
 
           try {
             await targetMeta.handler.call(cmd, ...commandArgs);
-            Logger.rawLog();
+            if (!targetMeta.targetOption.stdio) Logger.rawLog();
           } catch (e) {
             printCliError(e);
             throw e;

package/commandDecorators/targetMeta.ts

@@ -28,4 +28,5 @@ export interface TargetOption {
   devOnly?: boolean;
   desc?: string;
   runsOnWorkspaceRoot?: boolean;
+  stdio?: boolean;
 }

package/executors.test.ts

@@ -256,6 +256,98 @@ describe("Workspace and app executor environment contracts", () => {
     expect((await stat(path.join(root, "dist/apps/demo/public"))).isDirectory()).toBe(true);
   });
 
+  test("accepts metadata route exports during page key discovery", async () => {
+    const root = await makeTempRoot();
+    process.env.AKAN_PUBLIC_REPO_NAME = "repo";
+    process.env.AKAN_PUBLIC_SERVE_DOMAIN = "example.com";
+    process.env.AKAN_PUBLIC_ENV = "local";
+    await writeJson(path.join(root, "package.json"), rootPackageJson());
+    await mkdir(path.join(root, "apps/demo/page/docs"), { recursive: true });
+    await writeFile(path.join(root, "apps/demo/akan.config.ts"), "export default {};\n");
+    await writeFile(
+      path.join(root, "apps/demo/page/_layout.tsx"),
+      [
+        "export const head = null;",
+        "export const metadata = { title: 'Root' };",
+        "export default function Layout({ children }) { return children; }",
+        "",
+      ].join("\n"),
+    );
+    await writeFile(
+      path.join(root, "apps/demo/page/docs/_layout.tsx"),
+      [
+        "export async function generateMetadata() { return { title: 'Docs' }; }",
+        "export default function Layout({ children }) { return children; }",
+        "",
+      ].join("\n"),
+    );
+    await writeFile(
+      path.join(root, "apps/demo/page/docs/intro.tsx"),
+      ["export const metadata = { title: 'Intro' };", "export default function Page() { return null; }", ""].join("\n"),
+    );
+
+    const workspace = new WorkspaceExecutor({ workspaceRoot: root, repoName: "repo" });
+    const app = AppExecutor.from(workspace, "demo");
+
+    await expect(app.getPageKeys({ refresh: true })).resolves.toEqual([
+      "./_layout.tsx",
+      "./docs/_layout.tsx",
+      "./docs/intro.tsx",
+    ]);
+  });
+
+  test("rejects conflicting metadata route exports during page key discovery", async () => {
+    const root = await makeTempRoot();
+    process.env.AKAN_PUBLIC_REPO_NAME = "repo";
+    process.env.AKAN_PUBLIC_SERVE_DOMAIN = "example.com";
+    process.env.AKAN_PUBLIC_ENV = "local";
+    await writeJson(path.join(root, "package.json"), rootPackageJson());
+    await mkdir(path.join(root, "apps/demo/page"), { recursive: true });
+    await writeFile(path.join(root, "apps/demo/akan.config.ts"), "export default {};\n");
+    await writeFile(
+      path.join(root, "apps/demo/page/conflict.tsx"),
+      [
+        "export const metadata = { title: 'Conflict' };",
+        "export function generateMetadata() { return { title: 'Conflict' }; }",
+        "export default function Page() { return null; }",
+        "",
+      ].join("\n"),
+    );
+
+    const workspace = new WorkspaceExecutor({ workspaceRoot: root, repoName: "repo" });
+    const app = AppExecutor.from(workspace, "demo");
+
+    await expect(app.getPageKeys({ refresh: true })).rejects.toThrow(
+      "metadata and generateMetadata cannot both be exported",
+    );
+  });
+
+  test("rejects mixed head and metadata route export channels during page key discovery", async () => {
+    const root = await makeTempRoot();
+    process.env.AKAN_PUBLIC_REPO_NAME = "repo";
+    process.env.AKAN_PUBLIC_SERVE_DOMAIN = "example.com";
+    process.env.AKAN_PUBLIC_ENV = "local";
+    await writeJson(path.join(root, "package.json"), rootPackageJson());
+    await mkdir(path.join(root, "apps/demo/page"), { recursive: true });
+    await writeFile(path.join(root, "apps/demo/akan.config.ts"), "export default {};\n");
+    await writeFile(
+      path.join(root, "apps/demo/page/mixed.tsx"),
+      [
+        "export const head = null;",
+        "export const metadata = { title: 'Mixed' };",
+        "export default function Page() { return null; }",
+        "",
+      ].join("\n"),
+    );
+
+    const workspace = new WorkspaceExecutor({ workspaceRoot: root, repoName: "repo" });
+    const app = AppExecutor.from(workspace, "demo");
+
+    await expect(app.getPageKeys({ refresh: true })).rejects.toThrow(
+      "head/generateHead and metadata/generateMetadata cannot both be exported",
+    );
+  });
+
   test("assigns start command ports from sorted app order", async () => {
     const root = await makeTempRoot();
     process.env.AKAN_PUBLIC_REPO_NAME = "repo";

package/executors.ts

@@ -151,11 +151,21 @@ const parseEnvFile = (envPath: string): Record<string, string> => {
   return env;
 };
 
-const PAGE_ROUTE_EXPORTS = new Set(["default", "pageConfig", "head", "generateHead", "Loading"]);
+const PAGE_ROUTE_EXPORTS = new Set([
+  "default",
+  "pageConfig",
+  "head",
+  "metadata",
+  "generateHead",
+  "generateMetadata",
+  "Loading",
+]);
 const ROOT_LAYOUT_EXPORTS = new Set([
   "default",
   "head",
+  "metadata",
   "generateHead",
+  "generateMetadata",
   "fonts",
   "manifest",
   "theme",
@@ -166,7 +176,16 @@ const ROOT_LAYOUT_EXPORTS = new Set([
   "NotFound",
   "Error",
 ]);
-const LAYOUT_ROUTE_EXPORTS = new Set(["default", "head", "generateHead", "Loading", "NotFound", "Error"]);
+const LAYOUT_ROUTE_EXPORTS = new Set([
+  "default",
+  "head",
+  "metadata",
+  "generateHead",
+  "generateMetadata",
+  "Loading",
+  "NotFound",
+  "Error",
+]);
 
 function validateRouteSourceExports(
   source: string,
@@ -221,6 +240,18 @@ function validateRouteSourceExports(
   if (exported.has("head") && exported.has("generateHead")) {
     throw new Error(`[route-convention] head and generateHead cannot both be exported in ${filePath}`);
   }
+  if (
+    !options.rootLayout &&
+    (exported.has("head") || exported.has("generateHead")) &&
+    (exported.has("metadata") || exported.has("generateMetadata"))
+  ) {
+    throw new Error(
+      `[route-convention] head/generateHead and metadata/generateMetadata cannot both be exported in ${filePath}`,
+    );
+  }
+  if (exported.has("metadata") && exported.has("generateMetadata")) {
+    throw new Error(`[route-convention] metadata and generateMetadata cannot both be exported in ${filePath}`);
+  }
 }
 
 export class Executor {

package/frontendBuild/frontendBuild.test.ts

@@ -8,6 +8,7 @@ import { CsrArtifactBuilder } from "./csrArtifactBuilder";
 import { CssCompiler, isIgnoredNodeModuleSource } from "./cssCompiler";
 import { CssImportResolver } from "./cssImportResolver";
 import { HmrChangeClassifier } from "./hmrChangeClassifier";
+import { PagesBundleBuilder } from "./pagesBundleBuilder";
 import { PagesEntrySourceGenerator } from "./pagesEntrySourceGenerator";
 import { RoutesManifestArtifactSerializer } from "./routesManifestArtifactSerializer";
 import { prepareCssAsset } from "./ssrBaseArtifactBuilder";
@@ -95,6 +96,32 @@ describe("PagesEntrySourceGenerator", () => {
   });
 });
 
+describe("PagesBundleBuilder", () => {
+  test("stubs CSS imports in the server pages bundle", async () => {
+    const root = await makeTempRoot();
+    const entry = path.join(root, "entry.tsx");
+    const css = path.join(root, "styles.css");
+    const outdir = path.join(root, "out");
+    await write(entry, ['import "./styles.css";', "export const marker = 1;", ""].join("\n"));
+    await write(
+      css,
+      ['@plugin "daisyui" {', "  themes: false;", "}", "@theme {", "  --color-primary: red;", "}", ""].join("\n"),
+    );
+
+    const result = await Bun.build({
+      entrypoints: [entry],
+      outdir,
+      target: "bun",
+      format: "esm",
+      plugins: [PagesBundleBuilder.createServerCssStubPlugin()],
+    });
+
+    expect(result.success).toBe(true);
+    expect(result.logs).toEqual([]);
+    expect(result.outputs.some((output) => output.kind === "entry-point")).toBe(true);
+  });
+});
+
 describe("CsrArtifactBuilder", () => {
   test("replaces module script src with inline script", async () => {
     const html = [

package/frontendBuild/pagesBundleBuilder.ts

@@ -64,6 +64,7 @@ export class PagesBundleBuilder {
       define: this.#define(),
       plugins: [
         PagesBundleBuilder.createPagesEntryPlugin(entrySource),
+        PagesBundleBuilder.createServerCssStubPlugin(),
         await createExternalizeFrameworkPlugin({ app: this.#app, extra: akanConfig.externalLibs }),
         akanConfig.barrelImports.length > 0
           ? await createBarrelImportsPlugin(this.#app, {
@@ -134,4 +135,16 @@ export class PagesBundleBuilder {
       },
     };
   }
+
+  static createServerCssStubPlugin(): BunPlugin {
+    return {
+      name: "akan-server-css-stub",
+      setup(build) {
+        build.onLoad({ filter: /\.css$/ }, () => ({
+          contents: "",
+          loader: "js",
+        }));
+      },
+    };
+  }
 }

package/frontendBuild/ssrBaseArtifactBuilder.ts

@@ -8,6 +8,7 @@ import { ClientEntriesBundler } from "./clientEntriesBundler";
 import { CssCompiler } from "./cssCompiler";
 import { FontOptimizer } from "./fontOptimizer";
 import { PagesBundleBuilder } from "./pagesBundleBuilder";
+import { RouteClientBuilder } from "./routeClientBuilder";
 import { VENDOR_SPECIFIERS, type VendorSpecifier } from "./vendorSpecifiers";
 
 export interface BuildSsrBaseArtifactResult {
@@ -37,7 +38,8 @@ export class SsrBaseArtifactBuilder {
 
   async build(): Promise<BuildSsrBaseArtifactResult> {
     const akanConfig = await this.#app.getConfig();
-    const { rscClientUrl, vendorMap } = await this.#buildRuntimeClientEntries();
+    const { rscClientUrl, rscRuntimeClientManifest, rscRuntimeSsrManifest, vendorMap } =
+      await this.#buildRuntimeClientEntries();
     const pageKeys = await this.#app.getPageKeys();
     this.#app.verbose(`[base-artifact] discovered ${pageKeys.length} route files under ${this.#app.cwdPath}/page`);
 
@@ -58,6 +60,8 @@ export class SsrBaseArtifactBuilder {
 
     const artifact: BaseBuildArtifact = {
       rscClientUrl,
+      rscRuntimeClientManifest,
+      rscRuntimeSsrManifest,
       vendorMap,
       cssAssets,
       pagesBundlePath:
@@ -80,21 +84,61 @@ export class SsrBaseArtifactBuilder {
     return { artifact, seedIndex, cssCompiler, optimizedFonts };
   }
 
-  async #buildRuntimeClientEntries(): Promise<{ rscClientUrl: string; vendorMap: Record<VendorSpecifier, string> }> {
+  async #buildRuntimeClientEntries(): Promise<
+    Pick<BaseBuildArtifact, "rscClientUrl" | "rscRuntimeClientManifest" | "rscRuntimeSsrManifest"> & {
+      vendorMap: Record<VendorSpecifier, string>;
+    }
+  > {
     const akanServerPath = await this.#resolveAkanServerPath();
     const rscClientEntry = `${akanServerPath}/rscClient.tsx`;
+    const rscSegmentOutletEntry = `${akanServerPath}/rscSegmentOutlet.tsx`;
     const vendorEntries = VENDOR_SPECIFIERS.map((specifier) => ({
       specifier,
       absPath: `${akanServerPath}/vendor/${specifier.replaceAll("/", "-").replaceAll(".", "-")}.ts`,
     }));
-    const entries = [rscClientEntry, ...vendorEntries.map((v) => v.absPath)];
+    const entries = [rscClientEntry, rscSegmentOutletEntry, ...vendorEntries.map((v) => v.absPath)];
     const clientBundle = await new ClientEntriesBundler({ app: this.#app, entries, command: this.#command }).bundle();
+    const ssrBundle = await new ClientEntriesBundler({
+      app: this.#app,
+      entries: [rscSegmentOutletEntry],
+      ...RouteClientBuilder.resolveSsrClientExternalOptions(this.#command),
+      outputSubdir: "client-ssr",
+      command: this.#command,
+    }).bundle();
     const rscClientUrl = clientBundle.entryUrlsByAbsPath.get(rscClientEntry) ?? "";
+    const rscRuntimeSsrManifest = {
+      moduleLoading: null,
+      moduleMap: Object.fromEntries(
+        Object.entries(clientBundle.manifest)
+          .map(([key, row]) => {
+            const ssrOutput = ssrBundle.entryOutputAbsByAbsPath.get(rscSegmentOutletEntry);
+            if (
+              !ssrOutput ||
+              key !== `${clientBundle.clientReferenceIdByAbsPath.get(rscSegmentOutletEntry)}#${row.name}`
+            ) {
+              return null;
+            }
+            return [
+              row.id,
+              { [row.name]: { id: ssrOutput, chunks: [ssrOutput, ssrOutput], name: row.name, async: true } },
+            ];
+          })
+          .filter(
+            (entry): entry is [string, Record<string, { id: string; chunks: string[]; name: string; async: true }>] =>
+              Boolean(entry),
+          ),
+      ),
+    };
     const vendorMap = Object.fromEntries(
       vendorEntries.map(({ specifier, absPath }) => [specifier, clientBundle.entryUrlsByAbsPath.get(absPath) ?? ""]),
     ) as Record<VendorSpecifier, string>;
     this.#app.verbose(`[base-artifact] rscClientUrl=${rscClientUrl} vendors=${Object.keys(vendorMap).length}`);
-    return { rscClientUrl, vendorMap };
+    return {
+      rscClientUrl,
+      rscRuntimeClientManifest: clientBundle.manifest,
+      rscRuntimeSsrManifest,
+      vendorMap,
+    };
   }
   async #resolveAkanServerPath() {
     const candidates: string[] = [];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@akanjs/devkit",
-  "version": "2.3.0",
+  "version": "2.3.1-rc.0",
   "sourceType": "module",
   "type": "module",
   "publishConfig": {
@@ -32,7 +32,7 @@
     "@langchain/openai": "^1.4.6",
     "@tailwindcss/node": "^4.3.0",
     "@trapezedev/project": "^7.1.4",
-    "akanjs": "2.3.0",
+    "akanjs": "2.3.1-rc.0",
     "chalk": "^5.6.2",
     "commander": "^14.0.3",
     "daisyui": "^5.5.20",