npm.io
3.2.36 • Published 2d ago

@visulima/tsconfig

Licence
MIT
Version
3.2.36
Deps
4
Size
174 kB
Vulns
0
Weekly
0
Stars
49
SummaryDependencyVersions
tsconfig

Find and/or parse the tsconfig.json file from a directory path.


typescript-image mit licence npm downloads Chat PRs Welcome

Daniel Bannert's open source work is supported by the community on GitHub Sponsors

Features

  • Tested against TypeScript for correctness
  • Supports comments & dangling commas in tsconfig.json (JSONC)
  • Resolves extends (relative paths, package names, and Yarn PnP)
  • Resolves ${configDir} template variables
  • Fully typed tsconfig.json
  • Synchronous and asynchronous search helpers

Install

npm install @visulima/tsconfig
yarn add @visulima/tsconfig
pnpm add @visulima/tsconfig

Usage

findTsConfig / findTsConfigSync

Retrieves the TsConfig by searching upward for a tsconfig.json file (falling back to jsconfig.json) from a given directory. findTsConfig is asynchronous; findTsConfigSync is the synchronous variant.

import { findTsConfig, findTsConfigSync } from "@visulima/tsconfig";

const tsconfig = await findTsConfig();
// => { path: "/Users/.../visulima/packages/tsconfig/tsconfig.json", config: { compilerOptions: { ... } } }

// Synchronous, with a custom start directory
const tsconfigSync = findTsConfigSync("/path/to/project");

Options (findTsConfig/findTsConfigSync):

Option Type Default Description
configFileName string "tsconfig.json" Name of the file to search for. Supplying a custom name disables the jsconfig.json fallback.
cache boolean | Map<string, TsConfigResult> undefined Cache parsed configs. true uses a process-wide cache; pass a Map for a caller-owned cache. Keys embed the file mtime, so on-disk edits invalidate cached entries automatically.
tscCompatible see readTsConfig undefined Forwarded to readTsConfig.
typescriptVersion see readTsConfig undefined Forwarded to readTsConfig.

Note: only the upward file search is async. Parsing (including the full extends chain) is synchronous, so a very deep extends chain still blocks the event loop during parse.

readTsConfig

Reads and parses the TypeScript configuration from a tsconfig.json path. This function is synchronous — it returns the resolved config object directly (no await).

import { readTsConfig } from "@visulima/tsconfig";

const tsconfig = readTsConfig("/path/to/tsconfig.json");

// Make derived defaults match a specific TypeScript version
const compatible = readTsConfig("/path/to/tsconfig.json", { tscCompatible: "5.8" });

// Apply the unconditional compiler-option defaults of the installed TypeScript
const withDefaults = readTsConfig("/path/to/tsconfig.json", { typescriptVersion: "auto" });

Options (ReadTsConfigOptions):

Option Type Default Description
tscCompatible "5.4" | "5.5" | "5.6" | "5.7" | "5.8" | "5.9" | "6.0" | "7.0" | true undefined Synthesize the derived defaults TypeScript would imply from other options for the given version (e.g. module: nodenext ⇒ moduleResolution: nodenext). true targets the latest supported version.
typescriptVersion "auto" | false | string false Apply the unconditional compiler-option defaults of a TypeScript version. "auto" detects the installed version (including Yarn PnP); a string pins an explicit version; false applies none. Can be combined with tscCompatible.
writeTsConfig / writeTsConfigSync

Writes the provided TypeScript configuration object to a tsconfig.json file. writeTsConfig is asynchronous; writeTsConfigSync is the synchronous variant.

import { writeTsConfig, writeTsConfigSync } from "@visulima/tsconfig";

await writeTsConfig({ compilerOptions: { strict: true } }, { cwd: "./" });

writeTsConfigSync({ compilerOptions: { strict: true } }, { cwd: "./" });
configDirectoryPlaceholder

The literal ${configDir} template string used by TypeScript. Re-exported so consumers can detect un-interpolated values without deep-importing internals.

import { configDirectoryPlaceholder } from "@visulima/tsconfig";

if (someValue.startsWith(configDirectoryPlaceholder)) {
    // value still references ${configDir}
}

Api Docs

@visulima/tsconfig

File

TsConfigJson

type TsConfigJson = object;

Defined in: node_modules/.pnpm/type-fest@4.41.0/node_modules/type-fest/source/tsconfig-json.d.ts:1

Type for TypeScript's tsconfig.json file (TypeScript 3.7).

