@akanjs/devkit 3.1.0 → 3.1.1-rc.0

package/akanConfig/akanConfig.ts

@@ -1,10 +1,10 @@
 import fs from "node:fs";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
-import type { ServerPolicy } from "@akanjs/native/api";
 import type { AkanPlugin } from "akanjs";
 import { DatabaseModes, normalizeRoutePrefix } from "akanjs/base";
 import { type AkanI18nConfig, resolveAkanI18nConfig, trimSlashes } from "akanjs/common";
+import type { ServerPolicy } from "akanjs/native/api";
 import type { AkanImageConfig } from "akanjs/server";
 import type { App, Lib } from "../commandDecorators";
 import { LibExecutor, WorkspaceExecutor } from "../executors";

package/artifact/implicitRootLayout.ts

@@ -244,7 +244,7 @@ ${layoutExports}(
       className={defaultFontClassName}
       layoutStyle={userLayout.layoutStyle ?? inheritedLayout.layoutStyle}
       reconnect={userLayout.reconnect ?? inheritedLayout.reconnect ?? false}
-      wsConnect={userLayout.wsConnect ?? inheritedLayout.wsConnect ?? true}
+      wsConnect={userLayout.wsConnect ?? inheritedLayout.wsConnect}
       allDictionary={process.env.AKAN_PUBLIC_RENDER_ENV === "ssr" ? allDictionary : undefined}
     >
       ${layoutChild}

package/frontendBuild/dictionaryAssetBuilder.test.ts

@@ -0,0 +1,77 @@
+import { describe, expect, test } from "bun:test";
+import { mkdir, readdir, writeFile } from "node:fs/promises";
+import path from "node:path";
+import type { App } from "../commandDecorators";
+import { tempDirs } from "../testHelpers";
+import { DictionaryAssetBuilder } from "./dictionaryAssetBuilder";
+
+const tempRoot = tempDirs("akan-devkit-dict-asset-");
+
+const allDictionary = {
+  en: { app: { title: { t: "Title" }, partial: { t: "Partial" } }, libOnly: { signin: { t: "Sign In" } } },
+  ko: { app: { title: { t: "제목" } } },
+};
+
+const makeApp = async (dictSource?: string) => {
+  const root = await tempRoot();
+  const cwdPath = path.join(root, "apps/demo");
+  await mkdir(path.join(cwdPath, "lib"), { recursive: true });
+  if (dictSource) await writeFile(path.join(cwdPath, "lib/dict.ts"), dictSource);
+  const app = { cwdPath, verbose: () => undefined } as unknown as App;
+  return { app, artifactDir: path.join(root, "artifact") };
+};
+
+const dictSourceOf = (dictionary: object) => `export const getAllDictionary = () => (${JSON.stringify(dictionary)});\n`;
+
+describe("DictionaryAssetBuilder", () => {
+  test("writes one module per locale, the default locale's text filled into the gaps", async () => {
+    const { app, artifactDir } = await makeApp(dictSourceOf(allDictionary));
+    const assets = await new DictionaryAssetBuilder(app, artifactDir).build({
+      defaultLocale: "en",
+      locales: ["en", "ko"],
+    });
+
+    expect(Object.keys(assets)).toEqual(["en", "ko"]);
+    expect(assets.ko.url).toMatch(/^\/_akan\/dict\/ko-[a-z0-9]+\.js$/);
+    expect(assets.ko.url).toBe(`/_akan/${assets.ko.relPath}`);
+    const ko = (await import(path.join(artifactDir, assets.ko.relPath))) as { lang: string; default: object };
+    expect(ko.lang).toBe("ko");
+    expect(ko.default).toEqual({
+      app: { title: { t: "제목" }, partial: { t: "Partial" } },
+      libOnly: { signin: { t: "Sign In" } },
+    });
+    const en = (await import(path.join(artifactDir, assets.en.relPath))) as { default: object };
+    expect(en.default).toEqual(allDictionary.en);
+  });
+
+  test("takes the default locale from the config it is handed", async () => {
+    const { app, artifactDir } = await makeApp(dictSourceOf(allDictionary));
+    const assets = await new DictionaryAssetBuilder(app, artifactDir).build({
+      defaultLocale: "ko",
+      locales: ["en", "ko"],
+    });
+    const en = (await import(path.join(artifactDir, assets.en.relPath))) as { default: object };
+    expect(en.default).toEqual(allDictionary.en);
+    const ko = (await import(path.join(artifactDir, assets.ko.relPath))) as { default: object };
+    expect(ko.default).toEqual(allDictionary.ko);
+  });
+
+  test("names a module by its content, so a rebuild of the same dictionary keeps the URL", async () => {
+    const { app, artifactDir } = await makeApp(dictSourceOf(allDictionary));
+    const i18n = { defaultLocale: "en", locales: ["en", "ko"] };
+    const first = await new DictionaryAssetBuilder(app, artifactDir).build(i18n);
+    const second = await new DictionaryAssetBuilder(app, artifactDir).build(i18n);
+    expect(second).toEqual(first);
+    expect((await readdir(path.join(artifactDir, "dict"))).length).toBe(2);
+    expect(DictionaryAssetBuilder.source("en", { a: { t: "A" } })).not.toBe(
+      DictionaryAssetBuilder.source("en", { a: { t: "B" } }),
+    );
+  });
+
+  test("writes nothing for an app without a dictionary", async () => {
+    const { app, artifactDir } = await makeApp();
+    expect(await new DictionaryAssetBuilder(app, artifactDir).build({ defaultLocale: "en", locales: ["en"] })).toEqual(
+      {},
+    );
+  });
+});

package/frontendBuild/dictionaryAssetBuilder.ts

@@ -0,0 +1,49 @@
+import path from "node:path";
+import { type AllDictionary, Translator } from "akanjs/client";
+import type { AkanI18nConfig } from "akanjs/common";
+import type { DictAsset } from "akanjs/server";
+import type { App } from "../commandDecorators";
+
+export class DictionaryAssetBuilder {
+  static readonly urlPrefix = "/_akan/dict";
+  readonly #app: App;
+  readonly #absArtifactDir: string;
+
+  constructor(app: App, absArtifactDir: string) {
+    this.#app = app;
+    this.#absArtifactDir = absArtifactDir;
+  }
+
+  async build(i18n: AkanI18nConfig): Promise<Record<string, DictAsset>> {
+    const allDictionary = await this.#loadAllDictionary();
+    if (!allDictionary) return {};
+    const assets = await Promise.all(
+      i18n.locales.map((lang) =>
+        this.#write(lang, Translator.fillFromDefault(allDictionary, lang, i18n.defaultLocale)),
+      ),
+    );
+    this.#app.verbose(`[base-artifact] dictionaries -> ${assets.map(([, asset]) => asset.relPath).join(", ")}`);
+    return Object.fromEntries(assets);
+  }
+
+  //? The same module the root layout's macro evaluates in this process, so the asset and the RSC worker's copy agree.
+  async #loadAllDictionary(): Promise<AllDictionary | null> {
+    const dictPath = path.resolve(this.#app.cwdPath, "lib", "dict.ts");
+    if (!(await Bun.file(dictPath).exists())) return null;
+    const { getAllDictionary } = (await import(dictPath)) as { getAllDictionary?: () => AllDictionary };
+    return getAllDictionary ? getAllDictionary() : null;
+  }
+
+  async #write(lang: string, dictionary: object): Promise<readonly [string, DictAsset]> {
+    const source = DictionaryAssetBuilder.source(lang, dictionary);
+    const name = `${lang}-${Bun.hash(source).toString(36)}.js`;
+    const relPath = `dict/${name}`;
+    await Bun.write(path.join(this.#absArtifactDir, relPath), source);
+    return [lang, { url: `${DictionaryAssetBuilder.urlPrefix}/${name}`, relPath }] as const;
+  }
+
+  //? A string for JSON.parse, not an object literal: engines parse the JSON grammar faster than a JS expression.
+  static source(lang: string, dictionary: object): string {
+    return `export const lang = ${JSON.stringify(lang)};\nexport default JSON.parse(${JSON.stringify(JSON.stringify(dictionary))});\n`;
+  }
+}

package/frontendBuild/precompressArtifacts.test.ts

@@ -0,0 +1,42 @@
+import { describe, expect, test } from "bun:test";
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import path from "node:path";
+import zlib from "node:zlib";
+import type { App } from "../commandDecorators";
+import { tempDirs } from "../testHelpers";
+import { precompressArtifacts } from "./precompressArtifacts";
+
+const tempRoot = tempDirs("akan-devkit-precompress-");
+
+const brotliAt = (bytes: Buffer, quality: number) =>
+  zlib.brotliCompressSync(bytes, {
+    params: {
+      [zlib.constants.BROTLI_PARAM_QUALITY]: quality,
+      [zlib.constants.BROTLI_PARAM_SIZE_HINT]: bytes.byteLength,
+    },
+  });
+
+describe("precompressArtifacts", () => {
+  test("writes sidecars for client chunks, stylesheets and dictionaries, a dictionary's brotli at quality 11", async () => {
+    const distPath = await tempRoot();
+    const artifactDir = path.join(distPath, ".akan/artifact");
+    const files = {
+      "client/chunk.js": `export const x = ${JSON.stringify("chunk ".repeat(400))};`,
+      "styles/root.css": `.a{color:red}${".b{margin:0}".repeat(200)}`,
+      "dict/en-abc.js": `export default JSON.parse(${JSON.stringify(JSON.stringify({ a: { t: "word ".repeat(400) } }))});`,
+    };
+    for (const [rel, content] of Object.entries(files)) {
+      await mkdir(path.dirname(path.join(artifactDir, rel)), { recursive: true });
+      await writeFile(path.join(artifactDir, rel), content);
+    }
+    const app = { dist: { cwdPath: distPath }, verbose: () => undefined } as unknown as App;
+
+    expect((await precompressArtifacts(app)).files).toBe(3);
+    const dictPath = path.join(artifactDir, "dict/en-abc.js");
+    const dictBytes = await readFile(dictPath);
+    expect(await readFile(`${dictPath}.br`)).toEqual(brotliAt(dictBytes, 11));
+    const chunkPath = path.join(artifactDir, "client/chunk.js");
+    expect(await readFile(`${chunkPath}.br`)).toEqual(brotliAt(await readFile(chunkPath), 9));
+    expect(await Bun.file(`${dictPath}.gz`).exists()).toBe(true);
+  });
+});

package/frontendBuild/precompressArtifacts.ts

@@ -6,8 +6,10 @@ import { FontPruner } from "./fontPruner";
 
 const COMPRESSIBLE_EXTS = new Set([".css", ".html", ".js", ".json", ".svg"]);
 const MIN_COMPRESS_BYTES = 1024;
-// Brotli 11 is ~100x slower than gzip: worth it for the one CSS asset per basePath, not for hundreds of JS chunks.
-const BROTLI_QUALITY_BY_EXT = { ".css": 11 } as const;
+// Brotli 11 is ~100x slower than gzip: worth it for the one CSS asset per basePath and one dictionary per locale, not
+// for hundreds of JS chunks.
+const MAX_BROTLI_QUALITY = 11;
+const BROTLI_QUALITY_BY_EXT = { ".css": MAX_BROTLI_QUALITY } as const;
 const DEFAULT_BROTLI_QUALITY = 9;
 const GZIP_LEVEL = 9;
 const { formatBytes } = FontPruner;
@@ -20,14 +22,16 @@ export interface PrecompressArtifactsResult {
 }
 
 export async function precompressArtifacts(app: App): Promise<PrecompressArtifactsResult> {
-  //* WebRouter serves client/ and styles/ through the same sidecar-aware #fileResponse.
+  //* WebRouter serves client/, styles/ and dict/ through the same sidecar-aware #fileResponse.
+  const artifactDir = path.join(app.dist.cwdPath, ".akan/artifact");
   const roots = [
-    path.join(app.dist.cwdPath, ".akan/artifact/client"),
-    path.join(app.dist.cwdPath, ".akan/artifact/styles"),
+    { root: path.join(artifactDir, "client") },
+    { root: path.join(artifactDir, "styles") },
+    { root: path.join(artifactDir, "dict"), brotliQuality: MAX_BROTLI_QUALITY },
   ];
   const result: PrecompressArtifactsResult = { files: 0, inputBytes: 0, outputBytes: 0, brotliBytes: 0 };
 
-  await Promise.all(roots.map((root) => precompressRoot(root, result)));
+  await Promise.all(roots.map(({ root, brotliQuality }) => precompressRoot(root, result, brotliQuality)));
   if (result.files > 0) {
     app.verbose(
       `[precompress] wrote ${result.files} sidecars (${formatBytes(result.inputBytes)} -> gzip ${formatBytes(
@@ -38,7 +42,11 @@ export async function precompressArtifacts(app: App): Promise<PrecompressArtifac
   return result;
 }
 
-async function precompressRoot(root: string, result: PrecompressArtifactsResult): Promise<void> {
+async function precompressRoot(
+  root: string,
+  result: PrecompressArtifactsResult,
+  brotliQuality?: number,
+): Promise<void> {
   if (!fs.existsSync(root) || !fs.statSync(root).isDirectory()) return;
   const glob = new Bun.Glob("**/*");
   for await (const filePath of glob.scan({ cwd: root, absolute: true })) {
@@ -46,7 +54,7 @@ async function precompressRoot(root: string, result: PrecompressArtifactsResult)
     const bytes = await Bun.file(filePath).bytes();
     const buffer = bytes.buffer.slice(bytes.byteOffset, bytes.byteOffset + bytes.byteLength) as ArrayBuffer;
     const gz = Bun.gzipSync(buffer, { level: GZIP_LEVEL });
-    const br = brotliCompress(buffer, path.extname(filePath).toLowerCase());
+    const br = brotliCompress(buffer, brotliQuality ?? brotliQualityOf(path.extname(filePath).toLowerCase()));
     await Promise.all([Bun.write(`${filePath}.gz`, gz), Bun.write(`${filePath}.br`, br)]);
     result.files += 1;
     result.inputBytes += bytes.byteLength;
@@ -55,8 +63,11 @@ async function precompressRoot(root: string, result: PrecompressArtifactsResult)
   }
 }
 
-function brotliCompress(buffer: ArrayBuffer, ext: string): Buffer {
-  const quality = BROTLI_QUALITY_BY_EXT[ext as keyof typeof BROTLI_QUALITY_BY_EXT] ?? DEFAULT_BROTLI_QUALITY;
+function brotliQualityOf(ext: string): number {
+  return BROTLI_QUALITY_BY_EXT[ext as keyof typeof BROTLI_QUALITY_BY_EXT] ?? DEFAULT_BROTLI_QUALITY;
+}
+
+function brotliCompress(buffer: ArrayBuffer, quality: number): Buffer {
   return zlib.brotliCompressSync(buffer, {
     params: {
       [zlib.constants.BROTLI_PARAM_QUALITY]: quality,

package/frontendBuild/routeClientBuilder.ts

@@ -169,6 +169,7 @@ export class RouteClientBuilder {
       plugins: [
         await createBarrelImportsPlugin(this.#app, {
           pipeAfter: reactFastRefresh ? RouteClientBuilder.normalizeNamedDefaultFunctionForFastRefresh : undefined,
+          external: VENDOR_SPECIFIERS,
         }),
       ],
       external: VENDOR_SPECIFIERS,

package/frontendBuild/ssrBaseArtifactBuilder.ts

@@ -8,6 +8,7 @@ import { computeRouteSeedIndex, type RouteSeedIndex, saveRouteSeedIndex } from "
 import type { App } from "../commandDecorators";
 import { ClientEntriesBundler } from "./clientEntriesBundler";
 import { CssCompiler, type ImportedStylesheet } from "./cssCompiler";
+import { DictionaryAssetBuilder } from "./dictionaryAssetBuilder";
 import { FontOptimizer } from "./fontOptimizer";
 import { PagesBundleBuilder } from "./pagesBundleBuilder";
 import { RouteClientBuilder } from "./routeClientBuilder";
@@ -56,6 +57,7 @@ export class SsrBaseArtifactBuilder {
 
     const pageEntries = await resolveSsrPageEntriesForApp(this.#app, pageKeys);
     const { cssCompiler, optimizedFonts, cssAssets } = await this.#buildStyleAssets();
+    const dictAssets = await new DictionaryAssetBuilder(this.#app, this.#absArtifactDir).build(akanConfig.i18n);
     const pagesBundle = await new PagesBundleBuilder(this.#app, this.#command, pageEntries, this.#serverEnv).build();
     this.#app.verbose(
       `[base-artifact] pages bundle -> ${pagesBundle.bundlePath} (buildId=${pagesBundle.buildId}, splitting=${pagesBundle.splitting}, entry=${pagesBundle.entryBytes} bytes, outputs=${pagesBundle.outputCount}, chunks=${pagesBundle.chunkCount}, total=${pagesBundle.outputBytes} bytes)`,
@@ -75,6 +77,7 @@ export class SsrBaseArtifactBuilder {
       rscRuntimeSsrManifest,
       vendorMap,
       cssAssets,
+      dictAssets,
       pagesBundlePath:
         this.#command === "build"
           ? path.relative(this.#absArtifactDir, pagesBundle.bundlePath)

package/frontendBuild/vendorSpecifiers.ts

@@ -12,6 +12,7 @@ export const VENDOR_SPECIFIERS = [
   "akanjs/common",
   "akanjs/constant",
   "akanjs/fetch",
+  "tailwind-merge",
 ] as const;
 
 export type VendorSpecifier = (typeof VENDOR_SPECIFIERS)[number];

package/mobile/desktopServerStage.ts

@@ -1,7 +1,7 @@
 import { cp, mkdir, readdir, rm, writeFile } from "node:fs/promises";
 import path from "node:path";
-import type { ServerPolicy } from "@akanjs/native/api";
 import { toError } from "akanjs/common";
+import type { ServerPolicy } from "akanjs/native/api";
 import type { AkanAppConfig, NativeEnv } from "../akanConfig";
 import type { App } from "../commandDecorators";
 import type { PackageJson } from "../types";

package/mobile/nativeApi.ts

@@ -1,5 +1,5 @@
 import path from "node:path";
-import type * as NativeBuildApi from "@akanjs/native/api";
+import type * as NativeBuildApi from "akanjs/native/api";
 
 export type NativeBuildApiModule = typeof NativeBuildApi;
 

package/mobile/nativeApp.ts

@@ -1,7 +1,7 @@
 import path from "node:path";
-import type { AkanNativeConfig } from "@akanjs/native/config";
 import type { NativeEnv } from "akanjs";
 import { toError } from "akanjs/common";
+import type { AkanNativeConfig } from "akanjs/native/config";
 import type { App } from "../commandDecorators";
 import { Executor } from "../executors";
 import { type DesktopArch, DesktopBin } from "./desktopBin";

package/mobile/nativeConfig.ts

@@ -1,6 +1,5 @@
 import { readFileSync } from "node:fs";
 import path from "node:path";
-import type { AkanNativeConfig } from "@akanjs/native/config";
 import type {
   AkanNativeDmgConfig,
   AkanNativeTarget,
@@ -10,6 +9,7 @@ import type {
   NativePermission,
 } from "akanjs";
 import { trimSlashes } from "akanjs/common";
+import type { AkanNativeConfig } from "akanjs/native/config";
 import type { DesktopServerBundle } from "./desktopServerStage";
 import { type NativePlatform, resolveAppId } from "./mobileTarget";
 import type { NativePluginFolder } from "./nativePluginFolders";

package/mobile/updatePackFolder.ts

@@ -1,8 +1,8 @@
 import { mkdtemp, rm } from "node:fs/promises";
 import os from "node:os";
 import path from "node:path";
-import type { BundleInfo, UpdateManifest } from "@akanjs/native/api";
 import type { NativeEnv } from "akanjs";
+import type { BundleInfo, UpdateManifest } from "akanjs/native/api";
 import { ExitCodeError } from "../commandDecorators/exitCodeError";
 import type { MobilePlatform } from "./mobileTarget";
 

package/mobile/updateUploader.ts

@@ -1,7 +1,7 @@
 import { readdir } from "node:fs/promises";
 import path from "node:path";
-import type { UpdateEnvelope, UpdateManifest } from "@akanjs/native/api";
 import { isRecord, trimTrailingSlashes } from "akanjs/common";
+import type { UpdateEnvelope, UpdateManifest } from "akanjs/native/api";
 import { UpdatePackFolder } from "./updatePackFolder";
 
 /** What the uploader needs of an S3 client; Bun.S3Client is one. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@akanjs/devkit",
-  "version": "3.1.0",
+  "version": "3.1.1-rc.0",
   "sourceType": "module",
   "type": "module",
   "publishConfig": {
@@ -48,7 +48,7 @@
     "@earendil-works/pi-tui": "1.3.0",
     "@inquirer/prompts": "^8.7.3",
     "@tailwindcss/node": "^4.3.3",
-    "akanjs": "3.1.0",
+    "akanjs": "3.1.1-rc.0",
     "chalk": "^6.0.1",
     "commander": "^15.0.0",
     "dayjs": "^1.11.23",

package/transforms/barrelImportsPlugin.ts

@@ -10,14 +10,16 @@ export interface BarrelImportsPluginOptions {
   skipPath?: (absPath: string) => boolean;
   /** Runs after the rewrite in the same onLoad (Bun's onLoad cannot fall through); null means no change. */
   pipeAfter?: (source: string, args: { path: string }) => string | Promise<string | null> | null;
+  /** Barrels the bundle leaves external: a rewritten import would inline the modules the import map already serves. */
+  external?: readonly string[];
 }
 
 export const createBarrelImportsPlugin = async (
   app: App,
-  { skipPath = defaultSkipPath, pipeAfter }: BarrelImportsPluginOptions = {},
+  { skipPath = defaultSkipPath, pipeAfter, external = [] }: BarrelImportsPluginOptions = {},
 ): Promise<BunPlugin> => {
   const akanConfig = await app.getConfig();
-  const barrels = [...new Set(akanConfig.barrelImports)].filter(Boolean);
+  const barrels = [...new Set(akanConfig.barrelImports)].filter((barrel) => barrel && !external.includes(barrel));
   const analyzer = new BarrelAnalyzer({
     resolvePackage: await createTsconfigPackageResolver(app),
   });