feat: add extra dist folders control and generate clientlibs for SplitChunks by infloent · Pull Request #145 · Netcentric/fe-build

infloent · 2026-05-29T13:26:39Z

Description

The solution It does not enforce any source folder structure
It allows for a different source (less folder nesting) vs dist folder structure.

Currently source and dist folder structure must be mirrors.
Now a source folder can not contains more than one entrypoint file of type js or scss because of AEM requirement on the dist side where each clientlib needs it’s own folder with it's own .xml, .txt files.

This will fix this limitation and allow to have multiple entrypoints in the same source folder but generate extra dist folders as required for AEM clientlibs categories.

New options

All would default to false / []. Existing projects would be unaffected unless they opt in.

Filename-based dist folders (config.general)

Option	What it does
`sourceKey: string or string[]`	Match one or multiple source suffixes (e.g. `'clientlibs'` or `['clientlibs', 'publishlibs', 'authorlibs']`)
`sourceKeyAsDistFolder: true`	Promote the matched sourceKey suffix to a dist subfolder
`fileNameDotSuffixesAsDistFolder: true`	Promote dot-segments between name and sourceKey suffix to dist subfolders
`excludeFileNameDotSuffixes: string[]`	Opt specific values out of folder promotion. Supports exact strings and regular expressions (migration safety valve)

Split chunks clientlibs (config.clientlibs)

Option	What it does
`generateSplitChunksClientlibs: true`	Auto-generate `.content.xml` + `js.txt` for webpack `splitChunks` / `runtimeChunk` output folders

This would be independent of the filename-based flags above. checkChunk would also expose module.resource (the full file path including filename) to splitChunks cache group test functions, making it possible to also route files by name convention into dedicated chunk groups.

The idea

All files for a component live in one folder (not mandatory). One ls returns the complete picture of what it does and how it splits, useful for developers navigating the codebase and for AI tools that rely on directory context to understand component scope.

When an AI needs context to fix or extend a component, one directory read is enough instead of correlating multiple parallel trees, which means fewer tool calls and less context consumed.

With this options

sourceKey: ['clientlibs', 'publishlibs', 'authorlibs'],
sourceKeyAsDistFolder: true,
fileNameDotSuffixesAsDistFolder: true,
excludeFileNameDotSuffixes: ['clientlibs']

And this example source structure (not a requirement)

src/components/cmp/v1/cmp/
  cmp.main.publishlibs.js       ← The main cmp functionality
  cmp.main.publishlibs.scss     ← The default cmp styles
  cmp.main.authorlibs.js        ← The main cmp author functionality when needed
  cmp.main.authorlibs.scss.     ← The default cmp author styles overwrites
  cmp.layout1.publishlibs.scss  ← loaded only when needed based on cmp config
  cmp.layout1.authorlibs.scss   ← some layout/feature might need author css overwrites
  cmp.layout2.publishlibs.scss  ← loaded only when needed based on cmp config
  cmp.tracking.clientlibs.js    ← loaded if tracking is enabled
  cmp.dialog.clientlibs.js       ← loaded as extra clientlib in dialog
  cmp.dialog.clientlibs.scss     ← loaded as extra clientlib in dialog
  cmp.editor.clientlibs.scss     ← custom granite editor toolbars widgets

The generated dist structure will be:

dist/components/cmp/v1/cmp
  main/
    publishlibs/
      .content.xml
      js.txt
      css.txt
      cmp.bundle.js
      cmp.bundle.css
    authorlibs/
      .content.xml
      js.txt
      css.txt
      cmp.bundle.js
      cmp.bundle.css
  layout1/
    publishlibs/
      .content.xml
      css.txt
      cmp.layout1.bundle.css
    authorlibs/
      .content.xml
      css.txt
      cmp.layout1.bundle.css
  layout2/
    publishlibs/
      .content.xml
      css.txt
      cmp.layout2.bundle.css
  tracking/
    .content.xml
    js.txt
    cmp.tracking.bundle.js
  dialog/
    .content.xml
    js.txt
    css.txt
    cmp.dialog.bundle.js
    cmp.dialog.bundle.css
  editor/
    .content.xml
    css.txt
    cmp.editor.bundle.css

Related Issue

Fixes: Update chokidar usage to support v4 (glob patterns removal) -> as a prerequisite.

Fixes: Flexible source vs dist folders/clientlibs management

Types of changes

Bug fix (non-breaking change which fixes an issue)
New feature (non-breaking change which adds functionality)
Breaking change (fix or feature that would cause existing functionality to change)

Checklist:

My code follows the code style of this project.
I have read the CONTRIBUTING document.
All new and existing tests passed.

easingthemes

Nice feature — backward-compatible defaults hold up (verified the default-config path is preserved) and the fixtures/tests are thorough. A few correctness issues surface once the new opt-in flags are used, plus one watch-mode regression that affects the default workflow. Details inline.

easingthemes · 2026-05-29T14:11:28Z


