Custom Rspack Configuration

Aplos allows you to extend the framework's default rspack configuration by providing your own rspack.config.js at the project root.

Usage

Create a rspack.config.js file in your project directory:

// rspack.config.js
export default {
  module: {
    rules: [
      {
        test: /\.md$/,
        type: 'asset/source',
      },
    ],
  },
};

Your configuration is automatically merged with the framework defaults using webpack-merge.

Merge Behavior

Examples

Adding a custom loader

export default {
  module: {
    rules: [
      {
        test: /\.svg$/,
        type: 'asset/resource',
      },
    ],
  },
};

Adding resolve aliases

export default {
  resolve: {
    alias: {
      '~content': './content',
    },
  },
};

Adding plugins

import { ProvidePlugin } from '@rspack/core';

export default {
  plugins: [
    new ProvidePlugin({
      Buffer: ['buffer', 'Buffer'],
    }),
  ],
};

Build cache

Aplos uses Rspack's persistent filesystem cache to speed up repeat builds. The client and SSR compilations keep separate caches so they never invalidate each other.

By default the cache lives in node_modules/.cache/aplos/. If the XDG_CACHE_HOME environment variable is set, the cache is written under $XDG_CACHE_HOME/aplos/ instead. This matters in CI/CD and on PaaS builders: point XDG_CACHE_HOME at a directory that persists between builds and the cache survives across deploys, turning every build after the first into a warm build.

# Persist the cache across builds (CI example)
export XDG_CACHE_HOME=/path/to/persistent/cache
bun run build

The cache invalidates automatically when rspack.config.js or rspack.ssr.config.js changes. To force a clean build, delete the cache directory.

Memory cost

The persistent cache trades memory for speed: restoring and serialising the module graph keeps it resident alongside the live one, which measured ~83 MB of extra peak RSS on an app whose bundle is under a megabyte. This is a known Rspack issue (#11185) and the overhead grows once a cache exists, so it hits hardest exactly where the cache is persisted across deploys.

On a memory-capped builder that overhead can be enough to get the bundler OOM-killed — and a build that dies buys no warm builds at all. Set APLOS_BUILD_CACHE=0 to trade warm builds for the lower peak:

# Build on a memory-constrained container
APLOS_BUILD_CACHE=0 bun run build

!!! warning Avoid overriding core framework settings (entry, output.path, internal aliases) as this may break Aplos functionality.