JS with Types Start

jsconfig.json option

paths and baseUrl

  • Default not set
  • Since TypeScript 2.0

paths maps import specifiers to files: "@lib/*": ["./src/lib/*"] lets import … from "@lib/format.js" find src/lib/format.js. Paths are resolved relative to the config file that sets them. baseUrl is an older companion that resolves bare names from one folder; it has not been needed for paths since TypeScript 4.1 and is deprecated from 6.0.

The catch for a JavaScript project: paths only tells the checker where to look. Nothing rewrites your imports, so Node.js, which reads your files as they are, does not know @lib and fails at run time. For code Node.js runs, the imports field in package.json gives you the same alias in a form both understand, as the third example shows.

At a glance

Write In a project Node.js runs, prefer a package.json imports field ("#lib/*"), which Node.js also understands. Use paths for names only a bundler or the checker resolves
On the command line No flag: only a config file can set it
Type object
Default in TypeScript 5.9 not set
TypeScript's description Specify a set of entries that re-map imports to additional lookup locations.
In the quick-start setups

The description is quoted from TypeScript's own option list (Apache-2.0); see the notices. The setup values are the checked configs on the quick-start pages.

Examples

src/main.js Error confirmed 5.9.3 TypeScript 5.9.3, run 21 October 2026: src/main.js(2,29): error TS2307: Cannot find module '@lib/format.js' or its corresponding type declarations. 6.0.3 TypeScript 6.0.3, run 21 October 2026: the same as 5.9.3. src/main.js(2,29): error TS2307: Cannot find module '@lib/format.js' or its corresponding type declarations. 7.0.2 TypeScript 7.0.2, run 21 October 2026: the same as 5.9.3. src/main.js(2,29): error TS2307: Cannot find module '@lib/format.js' or its corresponding type declarations. checked 21 October 2026 
import { formatPrice } from "@lib/format.js";error TS2307: Cannot find module '@lib/format.js' or its corresponding type declarations.

console.log(formatPrice(1999));
An alias without paths: the checker cannot find it.
jsconfig.json for this example 
{
  "compilerOptions": {
    "checkJs": true,
    "noEmit": true,
    "strict": true,
    "target": "es2022",
    "module": "nodenext",
    "types": []
  },
  "include": [
    "src/**/*.js"
  ]
}
src/main.js Error confirmed 5.9.3 TypeScript 5.9.3, run 21 October 2026: src/main.js(4,25): error TS2345: Argument of type 'string' is not assignable to parameter of type 'number'. 6.0.3 TypeScript 6.0.3, run 21 October 2026: the same as 5.9.3. src/main.js(4,25): error TS2345: Argument of type 'string' is not assignable to parameter of type 'number'. 7.0.2 TypeScript 7.0.2, run 21 October 2026: the same as 5.9.3. src/main.js(4,25): error TS2345: Argument of type 'string' is not assignable to parameter of type 'number'. checked 21 October 2026 
import { formatPrice } from "@lib/format.js";

console.log(formatPrice("19.99"));error TS2345: Argument of type 'string' is not assignable to parameter of type 'number'.
The same alias mapped with paths: resolved and checked.
jsconfig.json for this example 
{
  "compilerOptions": {
    "checkJs": true,
    "noEmit": true,
    "strict": true,
    "target": "es2022",
    "module": "nodenext",
    "types": [],
    "paths": {
      "@lib/*": [
        "./src/lib/*"
      ]
    }
  },
  "include": [
    "src/**/*.js"
  ]
}
src/main.js Error confirmed 5.9.3 TypeScript 5.9.3, run 21 October 2026: src/main.js(4,25): error TS2345: Argument of type 'string' is not assignable to parameter of type 'number'. 6.0.3 TypeScript 6.0.3, run 21 October 2026: the same as 5.9.3. src/main.js(4,25): error TS2345: Argument of type 'string' is not assignable to parameter of type 'number'. 7.0.2 TypeScript 7.0.2, run 21 October 2026: the same as 5.9.3. src/main.js(4,25): error TS2345: Argument of type 'string' is not assignable to parameter of type 'number'. checked 21 October 2026 
import { formatPrice } from "#lib/format.js";

console.log(formatPrice("19.99"));error TS2345: Argument of type 'string' is not assignable to parameter of type 'number'.
The Node.js way: an imports field in package.json, no paths needed (the wrong argument shows the import is checked).
jsconfig.json for this example 
{
  "compilerOptions": {
    "checkJs": true,
    "noEmit": true,
    "strict": true,
    "target": "es2022",
    "module": "nodenext",
    "types": []
  },
  "include": [
    "src/**/*.js"
  ]
}

The imports field instead

Node.js supports subpath imports: names starting with #, mapped in package.json and private to the package. TypeScript reads them under nodenext and bundler with no config, so the alias works in the checker and in Node.js alike.

package.json 
{
  "private": true,
  "type": "module",
  "imports": {
    "#lib/*": "./src/lib/*"
  }
}

When paths is the right tool

When something else resolves the alias at run time: a bundler configured with the same alias, a test runner, or a monorepo where workspace links provide the package names and paths points the checker at the sources (see extends). Keep the two lists in sync, since nothing checks that they agree.

Gotchas

  • paths cannot be set on the command line, and tsc --init cannot write it; it lives only in a config file.
  • A paths entry in a base config that others extend is resolved relative to the base file, not to the config that extends it.

  • jsconfig.json option

    moduleResolution

    moduleResolution decides how the checker finds the file behind an import: Node's rules with nodenext, a bundler's with bundler. Usually module sets it for you.

  • jsconfig.json key

    extends

    extends makes a config inherit another config file's options, so several jsconfig.json files can share one base. Files lists are replaced, not merged.

  • Quick start

    Monorepo

    Type-check a JavaScript monorepo: one root jsconfig.json for all packages, a small one per package that extends it, and paths to the sources.

  • jsconfig.json option

    customConditions

    customConditions adds export conditions, like development, that TypeScript uses when it reads a package's exports map. Match what your runtime or bundler uses.

  • TypeScript error

    TS2307: An import the checker cannot resolve

    TS2307 means an import path resolves to nothing the checker can read: a package not installed, a typo, or a CSS or image file. Install it or declare the module.

Sources

Last reviewed 20 October 2026.