jskelet 0.6.5 → 0.6.6

package/CHANGELOG.md

@@ -28,6 +28,11 @@ one is listed under a **Breaking** heading.
 
 ### Added
 
+- `build.client` configures esbuild code splitting and chunk groups:
+  `splitting`, declarative `groups` (bare package / path / `@/` matchers), and
+  a `chunkGroup(id)` hook. Matched modules are co-located into one shared
+  chunk (webpack-`manualChunks` trade-off: weaker tree-shaking inside the
+  group). The client build step also prints the total JS file count.
 - `ogImage({ fonts })` registers each `ttf` or `otf` (`path` and `family`)
   with fontconfig so card and raw-SVG text use the site's own files. A slim
   image still needs the `fontconfig` package. `woff` / `woff2` are not drawn

package/docs/07-yapilandirma.md

@@ -91,6 +91,11 @@ export default {
   icons: { dir: "icons", scan: ["views", "client", "routes", "lib"] },
   images: { widths: [400, 800, 1200], quality: 78, skip: ["indirmeler"] },
   clientEnv: ["PUBLIC_WS_URL"],
+  build: {
+    client: {
+      groups: { charts: ["chart.js"] },
+    },
+  },
 
   async headers() {
     return [
@@ -585,6 +590,42 @@ images: {
 ayarla `src` / `srcset`'i `/_jskelet/image?url=…&w=96` biçimine çevirir.
 Elle URL kurmak için `remoteImageUrl(src, { width })` (`jskelet`).
 
+## `build`
+
+**Tip:** `{ client?: { splitting?, groups?, chunkGroup? } }` — **Varsayılan:**
+`{ client: { splitting: true, groups: {}, chunkGroup: null } }`
+
+Client JS (esbuild) bundling knobs. `fonts` / `icons` / `images` / `clientEnv`
+hâlâ top-level kalır; bu bölüm yalnızca splitting ve chunk gruplaması içindir.
+
+| Alan | Tip | Varsayılan | Anlamı |
+| --- | --- | --- | --- |
+| `client.splitting` | `boolean` | `true` | esbuild code splitting. `false` iken `groups` / `chunkGroup` yok sayılır (bir kez uyarı). |
+| `client.groups` | `Record<string, string[]>` | `{}` | İsim → matcher listesi. Bare paket (`chart.js`), yol öneki (`./client/chrome/`) veya `@/` öneki. |
+| `client.chunkGroup` | `(id: string) => string \| null \| undefined` | `null` | Modül kimliğini (mutlak yol veya bare specifier) grup adına map eder. **`groups` ile çakışınca hook kazanır.** |
+
+esbuild native `manualChunks` sunmaz. Framework, gruba düşen import'ları bir
+barrel üzerinden aynı paylaşılan chunk'a çeker. Bedel: grup içi tree-shaking
+zayıflar — bir üyeyi kullanan sayfa grubun geri kalanını da indirebilir
+(webpack `manualChunks` ile aynı takas). Çıktı dosya adı genelde
+`chunks/chunk.<hash>.js` kalır; grup adı config anahtarıdır, dosya adı değil.
+Ayrıntı: [08-build.md](./08-build.md).
+
+```js
+build: {
+  client: {
+    splitting: true,
+    groups: {
+      charts: ["chart.js", "chartjs-adapter-date-fns"],
+      chrome: ["./client/chrome/", "@/client/chrome/"],
+    },
+    chunkGroup(id) {
+      if (id.includes("node_modules/lodash")) return "vendor";
+    },
+  },
+},
+```
+
 ## `clientEnv`
 
 **Tip:** `string[]` — **Varsayılan:** `[]`

package/docs/08-build.md

@@ -175,7 +175,8 @@ esbuild ayarları:
 
 | Ayar | Değer | Sebebi |
 | --- | --- | --- |
-| `bundle`, `splitting` | `true` | Ortak modüller paylaşılan chunk'a çıkar |
+| `bundle` | `true` | — |
+| `splitting` | `config.build.client.splitting` (varsayılan `true`) | Ortak modüller paylaşılan chunk'a çıkar; kapatılınca gruplama da düşer |
 | `format` | `esm` | `type="module"` script'ler |
 | `target` | `chrome111`, `edge111`, `firefox111`, `safari16.4` | ESM + dinamik import + `IntersectionObserver` island modelinin alt sınırı; daha eskisine transpile etmek çıktıyı büyütüp hiçbir ziyaretçi kazandırmıyor |
 | `minify` | `true` | — |
@@ -185,7 +186,26 @@ esbuild ayarları:
 | `legalComments` | `none` | — |
 
 Çıktı `public/assets/js/` altına düşer ve her turda önce temizlenir.
-`browserslist` okunmaz; hedef listesi kod içinde sabittir.
+`browserslist` okunmaz; hedef listesi kod içinde sabittir. Adım satırı entry
+sayısına ek olarak toplam JS dosya sayısını yazar (`1 entry, 48 files`) — çok
+chunk teşhisini kolaylaştırır.
+
+### Chunk gruplama (`build.client.groups` / `chunkGroup`)
+
+esbuild native `manualChunks` sunmaz. `build.client.groups` ve
+`build.client.chunkGroup` bir plugin ile uygulanır:
+
+1. Eşleşen import bir re-export sarmalayıcısına yönlenir.
+2. Sarmalayıcı `jskelet-group:<name>` barrel'ını side-effect olarak çeker.
+3. Barrel gruptaki tüm bilinen üyeleri (bare paketler + yol önekindeki
+   `.{js,ts,mts}` dosyaları + resolve sırasında keşfedilenler) statik import
+   eder — gruba dokunan entry'ler aynı üye kümesine ulaşır ve tek paylaşılan
+   chunk oluşur.
+
+**Trade-off:** grup içi tree-shaking zayıflar; bir üyeyi kullanan sayfa grubun
+geri kalanını da indirebilir. Grup adı config anahtarıdır; çıktı dosyası
+çoğunlukla `chunks/chunk.<hash>.js` kalır. Config sözlüğü:
+[07-yapilandirma.md](./07-yapilandirma.md#build).
 
 ### `@/` alias'ı
 

package/docs/en/07-configuration.md

@@ -95,6 +95,11 @@ export default {
   icons: { dir: "icons", scan: ["views", "client", "routes", "lib"] },
   images: { widths: [400, 800, 1200], quality: 78, skip: ["downloads"] },
   clientEnv: ["PUBLIC_WS_URL"],
+  build: {
+    client: {
+      groups: { charts: ["chart.js"] },
+    },
+  },
 
   async headers() {
     return [
@@ -598,6 +603,42 @@ images: {
 rewrites `src` / `srcset` to `/_jskelet/image?url=…&w=96`. To build URLs by
 hand, use `remoteImageUrl(src, { width })` from `jskelet`.
 
+## `build`
+
+**Type:** `{ client?: { splitting?, groups?, chunkGroup? } }` — **Default:**
+`{ client: { splitting: true, groups: {}, chunkGroup: null } }`
+
+Client JS (esbuild) bundling knobs. `fonts` / `icons` / `images` / `clientEnv`
+stay top-level; this section is only for splitting and chunk grouping.
+
+| Field | Type | Default | Meaning |
+| --- | --- | --- | --- |
+| `client.splitting` | `boolean` | `true` | esbuild code splitting. When `false`, `groups` / `chunkGroup` are ignored (one warning). |
+| `client.groups` | `Record<string, string[]>` | `{}` | Name → matcher list. Bare package (`chart.js`), path prefix (`./client/chrome/`), or `@/` prefix. |
+| `client.chunkGroup` | `(id: string) => string \| null \| undefined` | `null` | Maps a module id (absolute path or bare specifier) to a group name. **When it conflicts with `groups`, the hook wins.** |
+
+esbuild has no native `manualChunks`. The framework pulls imports that land in a
+group into the same shared chunk via a barrel. Trade-off: tree-shaking inside a
+group weakens — a page that uses one member may download the rest of the group
+(same trade-off as webpack `manualChunks`). Output filenames usually stay
+`chunks/chunk.<hash>.js`; the group name is a config key, not the file name.
+Details: [08-build.md](./08-build.md).
+
+```js
+build: {
+  client: {
+    splitting: true,
+    groups: {
+      charts: ["chart.js", "chartjs-adapter-date-fns"],
+      chrome: ["./client/chrome/", "@/client/chrome/"],
+    },
+    chunkGroup(id) {
+      if (id.includes("node_modules/lodash")) return "vendor";
+    },
+  },
+},
+```
+
 ## `clientEnv`
 
 **Type:** `string[]` — **Default:** `[]`

package/docs/en/08-build.md

@@ -183,7 +183,8 @@ esbuild settings:
 
 | Setting | Value | Reason |
 | --- | --- | --- |
-| `bundle`, `splitting` | `true` | Shared modules move into a shared chunk |
+| `bundle` | `true` | — |
+| `splitting` | `config.build.client.splitting` (default `true`) | Shared modules move into a shared chunk; turning it off also disables grouping |
 | `format` | `esm` | `type="module"` scripts |
 | `target` | `chrome111`, `edge111`, `firefox111`, `safari16.4` | The lower bound of the ESM + dynamic import + `IntersectionObserver` island model; transpiling to anything older grows the output without winning a single visitor |
 | `minify` | `true` | — |
@@ -193,7 +194,26 @@ esbuild settings:
 | `legalComments` | `none` | — |
 
 The output lands under `public/assets/js/` and is cleaned first on every pass.
-`browserslist` is not read; the target list is hard-coded.
+`browserslist` is not read; the target list is hard-coded. The step line prints
+the total JS file count next to the entry count (`1 entry, 48 files`) so large
+chunk graphs are easier to spot.
+
+### Chunk grouping (`build.client.groups` / `chunkGroup`)
+
+esbuild has no native `manualChunks`. `build.client.groups` and
+`build.client.chunkGroup` are applied through a plugin:
+
+1. A matching import is redirected to a re-export wrapper.
+2. The wrapper side-effect-imports the `jskelet-group:<name>` barrel.
+3. The barrel statically imports every known member of the group (bare packages,
+   `.{js,ts,mts}` files under path prefixes, plus members discovered at resolve
+   time) — every entry that touches the group reaches the same member set and
+   one shared chunk is produced.
+
+**Trade-off:** tree-shaking inside a group weakens; a page that uses one member
+may download the rest of the group. The group name is a config key; the output
+file is usually still `chunks/chunk.<hash>.js`. Config reference:
+[07-configuration.md](./07-configuration.md#build).
 
 ### The `@/` alias
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "jskelet",
-  "version": "0.6.5",
+  "version": "0.6.6",
   "description": "A framework that feels like no framework: Express 5 + build-time .jsk SSR (optional EJS peer), vanilla JS islands, Tailwind v4 and an in-process HTML TTL cache.",
   "type": "module",
   "license": "MIT",

package/src/build/chunk-groups.mjs

@@ -0,0 +1,331 @@
+/**
+ * esbuild manualChunks karşılığı: `build.client.groups` / `chunkGroup`.
+ *
+ * esbuild native grup ataması sunmaz. Bir gruba düşen import, re-export
+ * sarmalayıcısı üzerinden gider; sarmalayıcı gruba ait barrel'ı side-effect
+ * olarak çeker. Barrel tüm bilinen üyeleri statik import eder — gruba
+ * dokunan entry'ler aynı üye kümesine ulaşır ve paylaşılan tek chunk oluşur.
+ *
+ * Bedel: grup içi tree-shaking zayıflar (webpack manualChunks ile aynı
+ * takas). `splitting: false` iken plugin hiç eklenmez.
+ */
+import fs from "node:fs";
+import path from "node:path";
+
+const GROUP_NS = "jskelet-group";
+const REEXPORT_NS = "jskelet-group-reexport";
+const GROUP_PREFIX = `${GROUP_NS}:`;
+
+/** Barrel / re-export sarmalayıcısının kendi import'ları tekrar sarılmasın. */
+const SKIP_NS = new Set([GROUP_NS, REEXPORT_NS]);
+
+/**
+ * @typedef {object} ChunkGroupOptions
+ * @property {string} root
+ * @property {Record<string, string[]>} groups
+ * @property {((id: string) => string | null | undefined) | null} [chunkGroup]
+ */
+
+/**
+ * Grup adı dosya yoluna uygun mu (`chunks/<name>.[hash]`).
+ *
+ * @param {string} name
+ * @returns {boolean}
+ */
+export function isSafeGroupName(name) {
+  return typeof name === "string" && /^[A-Za-z0-9_-]+$/.test(name);
+}
+
+/**
+ * Matcher'ın bare paket, `@/` veya göreli yol öneki olup olmadığını ayırır.
+ *
+ * @param {string} matcher
+ * @returns {"bare" | "path"}
+ */
+export function matcherKind(matcher) {
+  if (matcher.startsWith("./") || matcher.startsWith("../") || matcher.startsWith("@/")) {
+    return "path";
+  }
+  return "bare";
+}
+
+/**
+ * Yol önekini proje köküne göre mutlak dizin / dosya önekine çevirir.
+ *
+ * @param {string} root
+ * @param {string} matcher
+ * @returns {string}
+ */
+export function resolvePathMatcher(root, matcher) {
+  if (matcher.startsWith("@/")) {
+    return path.resolve(root, matcher.slice(2));
+  }
+  return path.resolve(root, matcher);
+}
+
+/**
+ * Bare paket: exact veya `pkg/...` alt yolu.
+ *
+ * @param {string} matcher
+ * @param {string} importPath
+ * @returns {boolean}
+ */
+export function matchBarePackage(matcher, importPath) {
+  return importPath === matcher || importPath.startsWith(`${matcher}/`);
+}
+
+/**
+ * Mutlak yol, matcher önekiyle başlıyor mu (dizin sınırı korunur).
+ *
+ * @param {string} absMatcher
+ * @param {string} absPath
+ * @returns {boolean}
+ */
+export function matchPathPrefix(absMatcher, absPath) {
+  const normalizedMatcher = path.resolve(absMatcher);
+  const normalizedPath = path.resolve(absPath);
+  if (normalizedPath === normalizedMatcher) return true;
+  const prefix = normalizedMatcher.endsWith(path.sep)
+    ? normalizedMatcher
+    : normalizedMatcher + path.sep;
+  return normalizedPath.startsWith(prefix);
+}
+
+/**
+ * Declarative path matcher altındaki `.{js,ts,mts}` dosyalarını listeler.
+ *
+ * @param {string} root
+ * @param {string} matcher
+ * @returns {string[]}
+ */
+export function listPathMatcherMembers(root, matcher) {
+  const base = resolvePathMatcher(root, matcher);
+  if (!fs.existsSync(base)) return [];
+
+  const stat = fs.statSync(base);
+  if (stat.isFile()) return [base];
+
+  /** @type {string[]} */
+  const out = [];
+  walkJsFiles(base, out);
+  return out;
+}
+
+/**
+ * @param {string} dir
+ * @param {string[]} out
+ */
+function walkJsFiles(dir, out) {
+  let entries;
+  try {
+    entries = fs.readdirSync(dir, { withFileTypes: true });
+  } catch {
+    return;
+  }
+  for (const entry of entries) {
+    const full = path.join(dir, entry.name);
+    if (entry.isDirectory()) {
+      if (entry.name === "node_modules" || entry.name === ".git") continue;
+      walkJsFiles(full, out);
+      continue;
+    }
+    if (!entry.isFile()) continue;
+    const ext = path.extname(entry.name);
+    if (ext === ".js" || ext === ".ts" || ext === ".mts" || ext === ".mjs") {
+      out.push(full);
+    }
+  }
+}
+
+/**
+ * Import yolu / çözümlenmiş dosya için grup adını bulur.
+ * `chunkGroup` hook'u `groups` map'inden önce gelir.
+ *
+ * @param {string} importPath
+ * @param {string | null} resolvedPath
+ * @param {ChunkGroupOptions} options
+ * @returns {string | null}
+ */
+export function resolveGroupName(importPath, resolvedPath, options) {
+  const { root, groups, chunkGroup } = options;
+
+  if (typeof chunkGroup === "function") {
+    for (const id of [resolvedPath, importPath].filter(Boolean)) {
+      try {
+        const result = chunkGroup(/** @type {string} */ (id));
+        if (typeof result === "string" && isSafeGroupName(result.trim())) {
+          return result.trim();
+        }
+      } catch (error) {
+        console.warn(
+          "[build] build.client.chunkGroup() threw, ignoring this module",
+          error,
+        );
+      }
+    }
+  }
+
+  for (const [name, matchers] of Object.entries(groups)) {
+    for (const matcher of matchers) {
+      if (matcherKind(matcher) === "bare") {
+        if (matchBarePackage(matcher, importPath)) return name;
+        continue;
+      }
+      const absMatcher = resolvePathMatcher(root, matcher);
+      if (resolvedPath && matchPathPrefix(absMatcher, resolvedPath)) return name;
+      if (
+        importPath.startsWith("./") ||
+        importPath.startsWith("../") ||
+        importPath.startsWith("@/")
+      ) {
+        // resolveDir bilinmeden göreli yolu kesinleştiremeyiz; @/ yeter.
+        if (importPath.startsWith("@/")) {
+          const absImport = path.resolve(root, importPath.slice(2));
+          if (matchPathPrefix(absMatcher, absImport)) return name;
+        }
+      }
+    }
+  }
+
+  return null;
+}
+
+/**
+ * @param {ChunkGroupOptions} options
+ * @returns {import('esbuild').Plugin | null}
+ */
+export function chunkGroupsPlugin(options) {
+  const { root, groups, chunkGroup } = options;
+  const hasGroups = Object.keys(groups).length > 0;
+  if (!hasGroups && typeof chunkGroup !== "function") return null;
+
+  /** @type {Map<string, Set<string>>} */
+  const members = new Map();
+
+  for (const name of Object.keys(groups)) {
+    if (!isSafeGroupName(name)) continue;
+    members.set(name, new Set());
+  }
+
+  // Declarative matcher'lardan bilinen üyeleri önceden doldur.
+  for (const [name, matchers] of Object.entries(groups)) {
+    if (!isSafeGroupName(name)) continue;
+    const set = members.get(name) ?? new Set();
+    members.set(name, set);
+    for (const matcher of matchers) {
+      if (matcherKind(matcher) === "bare") {
+        set.add(matcher);
+      } else {
+        for (const file of listPathMatcherMembers(root, matcher)) {
+          set.add(file);
+        }
+      }
+    }
+  }
+
+  /**
+   * @param {string} group
+   * @param {string} member
+   */
+  function addMember(group, member) {
+    if (!isSafeGroupName(group)) return;
+    let set = members.get(group);
+    if (!set) {
+      set = new Set();
+      members.set(group, set);
+    }
+    set.add(member);
+  }
+
+  return {
+    name: "jskelet-chunk-groups",
+    setup(build) {
+      build.onResolve({ filter: /.*/ }, async (args) => {
+        if (args.pluginData?.jskeletChunkGroupSkip) return undefined;
+
+        // Re-export sarmalayıcısı ve entry `jskelet-group:name` ister; namespace
+        // SKIP olsa bile bu specifier'ı biz çözmeliyiz.
+        if (args.path.startsWith(GROUP_PREFIX)) {
+          const name = args.path.slice(GROUP_PREFIX.length);
+          if (!isSafeGroupName(name)) return undefined;
+          if (!members.has(name)) members.set(name, new Set());
+          return { path: name, namespace: GROUP_NS };
+        }
+
+        // Barrel / re-export içindeki gerçek üye import'ları tekrar sarılmasın.
+        if (SKIP_NS.has(args.namespace)) return undefined;
+
+        // data:/http: vb. ve entry-point'leri dokunma.
+        if (args.kind === "entry-point") return undefined;
+        if (/^[a-zA-Z][a-zA-Z\d+.-]*:/.test(args.path)) return undefined;
+
+        // Önce hook / bare matcher ile ucuz eşleşme; path önekleri resolve ister.
+        let group = resolveGroupName(args.path, null, options);
+
+        const resolved = await build.resolve(args.path, {
+          importer: args.importer,
+          namespace: args.namespace,
+          resolveDir: args.resolveDir,
+          kind: args.kind,
+          pluginData: { jskeletChunkGroupSkip: true },
+        });
+
+        if (resolved.errors?.length || !resolved.path) {
+          return undefined;
+        }
+
+        // Virtual / zaten bizim namespace.
+        if (resolved.namespace && SKIP_NS.has(resolved.namespace)) {
+          return undefined;
+        }
+
+        group = resolveGroupName(args.path, resolved.path, options) ?? group;
+        if (!group) return undefined;
+
+        // Üye olarak çözümlenmiş yolu yaz — barrel aynı dosyayı çeker.
+        addMember(group, resolved.path);
+
+        return {
+          path: `${group}::${resolved.path}`,
+          namespace: REEXPORT_NS,
+        };
+      });
+
+      build.onLoad({ filter: /.*/, namespace: GROUP_NS }, (args) => {
+        const set = members.get(args.path) ?? new Set();
+        const lines = [...set].map((member) => `import ${JSON.stringify(member)};`);
+        return {
+          contents: lines.length ? `${lines.join("\n")}\n` : "export {}\n",
+          resolveDir: root,
+          loader: "js",
+        };
+      });
+
+      build.onLoad({ filter: /.*/, namespace: REEXPORT_NS }, (args) => {
+        const sep = args.path.indexOf("::");
+        if (sep === -1) {
+          return { contents: "export {}\n", loader: "js" };
+        }
+        const group = args.path.slice(0, sep);
+        const target = args.path.slice(sep + 2);
+        const targetLit = JSON.stringify(target);
+        const groupLit = JSON.stringify(`${GROUP_PREFIX}${group}`);
+
+        // Side-effect barrel + re-export. Named-only modüllerde
+        // `__ns.default` undefined olur (uyarı → logOverride ile susturulur);
+        // `export { default } from` ise hard error verdiği için kullanılmaz.
+        return {
+          contents: `
+import ${groupLit};
+import * as __ns from ${targetLit};
+export * from ${targetLit};
+export default __ns.default;
+`,
+          resolveDir: root,
+          loader: "js",
+        };
+      });
+    },
+  };
+}
+

package/src/build/tasks/client.mjs

@@ -15,6 +15,7 @@ import fs from "node:fs";
 import path from "node:path";
 import process from "node:process";
 import * as esbuild from "esbuild";
+import { chunkGroupsPlugin } from "../chunk-groups.mjs";
 import { paths, patchManifest, pruneAssets } from "../paths.mjs";
 import * as log from "../../log.mjs";
 
@@ -187,13 +188,34 @@ export async function buildClient(config, { watch = false } = {}) {
     .split(path.sep)
     .join("/");
 
+  const clientBuild = config.build?.client ?? {
+    splitting: true,
+    groups: {},
+    chunkGroup: null,
+  };
+  const splitting = clientBuild.splitting !== false;
+  const groups = splitting ? (clientBuild.groups ?? {}) : {};
+  const chunkGroup = splitting ? (clientBuild.chunkGroup ?? null) : null;
+
+  const groupPlugin = splitting
+    ? chunkGroupsPlugin({
+        root: config.root,
+        groups,
+        chunkGroup,
+      })
+    : null;
+
+  /** @type {esbuild.Plugin[]} */
+  const plugins = [aliasPlugin(config.root)];
+  if (groupPlugin) plugins.push(groupPlugin);
+
   /** @type {esbuild.BuildOptions} */
   const options = {
     entryPoints,
     outdir: outDir,
     absWorkingDir: config.root,
     bundle: true,
-    splitting: true,
+    splitting,
     format: "esm",
     target: ["chrome111", "edge111", "firefox111", "safari16.4"],
     minify: true,
@@ -203,10 +225,15 @@ export async function buildClient(config, { watch = false } = {}) {
     entryNames: "[name].[hash]",
     chunkNames: "chunks/[name].[hash]",
     legalComments: "none",
-    plugins: [aliasPlugin(config.root)],
+    plugins,
     define: {
       "process.env": JSON.stringify(publicEnv(config.clientEnv)),
     },
+    // Grup sarmalayıcısı her üyede `export { default }` yazar; named-only
+    // modüllerde bu uyarı gürültü — davranış yine doğru (default undefined).
+    ...(groupPlugin
+      ? { logOverride: { "import-is-undefined": "silent" } }
+      : {}),
   };
 
   if (watch) {
@@ -218,8 +245,7 @@ export async function buildClient(config, { watch = false } = {}) {
     await context.watch();
     writeMetafile(result.metafile);
     const manifest = toManifest(result.metafile, config, entryRoot);
-    const entries = Object.keys(manifest).length;
-    log.detail(`${entries} ${entries === 1 ? "entry" : "entries"}`);
+    log.detail(summarizeClientBuild(manifest, result.metafile));
     return manifest;
   }
 
@@ -230,11 +256,32 @@ export async function buildClient(config, { watch = false } = {}) {
     (sum, output) => sum + output.bytes,
     0,
   );
-  const entries = Object.keys(manifest).length;
-  log.detail(`${entries} ${entries === 1 ? "entry" : "entries"}, ${log.size(bytes)}`);
+  log.detail(
+    `${summarizeClientBuild(manifest, result.metafile)}, ${log.size(bytes)}`,
+  );
   return manifest;
 }
 
+/**
+ * Entry + inject edilen group entry'ler metafile'da durur; teşhis için
+ * hem gerçek manifest entry sayısını hem toplam çıktı dosyasını yaz.
+ *
+ * @param {Record<string, string>} manifest
+ * @param {esbuild.Metafile} [metafile]
+ * @returns {string}
+ */
+function summarizeClientBuild(manifest, metafile) {
+  const entries = Object.keys(manifest).length;
+  const entryLabel = `${entries} ${entries === 1 ? "entry" : "entries"}`;
+  if (!metafile) return entryLabel;
+
+  const outputs = Object.keys(metafile.outputs).filter(
+    (file) => file.endsWith(".js") || file.endsWith(".mjs"),
+  );
+  const chunks = outputs.length;
+  return `${entryLabel}, ${chunks} ${chunks === 1 ? "file" : "files"}`;
+}
+
 /**
  * Metafile diske yazılır: dev panelindeki chunk analizi giriş/çıkış
  * kırılımını buradan okur. Çalışma zamanı bu dosyaya bağımlı değildir.

package/src/config/defaults.js

@@ -470,6 +470,31 @@ export const DEFAULT_SECURITY = {
   },
 };
 
+/**
+ * Client bundle (esbuild) ayarları.
+ *
+ * `groups` / `chunkGroup` esbuild'in native manualChunks'ı olmadığı için
+ * framework plugin'i ile uygulanır — ayrıntı `src/build/chunk-groups.mjs`.
+ */
+export const DEFAULT_BUILD = {
+  client: {
+    /** esbuild `splitting`; kapalıyken gruplama yok sayılır. */
+    splitting: true,
+    /**
+     * İsim → matcher listesi. Bare paket (`chart.js`), yol öneki
+     * (`./client/chrome/`) veya `@/` öneki.
+     * @type {Record<string, string[]>}
+     */
+    groups: {},
+    /**
+     * Modül kimliğini (mutlak yol veya bare specifier) grup adına map eder.
+     * `groups` ile çakışınca hook kazanır.
+     * @type {((id: string) => string | null | undefined) | null}
+     */
+    chunkGroup: null,
+  },
+};
+
 /**
  * Build-zamanı görsel adımı + opsiyonel runtime uzak görsel proxy.
  *

package/src/config/index.js

@@ -47,6 +47,7 @@ import {
   ON_VISIT_CONCURRENCY_CEILING,
   ON_VISIT_PER_PAGE_CEILING,
   ON_VISIT_RPS_CEILING,
+  DEFAULT_BUILD,
   DEFAULT_IMAGES,
   DEFAULT_LOGS,
   DEFAULT_NAVIGATION,
@@ -160,6 +161,17 @@ const CONFIG_FILE = "jskelet.config.mjs";
  * @property {{ scan?: string[], dir: string } | false} icons
  * @property {ImagesConfig | false} images
  * @property {string[]} clientEnv Client bundle'a gömülecek env anahtarları.
+ * @property {BuildConfig} build Client bundling (esbuild splitting / chunk groups).
+ */
+
+/**
+ * @typedef {object} BuildClientConfig
+ * @property {boolean} splitting
+ * @property {Record<string, string[]>} groups
+ * @property {((id: string) => string | null | undefined) | null} chunkGroup
+ *
+ * @typedef {object} BuildConfig
+ * @property {BuildClientConfig} client
  */
 
 /**
@@ -1139,6 +1151,118 @@ function normalizeSecurity(raw) {
   };
 }
 
+/**
+ * Client build ayarları (`build.client`). Bozuk tipler uyarıyla varsayılana düşer.
+ *
+ * @param {unknown} raw
+ * @returns {BuildConfig}
+ */
+export function normalizeBuild(raw) {
+  if (raw == null) {
+    return {
+      client: {
+        splitting: DEFAULT_BUILD.client.splitting,
+        groups: {},
+        chunkGroup: null,
+      },
+    };
+  }
+
+  if (typeof raw !== "object" || Array.isArray(raw)) {
+    console.warn("[config] build must be an object, ignoring it");
+    return {
+      client: {
+        splitting: DEFAULT_BUILD.client.splitting,
+        groups: {},
+        chunkGroup: null,
+      },
+    };
+  }
+
+  const source = /** @type {Record<string, any>} */ (raw);
+  const clientRaw = source.client;
+
+  if (clientRaw == null) {
+    return {
+      client: {
+        splitting: DEFAULT_BUILD.client.splitting,
+        groups: {},
+        chunkGroup: null,
+      },
+    };
+  }
+
+  if (typeof clientRaw !== "object" || Array.isArray(clientRaw)) {
+    console.warn("[config] build.client must be an object, ignoring it");
+    return {
+      client: {
+        splitting: DEFAULT_BUILD.client.splitting,
+        groups: {},
+        chunkGroup: null,
+      },
+    };
+  }
+
+  const client = /** @type {Record<string, any>} */ (clientRaw);
+  const splitting = client.splitting !== false;
+
+  /** @type {Record<string, string[]>} */
+  const groups = {};
+  if (client.groups != null) {
+    if (typeof client.groups !== "object" || Array.isArray(client.groups)) {
+      console.warn("[config] build.client.groups must be an object, ignoring it");
+    } else {
+      for (const [name, matchers] of Object.entries(client.groups)) {
+        if (!isSafeGroupName(name)) {
+          console.warn(
+            `[config] build.client.groups key "${name}" is invalid ` +
+              "(use letters, digits, _ or -); skipping",
+          );
+          continue;
+        }
+        const list = asArray(matchers, `build.client.groups.${name}`)
+          .filter((entry) => typeof entry === "string" && entry.trim())
+          .map((entry) => String(entry).trim());
+        if (list.length) groups[name] = list;
+      }
+    }
+  }
+
+  /** @type {((id: string) => string | null | undefined) | null} */
+  let chunkGroup = null;
+  if (client.chunkGroup != null) {
+    if (typeof client.chunkGroup === "function") {
+      chunkGroup = client.chunkGroup;
+    } else {
+      console.warn(
+        "[config] build.client.chunkGroup must be a function, ignoring it",
+      );
+    }
+  }
+
+  if (
+    !splitting &&
+    (Object.keys(groups).length > 0 || chunkGroup)
+  ) {
+    console.warn(
+      "[config] build.client.groups / chunkGroup require splitting; " +
+        "they are ignored while splitting is false",
+    );
+  }
+
+  return { client: { splitting, groups, chunkGroup } };
+}
+
+/**
+ * Chunk dosya adına güvenli grup adı.
+ *
+ * @param {string} name
+ * @returns {boolean}
+ */
+function isSafeGroupName(name) {
+  return typeof name === "string" && /^[A-Za-z0-9_-]+$/.test(name);
+}
+
 /**
  * İkon sprite ayarları. `false` → adım atlanır. `dir` varsayılanı `"icons"`:
  * o dizin varsa yalnızca yerel SVG'ler; yoksa Phosphor.
@@ -1423,6 +1547,7 @@ export async function loadConfig(options = {}) {
     icons: normalizeIcons(source.icons),
     images: normalizeImages(source.images),
     clientEnv: source.clientEnv ?? [],
+    build: normalizeBuild(source.build),
   };
 
   if (

package/types/config/defaults.d.ts

@@ -420,6 +420,30 @@ export declare const DEFAULT_SECURITY: {
         headerName: string;
     };
 };
+/**
+ * Client bundle (esbuild) ayarları.
+ *
+ * `groups` / `chunkGroup` esbuild'in native manualChunks'ı olmadığı için
+ * framework plugin'i ile uygulanır — ayrıntı `src/build/chunk-groups.mjs`.
+ */
+export declare const DEFAULT_BUILD: {
+    client: {
+        /** esbuild `splitting`; kapalıyken gruplama yok sayılır. */
+        splitting: boolean;
+        /**
+         * İsim → matcher listesi. Bare paket (`chart.js`), yol öneki
+         * (`./client/chrome/`) veya `@/` öneki.
+         * @type {Record<string, string[]>}
+         */
+        groups: Record<string, string[]>;
+        /**
+         * Modül kimliğini (mutlak yol veya bare specifier) grup adına map eder.
+         * `groups` ile çakışınca hook kazanır.
+         * @type {((id: string) => string | null | undefined) | null}
+         */
+        chunkGroup: ((id: string) => string | null | undefined) | null;
+    };
+};
 /**
  * Build-zamanı görsel adımı + opsiyonel runtime uzak görsel proxy.
  *

package/types/config/index.d.ts

@@ -220,6 +220,18 @@ export type ResolvedConfig = {
      * Client bundle'a gömülecek env anahtarları.
      */
     clientEnv: string[];
+    /**
+     * Client bundling (esbuild splitting / chunk groups).
+     */
+    build: BuildConfig;
+};
+export type BuildClientConfig = {
+    splitting: boolean;
+    groups: Record<string, string[]>;
+    chunkGroup: ((id: string) => string | null | undefined) | null;
+};
+export type BuildConfig = {
+    client: BuildClientConfig;
 };
 export type ImagesRemoteConfig = {
     enabled: boolean;
@@ -279,6 +291,13 @@ export type SecurityConfig = {
         headerName: string;
     };
 };
+/**
+ * Client build ayarları (`build.client`). Bozuk tipler uyarıyla varsayılana düşer.
+ *
+ * @param {unknown} raw
+ * @returns {BuildConfig}
+ */
+export declare function normalizeBuild(raw: unknown): BuildConfig;
 /**
  * Config'i okur, normalize eder ve modül durumuna yazar. Sunucu ve build
  * süreçleri açılışta bir kez çağırır.