-          const destFile = path.join(relativePath, fileName)
+      // Build reverse map: absolute src path -> dest key
+      const srcToDest = Object.fromEntries(


multiple: false projects get garbage dest keys in watch.

generateEntries only returns the {dest: src} object when config.general.multiple is true; otherwise it returns a plain array of source paths. Object.entries(array) then yields [index, srcPath], so srcToDest becomes { srcPath: "0", ... } and renderStyles(file, "0", config) is called with a numeric index as the dest.

Default config is multiple: true, so this only bites projects that override it — but the old watch code didn't use generateEntries and worked regardless, so it's a new regression. A guard for the array shape (or normalizing generateEntries output) would fix it.

easingthemes · 2026-05-29T14:11:28Z


-          renderStyles(file, destFile, config)
-        });
+      watcher.on('all', (event, file) => {


unlink events run the full Sass pipeline on a deleted file.

on('all', ...) fires for unlink/addDir/etc. On unlink the deleted path is still a key in srcToDest, so the if (!destFile) return guard doesn't short-circuit and renderStyles runs against a now-missing file (noisy error / wasted work). Suggest filtering: if (event !== 'add' && event !== 'change') return;.

easingthemes · 2026-05-29T14:11:28Z

+      : []),
+  ];
+
+  const distFileNameParts = [prefix, ...featureSegments, bundleKey, ext];


Silent entry loss when two files collapse to the same dest key.

The matched sourceKey is dropped from both the folder list (only added when sourceKeyAsDistFolder is true, lines 30-32) and the filename (distFileNameParts here is prefix + featureSegments + bundleKey + ext, never the sourceKey). So two files differing only by their sourceKey suffix produce an identical destFile, and sources[destFile] = ... (line 52) silently overwrites the first — no warning.

Reachable via documented opt-in combos:

sourceKey: ['publishlibs','authorlibs'] + fileNameDotSuffixesAsDistFolder: true + sourceKeyAsDistFolder: false: cmp.main.publishlibs.js and cmp.main.authorlibs.js both → main/cmp.main.bundle.js.

Even with sourceKeyAsDistFolder: true, if excludeFileNameDotSuffixes lists those sourceKey values, they re-collapse.

The new test at utils/generateEntries.test.js:112-116 actually asserts this collapse (4 files → 2 entries) as expected. Recommend detecting duplicate destFile keys in the loop (line 50-53) and throwing/warning instead of silently dropping.

easingthemes · 2026-05-29T14:11:28Z

+        );
+      } else {
+        const [chunkName] = chunks;
+        const { name, folder, fileName, extension } = getClientlib(chunkName);


A chunk name with no directory writes a malformed clientlib into the dist root.

If a chunk name has no / (e.g. runtimeChunk: { name: 'runtime' }), getClientlib returns folder='.', name='.', extension='runtime' (split('.').pop() on a dotless string). renderClientLibs then does path.join(destinationPath, '.') and writes .content.xml straight into dist/ with category myproj.., while no js.txt is emitted (the runtime extension field is never read). A single dotless/dirless chunk also slips past the collision check below (everything maps to '.').

Suggest validating path.dirname(chunkName) !== '.' and that the name has a real .js/.css extension before registering. (Default config is safe — verified runtime + treeshaking share commons/treeshaking.bundle.js, so commons/ trips the >1 warning and is skipped.)

easingthemes · 2026-05-29T14:11:28Z

+        if (!clientLibs[folder]) {
+          clientLibs[folder] = { name, folder };
+        }
+        clientLibs[folder][extension] = fileName;


Split-chunk clientlib can silently overwrite a source-derived js/scss field.

This writes into the same clientLibs[folder] map populated by regular source entries above (keyed only by folder + extension). If a user chunk resolves to a folder already produced by a real entry (e.g. commons/foo.bundle.js), this line replaces that folder's js, dropping the original from js.txt. Consider detecting when clientLibs[folder] already came from a source entry and warning/skipping rather than merging by reference.

easingthemes · 2026-05-29T14:11:28Z

+// (uses mod.resource first, falls back to mod.context).
+module.exports = function checkChunk(moduleOrPath, excludes = [], includes = []) {
+  const module = (moduleOrPath && typeof moduleOrPath === 'object')
+    ? (moduleOrPath.resource || moduleOrPath.context || null)


Minor: switching mod.context → mod.resource || mod.context widens the excludedFromVendors (['babel','core-js']) substring match from the directory to the full file path including filename. Harmless for project source (the node_modules gate protects it), but it can misclassify individual files inside node_modules whose filenames contain those tokens. Worth a brief comment noting the intent.

Florin Raducan added 3 commits May 25, 2026 16:55

feat: add test source files

88b3df5

feat: Add file name to dist folders segments

f7573ea

docs: update docs for excludeFileNameDotSuffixes option

68ad0c3

infloent requested a review from easingthemes May 29, 2026 13:26

build: update package-lock file

bfb2196

easingthemes reviewed May 29, 2026

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat: add extra dist folders control and generate clientlibs for SplitChunks#145

feat: add extra dist folders control and generate clientlibs for SplitChunks#145
infloent wants to merge 4 commits into
Netcentric:mainfrom
infloent:feature/extra-dist-folders-control

infloent commented May 29, 2026

Uh oh!

easingthemes left a comment

Uh oh!

Uh oh!

easingthemes May 29, 2026

Uh oh!

easingthemes May 29, 2026

Uh oh!

easingthemes May 29, 2026

Uh oh!

easingthemes May 29, 2026

Uh oh!

easingthemes May 29, 2026

Uh oh!

easingthemes May 29, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Conversation

infloent commented May 29, 2026

Description

New options

The idea

Related Issue

Types of changes

Checklist:

Uh oh!

easingthemes left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

easingthemes May 29, 2026

Choose a reason for hiding this comment

Uh oh!

easingthemes May 29, 2026

Choose a reason for hiding this comment

Uh oh!

easingthemes May 29, 2026

Choose a reason for hiding this comment

Uh oh!

easingthemes May 29, 2026

Choose a reason for hiding this comment

Uh oh!

easingthemes May 29, 2026

Choose a reason for hiding this comment

Uh oh!

easingthemes May 29, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants