Utilities for working with tsconfig files
- What is this?
- When should I use this?
- Install
- Use
- API
createGetCanonicalFileName([useCaseSensitiveFileNames])createModuleResolutionHost([options])createParseConfigHost([options])isResolvedTsconfig(value)isTsconfigHost(value)loadTsconfig<T>([id][, options])mergeTsconfig<T>(target[, ...tsconfigs])readTsconfig<T>([id][, options])resolvePath(specifier[, options])
- Types
tsconfig-typesAwaitable<T>DirectoryExistsDirentFileExistsFileSystemGetCanonicalFileNameGetCurrentDirectoryGetDirectoriesHostReadFileIsDirectoryIsFileIsSymbolicLinkList<[T]>LoadTsconfigOptionsModuleResolutionHostOptionsModuleResolutionHostParseConfigHostOptionsParseConfigHostReadDirectoryReadFileReadTsconfigOptionsReaddirDirentOptionsReaddirOptionsReaddirRealpathResolvePathOptionsResolvedTsconfigStatStatsTsconfigHostUseCaseSensitiveFileNamesFnUseCaseSensitiveFileNames
- Related
- Contribute
This package exports utilities for working with TypeScript configuration files.
This package can be used to merge and load tsconfig files, as well resolve path aliases.
This package is ESM only.
In Node.js (version 20+) with yarn:
yarn add @flex-development/tsconfig-utilsSee Git - Protocols | Yarn for details regarding installing from Git.
In Deno with esm.sh:
import {
createModuleResolutionHost,
loadTsconfig,
resolvePath
} from 'https://esm.sh/@flex-development/tsconfig-utils'In browsers with esm.sh:
<script type="module">
import {
createModuleResolutionHost,
loadTsconfig,
resolvePath
} from 'https://esm.sh/@flex-development/tsconfig-utils'
</script>import {
loadTsconfig,
type ResolvedTsconfig
} from '@flex-development/tsconfig-utils'
import fs from 'node:fs'
/**
* The resolved tsconfig.
*
* @const {ResolvedTsconfig | null} resolved
*/
const resolved: ResolvedTsconfig | null = await loadTsconfig(null, {
encoding: 'utf8',
fs: fs.promises
})
if (resolved) {
console.dir(resolved.tsconfig) // the loaded tsconfig, with bases applied
console.dir(resolved.url) // the url of the tsconfig file
}This package exports the following identifiers listed below.
There is no default export.
Create a canonical file name function.
useCaseSensitiveFileNames(UseCaseSensitiveFileNames) — whether to treat filenames as case sensitive
(GetCanonicalFileName) A function that returns a canonical file name given a module id
Create a module resolution host.
The module resolution host acts a bridge between the TypeScript compiler and the file system.
👉 Note: The host can have both asynchronous and synchronous methods, but when used with the native TypeScript compiler, all methods must return synchronous values.
options(ModuleResolutionHostOptions|null|undefined) — options for host creation
(ModuleResolutionHost) The module resolution host
Create a configuration parser host.
The parser host provides methods for accessing the file system and resolving module paths.
👉 Note: The host can have both asynchronous and synchronous methods, but when used with the native TypeScript compiler, all methods must return synchronous values.
options(ParseConfigHostOptions|null|undefined) — options for host creation
(ParseConfigHost) The parse config host
Check if value is a resolved configuration object.
value(unknown) — the value to check
(value is ResolvedTsconfig) true if value is resolved tsconfig object, false otherwise
Check if value is an object with a Tsconfig.
value(unknown) — the value to check
(value is TsconfigHost) true if value is tsconfig host object, false otherwise
Load a tsconfig file.
T(Awaitable<ResolvedTsconfig | null>) — the resolved tsconfig
id(ModuleId|null|undefined) — the module id or specifier of the tsconfig file- default:
'tsconfig.json'
- default:
options(LoadTsconfigOptions|null|undefined) — load options
(T) The resolved tsconfig, or null if tsconfig file is not found
Merge one or more tsconfig objects into a single Tsconfig.
Tsconfig source objects are applied from left to right. Subsequent sources overwrite property assignments of previous sources.
👉 Note: If
targetis aTsconfigHost,target.tsconfigwill be modified. Otherwise,targetwill be modified.
T(Tsconfig) — the merged tsconfig
target(Tsconfig|TsconfigHost|null|undefined) — the target tsconfig or tsconfig host...tsconfigs(readonly (Tsconfig | TsconfigHost | null | undefined)[]) — the source tsconfig object(s)
(T) The merged tsconfig
Read a tsconfig file.
👉 Note: Returns a promise if
getSourceorresolveModulereturns a promise.
T(Awaitable<ResolvedTsconfig | null>) — the resolved tsconfig
id(ModuleId|null|undefined) — the module id or specifier of the tsconfig file- default:
'tsconfig.json'
- default:
options(ReadTsconfigOptions|null|undefined) — read options
(T) The resolved tsconfig, or null if tsconfig file is not found
Resolve an aliased specifier.
specifier(string) — the specifier using an aliasoptions(ResolvePathOptions|null|undefined) — alias resolution options
(string | null) The path alias match or null if match is not found
This package is fully typed with TypeScript.
This package re-exports TypeScript definitions from tsconfig-types.
This is primarily for the convenience of TypeScript users who do not hoist packages,
but may need to import definitions used in this package.
Create a union of T and T as a promise-like object (type).
type Awaitable<T> = PromiseLike<T> | TT(any) — the value
Check if a directory exists (interface).
<T extends Awaitable<boolean>>(id: ModuleId): TT(Awaitable<boolean>) — the result of the check
id(ModuleId) — the module id to check
(T) true if directory exists at id, false otherwise
Information about a directory entry (interface).
isDirectory(IsDirectory) — check if the entry is a directoryisFile(IsFile) — check if the entry is a fileisSymbolicLink(IsSymbolicLink) — check if the entry is a symbolic linkname(string) — the path to the entry, relative to theparentPathparentPath(string) — the path to the parent directory
Check if a file exists (interface).
<T extends Awaitable<boolean>>(id: ModuleId): TT(Awaitable<boolean>) — the result of the check
id(ModuleId) — the module id to check
(T) true if file exists at id, false otherwise
The file system API (interface).
readFile(ReadFile) — read the entire contents of a filereaddir(Readdir) — read the entire contents of a directoryrealpath(Realpath) — compute a canonical pathname by resolving.,.., and symbolic linksstat(Stat) — get information about a file system entry
Get the canonical file name for a module id (type).
type GetCanonicalFileName = (this: void, id: ModuleId) => stringid(ModuleId) — the module id
(string) The canonical file name
Get the path to the current working directory (interface).
<T extends Awaitable<string>>(): TT(Awaitable<string>) — the directory path
id(ModuleId) — the module id to check
(T) The current working directory path
Get a list of subdirectories (interface).
<T extends Awaitable<string[]>>(parent: ModuleId): TT(Awaitable<string[]>) — the list of subdirectory names
id(ModuleId) — the module id of the parent directory
(T) The list of subdirectory names
Read the entire contents of a file (interface).
<T extends Awaitable<string | undefined>>(id: ModuleId): TT(Awaitable<string | undefined>) — the file contents
id(ModuleId) — the module id of the file
(T) The file contents, or undefined if file does not exist at id
Check if a file system entry is a directory (interface).
Check if a file system entry is a file (interface).
Check if a file system entry is a symbolic link (interface).
(): boolean(boolean) true if entry is symbolic link, false otherwise
A list (type).
type List<T = unknown> = ReadonlySet<T> | readonly T[]T(any, optional) — the list item type
Options for loading tsconfig files (interface).
relativePaths(List<string>|null|undefined) — the list of property paths where the value may be a relative path
Options for creating module resolution hosts (interface).
encoding?(BufferEncoding) — the encoding to use when reading files- default:
'utf8'
- default:
fs?(FileSystem|null|undefined) — the file system apiroot?(ModuleId|null|undefined) — the module id of the current working directoryuseCaseSensitiveFileNames?(UseCaseSensitiveFileNames) — boolean indicating whether filenames should be treated as case sensitive, or a function that returns such a value
The module resolution host API (interface).
The module resolution host acts a bridge between the TypeScript compiler and the file system.
👉 Note: The host can have both asynchronous and synchronous methods, but when used with the native TypeScript compiler, all methods must return synchronous values.
directoryExists(DirectoryExists) — check if a directory existsfileExists(FileExists) — check if a file existsgetCurrentDirectory(GetCurrentDirectory) — get the path to the current working directorygetDirectories(GetDirectories) — get a list of subdirectoriesreadFile(HostReadFile) — read the entire contents of a filerealpath(Realpath) — compute a canonical pathname by resolving.,.., and symbolic linksuseCaseSensitiveFileNames?(UseCaseSensitiveFileNames) — whether to treat filenames as case sensitive
Options for creating parse config hosts (interface).
The configuration parser host API (interface).
The parser host provides methods for accessing the file system and resolving module paths.
👉 Note: The host can have both asynchronous and synchronous methods, but when used with the native TypeScript compiler, all methods must return synchronous values.
readDirectory(ReadDirectory) — read the contents of a directoryuseCaseSensitiveFileNames(boolean) — whether to treat filenames as case sensitive
Read the contents of a directory (interface).
<T extends Awaitable<readonly string[]>>(
parent: ModuleId,
extensions?: List<string> | null | undefined,
exclude?: List<string> | null | undefined,
include?: List<string> | null | undefined,
depth?: number | null | undefined
): TT(Awaitable<readonly string[]>) — the list of matched files
parent(ModuleId) — the module id of the parent directoryextensions(List<string>|null|undefined) — the list of file extensions to filter forexclude(List<string>|null|undefined) — the list of glob patterns matching files to excludeinclude(List<string>|null|undefined) — the list of glob patterns matching files to includedepth(number|null|undefined) — the maximum search depth (inclusive)
(T) The list of matched files
Read the entire contents of a file (interface).
Options for reading tsconfig files (interface).
conditions(List<Condition>|null|undefined) — the list of export/import conditions- default:
mlly.defaultConditions
👉 note: should be sorted by priority
- default:
cwd(ModuleId|null|undefined) — the url of the current working directory- default:
mlly.cwd()
- default:
mainFields(List<MainField>|null|undefined) — the list of legacymainfields- default:
mlly.defaultMainFields
👉 note: should be sorted by priority
- default:
parent(ModuleId|null|undefined) — the parent module id- default:
cwd|mlly.cwd()
- default:
preserveSymlinks(boolean|null|undefined) — whether to keep symlinks instead of resolving them
Options for reading the contents of a directory (interface).
withFileTypes(true) — whether the result should be a content object list instead of just strings.
iftrue, the result will be a list ofDirectobjects, which provide methods likeisDirectory()andisFile()to get more information about a file system entry without additionalfs.stat()calls
Options for reading the contents of a directory (interface).
withFileTypes?(boolean|null|undefined) — whether the result should be a content object list instead of just strings.
iftrue, the result will be a list ofDirectobjects, which provide methods likeisDirectory()andisFile()to get more information about a file system entry without additionalfs.stat()calls
Read the entire contents of a directory (interface).
<T extends Awaitable<readonly Dirent[]>>(id: ModuleId, options: ReaddirDirentOptions): TT(Awaitable<readonly Dirent[]>) — the directory contents
id(ModuleId) — the module id of the fileoptions(ReaddirDirentOptions) — read options
(T) The directory contents
Compute a canonical pathname by resolving ., .., and symbolic links (interface).
Options for path alias resolution (interface).
aliases?(null|undefined) — the url of the tsconfig file👉 note: path aliases are read from the
tsconfigtsconfig?(ResolvedTsconfig|Tsconfignull|undefined) — the tsconfig object, or the resolved tsconfig
A resolved TypeScript configuration (interface).
url(URL) — the url of the tsconfig file
Get information about a file system entry (interface).
Information about a file system entry (interface).
isDirectory(IsDirectory) — check if the entry is a directoryisFile(IsFile) — check if the entry is a file
An object with a TypeScript configuration (interface).
tsconfig(Tsconfig) — the tsconfig object
Determine if file names should be treated as case sensitive (type).
type UseCaseSensitiveFileNamesFn = (this: void) => boolean | null | undefined(boolean | null | undefined) true if file names should be treated as case sensitive
Union of values used to determine if file names should be treated as case sensitive (type).
type UseCaseSensitiveFileNames =
| UseCaseSensitiveFileNamesFn
| boolean
| null
| undefined(boolean | null | undefined) true if file names should be treated as case sensitive
@flex-development/mlly— ECMAScript module utilities@flex-development/tsconfig-types— TypeScript definitions fortsconfig.json
See CONTRIBUTING.md.
This project has a code of conduct. By interacting with this repository, organization, or community you agree to abide by its terms.