TypeScript Plug'n'Play Resolver

Common errors

• Cannot find module 'ts-pnp'

  cause The `ts-pnp` package has not been installed or is not accessible in the current environment.
  fix Run `yarn add -D ts-pnp` or `npm install --save-dev ts-pnp` in your project directory.

• TypeError: Cannot read properties of undefined (reading 'resolvedModule')

  cause This typically occurs if the `resolveModuleName` function returns `undefined` (or a similar falsy value) when it was expected to resolve a module, indicating a failure in the resolution process, possibly due to an incorrect path or a missing package in the PnP cache.
  fix Verify that the module being resolved actually exists and is properly installed via Yarn PnP. Double-check the `moduleName` and `containingFile` arguments passed to `resolvePnpModuleName` and ensure the `ts.resolveModuleName` fallback is correctly provided.

• TS2307: Cannot find module '...' or its corresponding type declarations.

  cause Despite `ts-pnp` being integrated, TypeScript is still unable to locate a module or its type definitions. This could mean PnP resolution failed, or a module is missing from the Yarn cache/`.pnp.cjs` file.
  fix Ensure the module is correctly listed in `package.json` and `yarn install` has been run. Verify that `ts-pnp`'s `resolveModuleName` is correctly wired into the `CompilerHost` and that the fallback to `ts.resolveModuleName` is present for non-PnP resolved modules or edge cases.

Warnings

• gotcha This package is a low-level utility for integrating Yarn PnP with the TypeScript Compiler API. It is not intended for direct application usage. Most users should look for higher-level integrations like `pnp-webpack-plugin`, `jest-pnp-resolver`, or `rollup-plugin-pnp-resolve` instead.
  Fix: Unless you are writing a custom TypeScript compiler host or tool, consider using a dedicated PnP plugin for your build system (e.g., `pnp-webpack-plugin` for Webpack).
• gotcha Incorrectly providing the `ts.resolveModuleName` or `ts.resolveTypeReferenceDirective` fallback function as the fifth argument to `ts-pnp`'s `resolveModuleName` will lead to incorrect module resolution behavior, potentially causing modules to not be found or resolved in unexpected ways.
  Fix: Always pass `ts.resolveModuleName` for module resolution and `ts.resolveTypeReferenceDirective` for type reference directive resolution as the fifth argument to `ts-pnp`'s `resolveModuleName` function.
• breaking Significant changes to Yarn's Plug'n'Play specification or the TypeScript Compiler API's module resolution hooks might require updates to `ts-pnp`. While the library strives for compatibility, fundamental shifts could impact its functionality.
  Fix: Always test `ts-pnp` integration thoroughly when upgrading major versions of Yarn or TypeScript. Refer to the `ts-pnp` GitHub repository for release notes regarding compatibility updates.
• gotcha While `ts-pnp` enables PnP resolution, it does not manage the installation or activation of PnP itself. Your project must be configured to use Yarn PnP for `ts-pnp` to function effectively.
  Fix: Ensure your project has `yarn install --enable-pnp` or equivalent configured to generate the `.pnp.cjs` file, and that your development environment is set up to use Yarn PnP.

Install

• npm install ts-pnp npm
• yarn add ts-pnp yarn
• pnpm add ts-pnp pnpm

Imports

• resolveModuleName
  wrong:

  import resolveModuleName from 'ts-pnp'; // Incorrect, it's a named export.
  const { resolveModuleName } = require('ts-pnp'); // CommonJS is typically not preferred for this library's use case with TypeScript.

  correct:

  import { resolveModuleName } from 'ts-pnp';

  The primary export is a named function, `resolveModuleName`, used to implement the `resolveModuleName` hook for TypeScript's `CompilerHost`.
• resolveTypeReferenceDirectives

  import { resolveModuleName } from 'ts-pnp'; // Used indirectly via resolveModuleName for type directives.

  While `resolveTypeReferenceDirectives` is an expected hook for `CompilerHost`, `ts-pnp` itself provides `resolveModuleName` which is then used to implement both module and type reference resolution, often by calling `resolveModuleName` from `ts-pnp` with appropriate arguments.
• CompilerHost integration

  import * as ts from 'typescript';
  import { resolveModuleName } from 'ts-pnp';

  This library is designed to be integrated into a custom `ts.CompilerHost` implementation. You will almost always need to import `typescript` itself alongside `ts-pnp`.

Quickstart

This quickstart demonstrates how to create a custom TypeScript `CompilerHost` that integrates `ts-pnp` for module and type reference resolution, providing Yarn Plug'n'Play support within a TypeScript compilation pipeline. It shows the core `resolveModuleName` hook implementation with a crucial fallback to TypeScript's default resolvers.

import { resolveModuleName as resolvePnpModuleName } from 'ts-pnp';
import * as ts from 'typescript';

interface CustomCompilerHost extends ts.CompilerHost {
  resolveModuleNames: (moduleNames: string[], containingFile: string) => (ts.ResolvedModule | undefined)[];
  resolveTypeReferenceDirectives: (typeDirectiveNames: string[], containingFile: string) => (ts.ResolvedTypeReferenceDirective | undefined)[];
}

function createPnPCompilerHost(
  compilerOptions: ts.CompilerOptions,
  host?: ts.CompilerHost, // Optional base host for fallback
): CustomCompilerHost {
  // Provide a default host if none is given
  const baseHost = host || ts.createCompilerHost(compilerOptions, true);

  const customHost: CustomCompilerHost = {
    ...baseHost,
    resolveModuleNames,
    resolveTypeReferenceDirectives,
  };

  return customHost;

  function resolveModuleNames(moduleNames: string[], containingFile: string) {
    return moduleNames.map(moduleName => {
      // ts-pnp resolver with a fallback to TypeScript's default resolver
      const resolved = resolvePnpModuleName(
        moduleName,
        containingFile,
        compilerOptions,
        customHost,
        ts.resolveModuleName // Essential fallback to TypeScript's internal resolver
      );
      return resolved.resolvedModule;
    });
  }

  function resolveTypeReferenceDirectives(typeDirectiveNames: string[], containingFile: string) {
    return typeDirectiveNames.map(typeDirectiveName => {
      // ts-pnp resolver for type directives, with fallback
      const resolved = resolvePnpModuleName(
        typeDirectiveName,
        containingFile,
        compilerOptions,
        customHost,
        ts.resolveTypeReferenceDirective // Essential fallback for type reference directives
      );
      return resolved.resolvedTypeReferenceDirective;
    });
  }
}

// Example usage (conceptual, actual compilation would involve more setup):
const compilerOptions: ts.CompilerOptions = {
  target: ts.ScriptTarget.ESNext,
  module: ts.ModuleKind.ESNext,
  strict: true,
  // ... other options
};

const pnpHost = createPnPCompilerHost(compilerOptions);
console.log('PnP-enabled TypeScript CompilerHost created.');
// To compile, you would typically use ts.createProgram with this host:
// const program = ts.createProgram(['./src/index.ts'], compilerOptions, pnpHost);
// program.emit();