Properties
compileOnSave?
optional compileOnSave: boolean;

Defined in: node_modules/.pnpm/type-fest@4.41.0/node_modules/type-fest/source/tsconfig-json.d.ts:1264

Enable Compile-on-Save for this project.

compilerOptions?
optional compilerOptions: CompilerOptions;

Defined in: node_modules/.pnpm/type-fest@4.41.0/node_modules/type-fest/source/tsconfig-json.d.ts:1249

Instructs the TypeScript compiler how to compile .ts files.

exclude?
optional exclude: string[];

Defined in: node_modules/.pnpm/type-fest@4.41.0/node_modules/type-fest/source/tsconfig-json.d.ts:1281

Specifies a list of files to be excluded from compilation. The exclude property only affects the files included via the include property and not the files property.

Glob patterns require TypeScript version 2.0 or later.

extends?
optional extends: string | string[];

Defined in: node_modules/.pnpm/type-fest@4.41.0/node_modules/type-fest/source/tsconfig-json.d.ts:1269

Path to base configuration file to inherit from.

files?
optional files: string[];

Defined in: node_modules/.pnpm/type-fest@4.41.0/node_modules/type-fest/source/tsconfig-json.d.ts:1274

If no files or include property is present in a tsconfig.json, the compiler defaults to including all files in the containing directory and subdirectories except those specified by exclude. When a files property is specified, only those files and those specified by include are included.

include?
optional include: string[];

Defined in: node_modules/.pnpm/type-fest@4.41.0/node_modules/type-fest/source/tsconfig-json.d.ts:1288

Specifies a list of glob patterns that match files to be included in compilation.

If no files or include property is present in a tsconfig.json, the compiler defaults to including all files in the containing directory and subdirectories except those specified by exclude.

references?
optional references: References[];

Defined in: node_modules/.pnpm/type-fest@4.41.0/node_modules/type-fest/source/tsconfig-json.d.ts:1293

Referenced projects.

typeAcquisition?
optional typeAcquisition: TypeAcquisition;

Defined in: node_modules/.pnpm/type-fest@4.41.0/node_modules/type-fest/source/tsconfig-json.d.ts:1259

Auto type (.d.ts) acquisition options for this project.

watchOptions?
optional watchOptions: WatchOptions;

Defined in: node_modules/.pnpm/type-fest@4.41.0/node_modules/type-fest/source/tsconfig-json.d.ts:1254

Instructs the TypeScript compiler how to watch files.

Other

findTsConfig()
function findTsConfig(cwd?, options?): Promise<TsConfigResult>;

Defined in: packages/tsconfig/src/find-tsconfig.ts:30

An asynchronous function that retrieves the TSConfig by searching for the "tsconfig.json" first, second attempt is to look for the "jsconfig.json" file from a given current working directory.

Parameters
cwd?

Optional. The current working directory from which to search for the "tsconfig.json" file. The type of cwd is string.

string | URL

options?

FindTsConfigOptions = {}

Returns

Promise<TsConfigResult>

A Promise that resolves to the TSConfig result object. The return type of the function is Promise<TsConfigResult>.

Throws

An Error when the "tsconfig.json" file is not found.

findTsConfigSync()
function findTsConfigSync(cwd?, options?): TsConfigResult;

Defined in: packages/tsconfig/src/find-tsconfig.ts:69

Parameters
cwd?

string | URL

options?

FindTsConfigOptions = {}

Returns

TsConfigResult

readTsConfig()
function readTsConfig(tsconfigPath, options?): object;

Defined in: packages/tsconfig/src/read-tsconfig.ts:460

Parameters
tsconfigPath

string

options?

ReadTsConfigOptions

Returns
compileOnSave?
optional compileOnSave: boolean;

Enable Compile-on-Save for this project.

compilerOptions?
optional compilerOptions: CompilerOptions;

Instructs the TypeScript compiler how to compile .ts files.

exclude?
optional exclude: string[];

Specifies a list of files to be excluded from compilation. The exclude property only affects the files included via the include property and not the files property.

Glob patterns require TypeScript version 2.0 or later.

files?
optional files: string[];

If no files or include property is present in a tsconfig.json, the compiler defaults to including all files in the containing directory and subdirectories except those specified by exclude. When a files property is specified, only those files and those specified by include are included.

include?
optional include: string[];

Specifies a list of glob patterns that match files to be included in compilation.

If no files or include property is present in a tsconfig.json, the compiler defaults to including all files in the containing directory and subdirectories except those specified by exclude.

