Layers

Turbopack models the user's code as it travels through Turbopack in multiple ways, each of which can be thought of as a layer in the system below:

┌───────────────┬──────────────────────────────┐
│    Sources    │                              │
├───────────────┘                              │
│                     What "the user wrote" as │
│                             application code │
└──────────────────────────────────────────────┘

┌───────────────┬──────────────────────────────┐
│    Modules    │                              │
├───────────────┘                              │
│        The "compiler's understanding" of the │
│                             application code │
└──────────────────────────────────────────────┘

┌───────────────┬──────────────────────────────┐
│ Output assets │                              │
├───────────────┘                              │
│ What the "target environment understands" as │
│                       executable application │
└──────────────────────────────────────────────┘

Each layer is implemented as a decorator/wrapper around the previous layer in top-down order. In contrast to tools like webpack, where whole {source,module,chunk} graphs are built in serial, Turbopack builds lazily by successively wrapping an asset in each layer and building only what's needed without blocking on everything in a particular phase.

Sources

Sources are content of code or files before they are analyzed and converted into Modules. They might be the original source file the user has written, or a virtual source code that was generated. They might also be transformed from other Sources, e. g. when using a preprocessor like SASS or webpack loaders.

Sources do not model references (the relationships between files like through import, sourceMappingURL, etc.).

Each Source has an identifier composed of file path, query, fragment, and other modifiers.

Modules

Modules are the result of parsing, transforming and analyzing Sources. They include references to other modules as analyzed.

References can be followed to traverse a subgraph of the module graph. They implicitly from the module graph by exposing references.

Each Module has an identifier composed of file path, query, fragment, and other modifiers.

Output asset

Output assets are artifacts that are understood by the target environment. They include references to other output assets.

Output assets are usually the result of transforming one or more modules to a given output format. This can be a very simple transformation like just copying the Source content (like with static assets like images), or a complex transformation like chunking and bundling modules (like with JavaScript or CSS).

Output assets can be emitted to disk or served from the dev server.

Each Output asset has a file path.

Example

graph TD
  subgraph Source code
    src ---> b.src.js[ ]
    src ---> util
    util ---> d.src.css[ ]
    util ---> c.src.js[ ]
  end
  subgraph Module graph
    a.ts ---> b.js
    a.ts ---> c.js
    b.js ---> c.js
    c.js ---> d.css
    c.js ---> e.js[ ]
    b.js ---> f.js[ ]

    b.js -.-> b.src.js
    d.css -.-> d.src.css
  end
  subgraph Output graph
    main.js --> chunk.js
    main.js --> chunk2.js[ ]

    main.js -.-> a.ts
    main.js -.-> b.js
    main.js -.-> c.js
  end