Contexts

TBD

Alias and resolve plugins

Turbopack supports aliasing imports similar to Webpack's 'alias' config. It is being applied when Turbopack runs its module resolvers.

Setting up alias

To set the alias, use the import_map in each context's ResolveOptionContext. ResolveOptionContext also has fallback_import_map which will be applied when a request to resolve cannot find any corresponding imports.

let resolve_option_context = ResolveOptionContext {
  ..
  import_map: Some(next_client_import_map),
  fallback_import_map: Some(next_client_fallback_import_map),
}

These internal mapping options will be applied at the end among any other resolve options. For example, if user have tsconfig's compilerOptions.paths alias, it'll take precedence.

ImportMap can be either 1:1 match (AliasPattern::Exact) or wildcard matching (AliasPattern::Wildcard). Check AliasPattern for more details.

React

Next.js internally aliases react imports based on context. Reference Webpack config and Turbopack for how it's configured.

ResolvePlugin

ResolveOptionContext have one another option plugins, can affect context's resolve result. A plugin implements ResolvePlugin can replace resolved results. Currently resolve plugin only supports after_resolve, which will be invoked after full resolve completes.

after_resolve provides some information to determine specific resolve, most notably request param contains full Request itself.

async fn after_resolve(
        &self,
        fs_path: Vc<FileSystemPath>,
        file_path: Vc<FileSystemPath>,
        reference_type: Value<ReferenceType>,
        request: Vc<Request>,
    ) -> Result<Vc<ResolveResultOption>>

Plugin can return its own ResolveResult or return nothing (None). Retuning None will makes original resolve result being honored, otherwise original resolve result will be overridden. In Next.js resolve plugins are being used for triggering side effect by emitting an issue if certain context imports not allowed module (InvalidImportResolvePlugin), or replace a single import into per-context aware imports (NextNodeSharedRuntimeResolvePlugin).