references?
optional references: References[];

Referenced projects.

typeAcquisition?
optional typeAcquisition: TypeAcquisition;

Auto type (.d.ts) acquisition options for this project.

watchOptions?
optional watchOptions: WatchOptions;

Instructs the TypeScript compiler how to watch files.

writeTsConfig()
function writeTsConfig(tsConfig, options): Promise<void>;

Defined in: packages/tsconfig/src/write-tsconfig.ts:17

An asynchronous function that writes the provided TypeScript configuration object to a tsconfig.json file.

Parameters
tsConfig

TsConfigJson

The TypeScript configuration object to write. The type of tsConfig is TsConfigJson.

options

WriteFileOptions & object & object = {}

Optional. The write options and the current working directory. The type of options is an intersection type of WriteOptions and a Record type with an optional cwd key of type string.

Returns

Promise<void>

A Promise that resolves when the tsconfig.json file has been written. The return type of function is Promise<void>.

writeTsConfigSync()
function writeTsConfigSync(tsConfig, options): void;

Defined in: packages/tsconfig/src/write-tsconfig.ts:35

A function that writes the provided TypeScript configuration object to a tsconfig.json file.

Parameters
tsConfig

TsConfigJson

The TypeScript configuration object to write. The type of tsConfig is TsConfigJson.

options

WriteFileOptions & object & object = {}

Optional. The write options and the current working directory. The type of options is an intersection type of WriteOptions and a Record type with an optional cwd key of type string.

Returns

void

A Promise that resolves when the tsconfig.json file has been written. The return type of function is Promise<void>.

implicitBaseUrlSymbol
const implicitBaseUrlSymbol: typeof implicitBaseUrlSymbol;

Defined in: packages/tsconfig/src/read-tsconfig.ts:457

FindTsConfigOptions
type FindTsConfigOptions = ReadTsConfigOptions & object;

Defined in: packages/tsconfig/src/find-tsconfig.ts:10

Type declaration
cache?
optional cache:
  | Map<string, TsConfigResult>
  | boolean;
configFileName?
optional configFileName: string;
ReadTsConfigOptions
type ReadTsConfigOptions = object;

Defined in: packages/tsconfig/src/read-tsconfig.ts:444

Properties
tscCompatible?
optional tscCompatible: "5.4" | "5.5" | "5.6" | "5.7" | "5.8" | "5.9" | "6.0" | "7.0" | true;

Defined in: packages/tsconfig/src/read-tsconfig.ts:703

Make the configuration compatible with the specified TypeScript version.

Controls derived defaults — fields TypeScript synthesizes when other fields are set (e.g. module: nodenext ⇒ moduleResolution: nodenext).

When true, it will make the configuration compatible with the latest TypeScript version.

Default
undefined;
typescriptVersion?
optional typescriptVersion: "auto" | false | string;

Defined in: packages/tsconfig/src/read-tsconfig.ts:718

Apply the unconditional compiler-option defaults TypeScript would synthesize for the given version. "auto" detects the installed TypeScript version (including Yarn PnP); a string pins an explicit version; false applies none. Distinct from tscCompatible, and both can be combined.

Default
false;
TsConfigJsonResolved
type TsConfigJsonResolved = Except<TsConfigJson, "extends">;

Defined in: packages/tsconfig/src/types.ts:3

TsConfigResult
type TsConfigResult = object;

Defined in: packages/tsconfig/src/find-tsconfig.ts:15

Properties
config
config: TsConfigJsonResolved;

Defined in: packages/tsconfig/src/find-tsconfig.ts:16

path
path: string;

Defined in: packages/tsconfig/src/find-tsconfig.ts:17

Related

  • get-tsconfig - Get the TypeScript configuration from a project.

Supported Node.js Versions

Libraries in this ecosystem make the best effort to track Node.js’ release schedule. Here’s a post on why we think this is important.

Contributing

If you would like to help take a look at the list of issues and check our Contributing guidelines.

Note: please note that this project is released with a Contributor Code of Conduct. By participating in this project you agree to abide by its terms.

Credits

Made with at Anolilab

This is an open source project and will always remain free to use. If you think it's cool, please star it . Anolilab is a Development and AI Studio. Contact us at hello@anolilab.com if you need any help with these technologies or just want to say hi!

License

The visulima tsconfig is open-sourced software licensed under the MIT

Keywords

anolilabget-tsconfigread-tsconfigts-configtsconfigtsconfig.jsonvisulima