feat(webpack): add webpackFilesystemCache for production builds

ak-seek · ak-seek · commit 53fbb7edae9b · 2026-04-17T10:31:21.000+10:00
Allow opting in to Webpack filesystem cache for sku build / build-ssr and CI via sku.config or SKU_WEBPACK_FILESYSTEM_CACHE. Default remains development-only (dev server).

Made-with: Cursor
diff --git a/.changeset/webpack-filesystem-cache-config.md b/.changeset/webpack-filesystem-cache-config.md
@@ -0,0 +1,5 @@
+---
+'sku': minor
+---
+
+`webpack`: Add `webpackFilesystemCache` (`'development' | 'always'`) so production builds (`sku build` / `sku build-ssr`) and CI can opt in to Webpack filesystem caching. Override with `SKU_WEBPACK_FILESYSTEM_CACHE`. Default remains `'development'` (cache only for the local dev server).
diff --git a/docs/docs/configuration.md b/docs/docs/configuration.md
@@ -492,6 +492,16 @@ Unfortunately, these kinds of imports only work for apps. In packages, the impor
 
 You can set this option in `sku.config.js`, or adding `"skuCompilePackage": true` to your `package.json` will disable this behaviour by default.
 
+## webpackFilesystemCache
+
+Type: `'development' | 'always'`
+
+Default: `'development'`
+
+Bundler: `webpack`
+
+Controls Webpack’s [filesystem cache](https://webpack.js.org/configuration/cache/#cachetype). With `'development'`, the cache is used only for the local dev server. Set to `'always'` to also use it for production builds and in CI (unless `SKU_DISABLE_CACHE` is set). Override with `SKU_WEBPACK_FILESYSTEM_CACHE=development` or `SKU_WEBPACK_FILESYSTEM_CACHE=always`. See [Caching](./extra-features?id=caching) for Docker and CI notes.
+
 ## routes
 
 Type: `Array<string | {route: string, name: string, entry: string, languages: Array<string>}>`
diff --git a/docs/docs/extra-features.md b/docs/docs/extra-features.md
@@ -156,12 +156,16 @@ export default {
 ### [Webpack filesystem cache]
 
 This cache stores generated webpack modules and chunks.
-It is only emitted during local development.
-Its purpose is to reduce the time it takes to start the local development server.
+By default (`webpackFilesystemCache: 'development'` in `sku.config.ts`), it is only used for the local development server (`sku start` / `sku start-ssr`).
+
+Set `webpackFilesystemCache: 'always'` to also enable it for `sku build` / `sku build-ssr` (including in CI), unless `SKU_DISABLE_CACHE` is set. You can override the config with `SKU_WEBPACK_FILESYSTEM_CACHE=development` or `SKU_WEBPACK_FILESYSTEM_CACHE=always`.
+
+In Docker or Buildkite, pair `'always'` with a [BuildKit cache mount] on `node_modules/.cache/webpack` so the cache persists between image builds on the same agents.
 
 > This cache is stored in `node_modules/.cache/webpack` and can be safely deleted at any time.
 
 [webpack filesystem cache]: https://webpack.js.org/configuration/cache/#cachetype
+[BuildKit cache mount]: https://docs.docker.com/build/cache/optimize/#use-cache-mounts
 
 ### [`babel-loader` cache]
 
diff --git a/packages/sku/src/context/configSchema.ts b/packages/sku/src/context/configSchema.ts
@@ -197,6 +197,11 @@ export default validator.compile({
   rootResolution: {
     type: 'boolean',
   },
+  webpackFilesystemCache: {
+    type: 'enum',
+    values: ['development', 'always'],
+    optional: true,
+  },
   languages: languagesToCompile,
   skipPackageCompatibilityCompilation: {
     type: 'array',
diff --git a/packages/sku/src/context/createSkuContext.ts b/packages/sku/src/context/createSkuContext.ts
@@ -1,4 +1,9 @@
-import type { SkuConfig, SkuRoute, SkuRouteObject } from '../types/types.js';
+import type {
+  SkuConfig,
+  SkuRoute,
+  SkuRouteObject,
+  WebpackFilesystemCacheMode,
+} from '../types/types.js';
 import { getPathFromCwd, requireFromCwd } from '@sku-private/utils';
 import { existsSync } from 'node:fs';
 import defaultSkuConfig from './defaultSkuConfig.js';
@@ -257,6 +262,13 @@ export const createSkuContext = ({
     skuConfig.skipPackageCompatibilityCompilation;
   const externalizeNodeModules = skuConfig.externalizeNodeModules;
 
+  const envWebpackFilesystemCache = process.env.SKU_WEBPACK_FILESYSTEM_CACHE;
+  const webpackFilesystemCache: WebpackFilesystemCacheMode =
+    envWebpackFilesystemCache === 'always' ||
+    envWebpackFilesystemCache === 'development'
+      ? envWebpackFilesystemCache
+      : skuConfig.webpackFilesystemCache ?? 'development';
+
   const tsPaths =
     skuConfig.bundler === 'vite' || skuConfig.testRunner === 'vitest'
       ? generateTypeScriptPaths(skuConfig.pathAliases)
@@ -314,6 +326,7 @@ export const createSkuContext = ({
     cspExtraScriptSrcHosts,
     httpsDevServer,
     rootResolution,
+    webpackFilesystemCache,
     languages,
     initialPath,
     transformOutputPath: skuConfig.transformOutputPath,
diff --git a/packages/sku/src/context/defaultSkuConfig.ts b/packages/sku/src/context/defaultSkuConfig.ts
@@ -44,6 +44,7 @@ export default {
   httpsDevServer: false,
   devServerMiddleware: undefined,
   rootResolution: !isCompilePackage,
+  webpackFilesystemCache: 'development',
   languages: undefined,
   skipPackageCompatibilityCompilation: [],
   externalizeNodeModules: false,
diff --git a/packages/sku/src/index.ts b/packages/sku/src/index.ts
@@ -3,4 +3,5 @@ export type {
   RenderCallbackParams,
   Server,
   SkuConfig,
+  WebpackFilesystemCacheMode,
 } from './types/types.js';
diff --git a/packages/sku/src/services/webpack/config/cache.ts b/packages/sku/src/services/webpack/config/cache.ts
@@ -1,25 +1,41 @@
 import isCI from '../../../utils/isCI.js';
 import type { SkuContext } from '../../../context/createSkuContext.js';
+import type { WebpackFilesystemCacheMode } from '../../../types/types.js';
 
 const disableCacheOverride = Boolean(process.env.SKU_DISABLE_CACHE);
 
 function getWebpackCacheSettings({
   isDevServer,
   paths,
+  webpackFilesystemCache,
 }: {
   isDevServer: boolean;
   paths: SkuContext['paths'];
+  webpackFilesystemCache: WebpackFilesystemCacheMode;
 }) {
-  if (isDevServer && !isCI && !disableCacheOverride) {
-    return {
-      type: 'filesystem',
-      buildDependencies: {
-        config: paths.appSkuConfigPath ? [paths.appSkuConfigPath] : [],
-      },
-    };
+  if (disableCacheOverride) {
+    return false;
   }
 
-  return false;
+  if (webpackFilesystemCache === 'development') {
+    if (isDevServer && !isCI) {
+      return {
+        type: 'filesystem' as const,
+        buildDependencies: {
+          config: paths.appSkuConfigPath ? [paths.appSkuConfigPath] : [],
+        },
+      };
+    }
+
+    return false;
+  }
+
+  return {
+    type: 'filesystem' as const,
+    buildDependencies: {
+      config: paths.appSkuConfigPath ? [paths.appSkuConfigPath] : [],
+    },
+  };
 }
 
 export default getWebpackCacheSettings;
diff --git a/packages/sku/src/services/webpack/config/webpack.config.ssr.ts b/packages/sku/src/services/webpack/config/webpack.config.ssr.ts
@@ -51,6 +51,7 @@ const makeWebpackConfig = ({
     skipPackageCompatibilityCompilation,
     externalizeNodeModules,
     sourceMapsProd,
+    webpackFilesystemCache,
   } = skuContext;
   const isProductionBuild = process.env.NODE_ENV === 'production';
   const webpackMode = isProductionBuild ? 'production' : 'development';
@@ -94,7 +95,11 @@ const makeWebpackConfig = ({
         filename: `${fileMask}.js`,
         chunkFilename: `${fileMask}.js`,
       },
-      cache: getCacheSettings({ isDevServer, paths }),
+      cache: getCacheSettings({
+        isDevServer,
+        paths,
+        webpackFilesystemCache,
+      }),
       optimization: {
         nodeEnv: process.env.NODE_ENV,
         minimize: isProductionBuild,
@@ -248,7 +253,11 @@ const makeWebpackConfig = ({
         hotUpdateChunkFilename: `[id].[fullhash].hot-update.${type === 'module' ? 'c' : ''}js`,
         library: { name: 'server', type: 'var' },
       },
-      cache: getCacheSettings({ isDevServer, paths }),
+      cache: getCacheSettings({
+        isDevServer,
+        paths,
+        webpackFilesystemCache,
+      }),
       optimization: {
         nodeEnv: process.env.NODE_ENV,
         emitOnErrors: isProductionBuild,
diff --git a/packages/sku/src/services/webpack/config/webpack.config.ts b/packages/sku/src/services/webpack/config/webpack.config.ts
@@ -56,6 +56,7 @@ const makeWebpackConfig = ({
     skipPackageCompatibilityCompilation,
     externalizeNodeModules,
     sourceMapsProd,
+    webpackFilesystemCache,
   } = skuContext;
   const isProductionBuild = process.env.NODE_ENV === 'production';
 
@@ -134,7 +135,11 @@ const makeWebpackConfig = ({
             }
           : {}),
       },
-      cache: getCacheSettings({ isDevServer, paths }),
+      cache: getCacheSettings({
+        isDevServer,
+        paths,
+        webpackFilesystemCache,
+      }),
       optimization: {
         nodeEnv: process.env.NODE_ENV,
         minimize: isProductionBuild,
@@ -292,7 +297,11 @@ const makeWebpackConfig = ({
         filename: 'render.js',
         library: { name: 'static', type: 'umd2', export: 'default' },
       },
-      cache: getCacheSettings({ isDevServer, paths }),
+      cache: getCacheSettings({
+        isDevServer,
+        paths,
+        webpackFilesystemCache,
+      }),
       optimization: {
         nodeEnv: process.env.NODE_ENV,
       },
diff --git a/packages/sku/src/types/types.ts b/packages/sku/src/types/types.ts
@@ -443,6 +443,8 @@ export interface SkuConfigBase {
   transformOutputPath?: TransformOutputPathFunction;
 }
 
+export type WebpackFilesystemCacheMode = 'development' | 'always';
+
 export interface WebpackSkuConfig {
   /**
    * A folder of public assets to be copied into the `target` directory after `sku build` or `sku build-ssr`.
@@ -514,6 +516,18 @@ export interface WebpackSkuConfig {
    * @link https://seek-oss.github.io/sku/#/./docs/configuration?id=rootresolution
    */
   rootResolution?: boolean;
+
+  /**
+   * Controls [Webpack filesystem caching](https://webpack.js.org/configuration/cache/#cachetype).
+   *
+   * - `'development'` (default): cache is used only for the local dev server (`sku start` / `sku start-ssr`), not for production builds or in CI.
+   * - `'always'`: cache is also used for `sku build` / `sku build-ssr` and in CI, unless `SKU_DISABLE_CACHE` is set.
+   *
+   * Can be overridden with `SKU_WEBPACK_FILESYSTEM_CACHE=development` or `SKU_WEBPACK_FILESYSTEM_CACHE=always`.
+   *
+   * In Docker/Buildkite, pair `'always'` with a BuildKit cache mount on `node_modules/.cache/webpack` (and optionally `node_modules/.cache/babel-loader`) so the cache persists between builds.
+   */
+  webpackFilesystemCache?: WebpackFilesystemCacheMode;
 }
 
 export interface ViteSkuConfig {

-Original file line number
+Diff line change
@@ @@ -0,0 +1,5 @@ @@
 +---
 +'sku': minor
 +---
++
 +`webpack`: Add `webpackFilesystemCache` (`'development' | 'always'`) so production builds (`sku build` / `sku build-ssr`) and CI can opt in to Webpack filesystem caching. Override with `SKU_WEBPACK_FILESYSTEM_CACHE`. Default remains `'development'` (cache only for the local dev server).