Separate runtime and dev/build code to fix large bundle & dependency graph

[alialnaghmoush]

Problem

intlayer currently exposes build-time and development tooling through the same entrypoints used at runtime.

Because of this, importing very small features pulls large parts of the ecosystem into the dependency graph.

Examples observed in a Next.js production project:

Import	Added to graph
import type { IntlayerConfig } from "intlayer"	~111 KB (≈39 KB gz)
import { withIntlayer } from "next-intlayer/server"	~1.6 MB gz

The reason is architectural rather than optimization:

• The main intlayer package depends on CLI/config/compiler modules
• The Next.js helper (withIntlayer) also performs build/watch responsibilities
• Dev tooling (watchers, generators, filesystem loaders) becomes reachable from runtime entrypoints
• Bundlers and analyzers cannot reliably tree-shake these paths

Even if some code executes only in Node, exposing it through runtime entrypoints:

• inflates dependency graphs
• increases install/build time
• risks accidental bundling in edge/serverless environments
• makes performance analysis confusing

---

Root Cause

There is no strict separation between:

Layer	Should be
Runtime (browser/server execution)	minimal, stable
Server helpers	node-only
Build/dev tooling	isolated
CLI	isolated

Currently these responsibilities are mixed across intlayer and next-intlayer/server.

---

Proposed Solution

Introduce explicit entrypoint separation:

intlayer/
  runtime    → minimal resolver & types only
  react      → hooks only
  server     → server utilities (no watchers)
  dev        → generators & watchers
  cli        → commands

next-intlayer/
  plugin     → thin Next.js config wrapper
  server     → runtime helpers
  dev        → build/watch integration

Additionally:

Lazy-load dev tools

if (process.env.NODE_ENV !== "production") {
  await import("@intlayer/chokidar");
}

---

Expected Result

Area	Current	After separation
Runtime imports	tens of KB	single-digit KB
Next plugin graph	~1.6MB gz	small (<50KB expected)
Tree-shaking	unreliable	reliable
Edge compatibility	risky	safe

---

Why This Matters

i18n libraries are imported everywhere in an app.
Any overhead multiplies across the entire project.

Separating runtime from tooling would:

• reduce bundle size significantly
• improve install/build performance
• simplify dependency graphs
• improve edge/serverless compatibility

---

If useful, I can help test a runtime-only build and provide bundle analysis feedback.

[aymericzip]

Hey @alialnaghmoush,

Thanks for taking the time to make that analysis.

What did you use to measure it?

Note that all packages and subpackages are tree-shakable. That means after bundling, this issue no longer appears.

You’re right, the main cause of the issue is @intlayer/chokidar, which integrates all the server logic, along with the multi-level dependencies. But since this package is loaded every time, dynamically loading the module would probably slow the startup instead of making it faster.

I’ll look into how to split @intlayer/chokidar. Another possible improvement would be to bundle the packages themselves, but that would make debugging much harder, complicate aliasing, and duplicate function logic across each package (intlayer / next-intlayer).

I’ll study how this can be optimized for the next major version.

[aymericzip]

hey @alialnaghmoush

I splitted the @intlayer/chokidar package, let me know if it get better using the next-intlayer@8.1.2

[alialnaghmoush]

First of all — thanks for the work on Intlayer 🙌
I investigated the problem in a real Next.js App Router monorepo and can now confirm the issue is not only about next-intlayer/server — it also affects plain intlayer runtime imports.

This means the problem is deeper than the Next adapter:

The runtime package itself currently exposes build-time logic in its dependency graph.

Below are concrete findings.

---

1) Importing ONLY types from intlayer pulls runtime logic

Example:

import { type Dictionary } from "intlayer";

This single line adds ~112KB to the bundle.

Bundle analysis shows the cause:

intlayer/config
intlayer/core
dotenv
buildConfigurationFields
getContent/plugins

So even type-only usage is not side-effect free.

This breaks the assumption that intlayer can be safely used in shared or client-adjacent code.

---

2) Using runtime helpers pulls config system

This code:

getIntlayer("root", locale)
getMultilingualUrls("/")

pulls:

intlayer/config
interpreter/plugins
cacheMemory
dotenv

These are not runtime translation responsibilities — they belong to initialization/build phase.

---

3) Server provider still ships heavy runtime

This:

import { IntlayerServerProvider } from "next-intlayer/server";

adds ~130KB even inside a server component.

Meaning the adapter currently includes:

• config loader
• editor helpers
• translation interpreter plugins
• content scanning logic

Instead of being a thin context wrapper.

---

4) Compiler tooling still reachable from runtime entry

Earlier investigation already showed:

next-intlayer/server → ts-morph → chokidar → fs

But the new observation is more important:

Even intlayer (not next adapter) references config/build subsystems.

So the layering currently looks like:

intlayer (runtime)
 ├─ core runtime
 ├─ config loader
 ├─ build helpers
 ├─ dotenv
 └─ interpreter plugins

