OpenParable
Skip to content
← Back to skills

Build Optimization

Development
build-optimization

Build Optimization is an Agent Skill for development published in the growilabs/growi repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.

GROWI apps/app Turbopack configuration, module optimization, and build measurement tooling. Auto-invoked when working in apps/app.

View on GitHub ↗
QUICK START

How to use this skill

Bring this guide into your coding agent with a prompt tailored to the tool you use.

  1. Open your project in Codex.
  2. Copy and paste the prompt below.
  3. Review files and risks before approving any action.
Prompt to paste
Inspect the Agent Skill at https://github.com/growilabs/growi/blob/HEAD/apps/app/.claude/skills/build-optimization/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/build-optimization, but wait for my approval before writing files or running scripts.

Copying this prompt does not install or run the skill. Review third-party files before use.

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)

RulePatternConditionPurpose
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:

PackageReason
fsNode.js built-in, not available in browser
mongooseMongoDB driver, server-only
i18next-fs-backendFile-system i18n loader, server-only
core-jsServer-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:

TechniqueWhen 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 importsPackages with large barrel exports (e.g., date-fns/format instead of date-fns)
Deep ESM importsPackages that re-export multiple engines via barrel (e.g., react-syntax-highlighter/dist/esm/prism-async-light)
resolveAliasServer-only packages leaking into client bundle via transitive imports
Lightweight replacementsReplace 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.