growilabs/build-optimization

Build Optimization (apps/app)

Next.js Version & Bundler

• Next.js 16 (^16.0.0) with Turbopack bundler (default)
• Build: next build; Dev: Express server calls next({ dev }) which uses Turbopack by default
• React stays at ^18.2.0 — Pages Router has full React 18 support in v16
• Webpack has been fully removed (no webpack() hook, no --webpack flag)

Turbopack Configuration

Custom Loader Rules (turbopack.rules)

| Rule | Pattern | Condition | Purpose | |------|---------|-----------|---------| | superjson-ssr-loader | *.page.ts, *.page.tsx | { not: 'browser' } (server-only) | Auto-wraps getServerSideProps with SuperJSON serialization |

• Loaders are registered in next.config.ts under turbopack.rules
• condition: { not: 'browser' } restricts the loader to server-side compilation only
• as: '*.ts' / as: '*.tsx' tells Turbopack to continue processing the transformed output as TypeScript

Resolve Aliases (turbopack.resolveAlias)

4 server-only packages + fs are aliased to ./src/lib/empty-module.ts in browser context:

| Package | Reason | |---------|--------| | fs | Node.js built-in, not available in browser | | mongoose | MongoDB driver, server-only | | i18next-fs-backend | File-system i18n loader, server-only | | core-js | Server-side polyfills |

• Uses conditional { browser: './src/lib/empty-module.ts' } syntax so server-side resolution is unaffected
• resolveAlias requires relative paths (e.g., ./src/lib/empty-module.ts), not absolute paths — absolute paths cause "server relative imports are not implemented yet" errors
• If a new server-only package leaks into the client bundle, add it to resolveAlias with the same pattern

SuperJSON Serialization Architecture

The next-superjson SWC plugin was replaced by a custom loader:

• Build time: superjson-ssr-loader.ts auto-wraps getServerSideProps in .page.{ts,tsx} files with withSuperJSONProps() via Turbopack rules
• Runtime (server): withSuperJSONProps() in src/pages/utils/superjson-ssr.ts serializes props via superjson
• Runtime (client): _app.page.tsx calls deserializeSuperJSONProps() for centralized deserialization
• No per-page changes needed — new pages automatically get superjson serialization
• Custom serializers registered in _app.page.tsx (ObjectId, PageRevisionWithMeta)

CSS Modules Turbopack Compatibility

:global Syntax

Turbopack only supports the function form :global(...). The block form :global { ... } is NOT supported:

// WRONG — Turbopack rejects this
.parent :global {
  .child { color: red; }
}

// CORRECT — function form
.parent {
  :global(.child) { color: red; }
}

Nested blocks must also use function form:

// WRONG
.parent :global {
  .child {
    .grandchild { }
  }
}

// CORRECT
.parent {
  :global(.child) {
    :global(.grandchild) { }
  }
}

Other Turbopack CSS Restrictions

• Standalone :local / &:local: Not supported. Inside :global(...), properties are locally scoped by default — remove &:local wrappers
• @extend with :global(): @extend .class fails when target is wrapped in :global(.class) — Sass doesn't match them as the same selector. Use shared selector groups (comma-separated selectors) instead
• IE CSS hacks: *zoom:1, *display:inline, filter:alpha() cannot be parsed by Turbopack's CSS parser (lightningcss). Avoid CSS files containing these hacks

Vendor CSS Imports

Global CSS cannot be imported from files other than _app.page.tsx under Turbopack Pages Router. See the vendor-styles-components skill for the precompilation system that handles per-component vendor CSS.

Module Optimization Configuration

• serverExternalPackages: ['handsontable'] — packages excluded from server-side bundling
• optimizePackageImports — 11 @growi/* packages configured (expansion to third-party packages was tested and reverted — it increased dev module count)

Effective Module Reduction Techniques

Techniques that have proven effective for reducing module count, ordered by typical impact:

| Technique | When to Use | |-----------|-------------| | next/dynamic({ ssr: true }) | Heavy rendering pipelines (markdown, code highlighting) that can be deferred to async chunks while preserving SSR | | next/dynamic({ ssr: false }) | Client-only heavy components (e.g., Mermaid diagrams, interactive editors) | | Subpath imports | Packages with large barrel exports (e.g., date-fns/format instead of date-fns) | | Deep ESM imports | Packages that re-export multiple engines via barrel (e.g., react-syntax-highlighter/dist/esm/prism-async-light) | | resolveAlias | Server-only packages leaking into client bundle via transitive imports | | Lightweight replacements | Replace large libraries used for a single feature (e.g., tinykeys instead of react-hotkeys, regex instead of validator) |

Techniques That Did NOT Work

• Expanding optimizePackageImports to third-party packages — In dev mode, this resolves individual sub-module files instead of barrel, resulting in MORE module entries. Reverted.
• Refactoring internal barrel exports — Internal barrels (states/, features/) are small and well-scoped; refactoring had no measurable impact.

i18n HMR

I18NextHMRPlugin was removed during the Turbopack migration. Translation file changes require a manual browser refresh. The performance gain from Turbopack (faster Fast Refresh overall) outweighs the loss of i18n-specific HMR. Monitor if i18next-hmr adds Turbopack support in the future.