Which makes tree-shaking impossible for modern bundlers.

---

Why this breaks modern frameworks

Modern runtimes don't execute code to detect environment — they analyze import graphs:

• React Server Components
• Edge runtime
• Bun
• Turbopack
• Vite SSR

If runtime imports config/build code — the whole graph becomes reachable.

This produces:

• incorrect client boundaries
• heavy server components
• edge incompatibility
• unstable tree-shaking

So the issue is architectural, not optimization.

---

Required architecture separation

The package currently mixes 3 responsibilities:

1. Runtime translation engine
2. Configuration system
3. Content compiler / generator

They must be hard separated.

Proposed structure

intlayer/runtime        → pure dictionary resolver only
intlayer/server         → context helpers only
intlayer/config         → configuration loading
intlayer/compiler       → AST + file transforms
intlayer/dev            → watchers
intlayer/cli            → commands
next-intlayer           → thin framework adapter

---

Strict rules required

runtime must NOT import:

• config
• dotenv
• filesystem
• AST
• plugins auto-registration

server must NOT import:

• compiler
• generators
• declaration writers

next adapter must ONLY:

• read request locale
• provide context

---

Concrete changes needed

1) Move configuration loading out of runtime

getIntlayer currently loads configuration indirectly.

Instead:

config resolved once → passed into runtime
runtime becomes pure interpreter

2) Remove dotenv from runtime graph

Environment loading must happen in CLI/build phase only.

3) Make types package side-effect free

import type { Dictionary } from "intlayer" should cost 0 bytes.

This requires separating:

intlayer/types

4) Interpreter plugins must be explicit

Currently auto-registered through imports.

Instead runtime should receive plugins as parameters.

5) Next adapter must not bootstrap system

IntlayerServerProvider should not initialize configuration.
Only consume already prepared runtime context.

---

Expected end state

After separation:

Import	Expected size
type import	0 bytes
runtime usage	<10KB
server provider	minimal wrapper
compiler	CLI only

---

Summary

This is not a bundle optimization problem.
It is a layering problem: runtime depends on build system.

As long as runtime imports configuration/compilation logic, modern frameworks will always over-bundle Intlayer.

The solution is enforcing hard package boundaries.

[aymericzip]

Hey @alialnaghmoush, thanks again for that great analysis.

What process did you use to mesure it ? Do you have any tool to recommend ?

Using static dependencies graph, alias cannot be applied. Aliasing is due to the cross compatibility of intlayer function on front / backend / cli / vscode extension / etc
that say the ts-morph or fs should not be present in the import graphs after aliasing.

I will not split the intlayer package before the next major version. But it may be possible to improve @intlayer/chokidar or @intlayer/core usages to limit this cases.

For your need, I will recommend to use the subpackages directly @intlayer/core / @intlayer/types to replace intlayer

Intllayer package only reexport the tools, and module augmentation
https://github.com/aymericzip/intlayer/blob/main/packages/intlayer/src/index.ts

[alialnaghmoush]

Thanks for the reply 🙌
Here is the exact process I used — and why the error itself is the important signal.

---

Method used

Instead of measuring bundle size, I measured static dependency reachability.

Reason: modern frameworks (Next RSC / Edge / Bun / Turbopack) analyze import graphs before execution.
So a module is problematic even if the code path never runs.

To isolate the problem from Next.js, I used a minimal entry file:

// tools/intlayer-only.ts
import "intlayer";

Then:

bun build tools/intlayer-only.ts --analyze

---

Observed behavior

The build fails with:

Browser build cannot require Node.js builtin: child_process
Browser build cannot import Node.js builtin: child_process
Loading .node files won't work in the browser

This happens without using Next.js, React, or any framework —
only importing intlayer.

---

What this proves

This is not a bundle size issue — it is dependency reachability:

intlayer runtime entry makes the bundler reach:

• child_process
• fs native bindings
• chokidar / fsevents
• build tooling

Even if these are never executed at runtime, they are still part of the import graph.

And modern runtimes treat that as invalid for:

• browser bundles
• edge runtimes
• RSC environments

---

Why aliasing cannot solve it

Because the dependency is not conditional execution —
it is top-level module import.

So the bundler must include it to be safe.

Only solutions that work:

• lazy/dynamic import inside dev paths
• separating initialization from runtime
• moving Node-only modules behind explicit init()

---

Why this matters

Today a component that only calls:

useIntlayer("root")

implicitly makes the environment require Node APIs during graph analysis.

That prevents the package from being considered runtime-safe even if it works at runtime.

---

What likely needs to change (without breaking v8)

Based on trace failures, the runtime entry should avoid top-level imports of:

• config loading
• dotenv
• plugin registration
• chokidar
• declaration writers

Moving them behind CLI/dev initialization should be enough without splitting the package yet.

[aymericzip]

hey @alialnaghmoush

I have made strong improvement on that. Let me know how it goes