Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/ifiokjr/tsconfig-resolver
Resolve the closest `tsconfig.json` file using the same lookup algorithm used by TypeScript
https://github.com/ifiokjr/tsconfig-resolver
configuration tsconfig tsconfig-json typescript
Last synced: 3 months ago
JSON representation
Resolve the closest `tsconfig.json` file using the same lookup algorithm used by TypeScript
- Host: GitHub
- URL: https://github.com/ifiokjr/tsconfig-resolver
- Owner: ifiokjr
- License: mit
- Created: 2020-03-12T19:17:24.000Z (almost 5 years ago)
- Default Branch: master
- Last Pushed: 2023-01-06T02:39:34.000Z (about 2 years ago)
- Last Synced: 2024-05-02T06:16:54.439Z (10 months ago)
- Topics: configuration, tsconfig, tsconfig-json, typescript
- Language: TypeScript
- Homepage:
- Size: 1.26 MB
- Stars: 3
- Watchers: 3
- Forks: 2
- Open Issues: 27
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Funding: .github/FUNDING.yml
- License: LICENSE
Awesome Lists containing this project
README
# tsconfig-resolver
[](#contributors-)
[](https://github.com/ifiokjr/tsconfig-resolver/actions?query=workflow%3A%22Node+CI%22)
[![Version][version]][npm]
[![Weekly Downloads][downloads-badge]][npm]
[![Typed Codebase][typescript]](./src/index.ts)
![MIT License][license]
[](https://github.com/semantic-release/semantic-release)
> A tool for loading the nearest tsconfig file in the same way the TypeScript compiler does. It walks up the directory tree until it finds the first matching `tsconfig.json` file.
## Table of Contents
- [tsconfig-resolver](#tsconfig-resolver)
- [Table of Contents](#table-of-contents)
- [Usage](#usage)
- [Setup](#setup)
- [Code Example](#code-example)
- [API](#api)
- [`tsconfigResolverSync`](#tsconfigresolversync)
- [Returns](#returns)
- [Options](#options)
- [`tsconfigResolver`](#tsconfigresolver)
- [`clearCache`](#clearcache)
- [`CacheStrategy`](#cachestrategy)
- [`TsConfigErrorReason`](#tsconfigerrorreason)
- [`TsConfigJson`](#tsconfigjson)
- [Contributing](#contributing)
- [Versioning](#versioning)
- [License](#license)
- [Contributors](#contributors)
## Usage
`tsconfig-resolver` is designed to be used inside your node project. It automatically populates the extends field so that the configuration received is the same as would be used by any consuming TypeScript project.
### Setup
First, install the plugin and it's peer dependencies:
```bash
npm install --save tsconfig-resolver
```
or
```bash
yarn add tsconfig-resolver
```
### Code Example
The following will load the first `tsconfig.json` file working upwards from the `process.cwd()` of the running node process.
```ts
import { tsconfigResolver } from 'tsconfig-resolver';
const result = await tsconfigResolver();
// without type narrowing
console.log(result?.config);
// with type narrowing
if (result.exists) {
console.log(result.config);
}
```
Configuration options can also be passed into the export function.
```ts
import { join } from 'path';
import { CacheStrategy, tsconfigResolver } from 'tsconfig-resolver';
const result = tsconfig({
cwd: join(__dirname, 'src'),
fileName: 'tsconfig.prod.json',
cache: CacheStrategy.Directory,
});
```
## API
### `tsconfigResolverSync`
```ts
import { tsconfigResolverSync } from 'tsconfig-resolver';
```
#### Returns
The function returns an object consisting of the following.
| Property | Type | Description |
| ----------------- | ------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **config** | `TsConfigJson` or `undefined` | The configuration object.
- `undefined` when the tsconfig resolver failed and no configuration was found.
- `TsConfigJson` (exported by the `type-fest` library) when the resolved tsconfig has been found and loaded.
| **exists** | `boolean` | Whether or not the configuration could be loaded.
- `false` when no tsconfig could be found.
- `true` when a valid tsconfig file has been found and successfully loaded.
| **reason** | `TsConfigErrorReason` or `undefined` | The reason for failure.
- `TsConfigErrorReason.NotFound` when the config failure is because the filename has not been found.
- `TsConfigErrorReason.InvalidConfig` when the config failure is because of an invalid config.
- `undefined` when no failure has occurred.
| **path** | `string` or `undefined` | The absolute path to the tsconfig.json or given filename.
- `undefined` when not found.
- `string` when config json is invalid.
- `string` when a valid tsconfig has been loaded.
| **extendedPaths** | `string[]` or `undefined` | The extendedPaths array.
- `undefined` when the tsconfig resolver failed to load a valid configuration.
- `string[]` of absolute paths to resolved tsconfig files when extended paths are encountered.
- `[]` an empty array when no extended paths are encountered.
- `[]` an empty array when ignoreExtends options is set to true.
| **isCircular** | `boolean` or `undefined` | The `isCircular` config flag.
- `undefined` when the tsconfig resolver failed to load a valid configuration.
- `true` when a circular `extends` property was encountered (an extends path chain that references itself).
- `false` when no circular `extends` property was encountered.
#### Options
| Property | Type | Default | Description |
| ----------------- | --------------------- | ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **cwd** | `string` | `process.cwd()` | The directory to start searching from. |
| **searchName** | `string` | `'tsconfig.json'` | The tsconfig file name to search for. This is where the `TsConfigJson` configuration object will be loaded from. |
| **filePath** | `string` | `undefined` | A direct path to the tsconfig file you would like to load. The path will be resolved relative to the current `process.cwd()`. If it leads to a directory then the `searchName` will be appended. \* This also supports the `npm:` prefix which will find the given npm package directory, if it is installed. When provided the `cache` is set to `'always'` by default. |
| **cache** | `string` or `boolean` | `'never'` | Set the caching strategy that will be used when searching for a file that's already been found. When a `filePath` is provided the default value becomes `'always'`. |
| **ignoreExtends** | `boolean` | `false` | When true will not automatically populate the `extends` argument. This is useful if all you want is the json object and not the fully resolved configuration. |
### `tsconfigResolver`
```ts
import { tsconfigResolver } from 'tsconfig-resolver';
```
The same API as `tsconfigResolverSync` except the return value is wrapped in a promise.
### `clearCache`
Clears the cache.
```ts
import { clearCache, tsconfigResolver } from 'tsconfig-resolver';
const result = await tsconfigResolver();
// Now clear the cache.
clearCache();
```
### `CacheStrategy`
```ts
import { CacheStrategy } from 'tsconfig-resolver';
```
Provides the available caching strategies that can be used.
Sometimes you'll want to run this module several times during runtime but it can be slow and expensive walk up the file tree for the tsconfig value every time.
To help prevent unnecessary lookups there are custom caching strategies available.
- `CacheStrategy.Never` - Caching never happens and the returned value is always recalculated
- `CacheStrategy.Always` - The first time the `tsconfigResolver` method is run it will save a cached value (by `searchName`) which will be returned every time after that. This value will always be the same. This is turned on by default when a `filePath` is provided.
- `CacheStrategy.Directory` - The cache will be used when the same directory (and `searchName`) is being searched.
### `TsConfigErrorReason`
```ts
import { TsConfigErrorReason } from 'tsconfig-resolver';
```
This provides the reason for the error in resolving the `tsconfig`.
- `TsConfigErrorReason.NotFound` - The `tsconfig` file could not be found.
- `TsConfigErrorReason.InvalidConfig` - The file was found but the configuration was invalid.
### `TsConfigJson`
Re-exported from [`type-fest`](https://github.com/sindresorhus/type-fest).
## Contributing
Dive into the codebase with Gitpod.
[](https://gitpod.io/#https://github.com/ifiokjr/tsconfig-resolver)
## Versioning
This project uses [SemVer](http://semver.org/) for versioning. For the versions available, see the
[tags on this repository](https://github.com/ifiokjr/tsconfig-resolver/tags).
## License
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details
## Contributors
[version]: https://flat.badgen.net/npm/v/tsconfig-resolver
[npm]: https://npmjs.com/package/tsconfig-resolver
[license]: https://flat.badgen.net/badge/license/MIT/purple
[size]: https://bundlephobia.com/result?p=#tsconfig-resolver
[size-badge]: https://flat.badgen.net/bundlephobia/minzip/tsconfig-resolver
[typescript]: https://flat.badgen.net/badge/icon/TypeScript/?icon=typescript&label&labelColor=blue&color=555555
[downloads-badge]: https://badgen.net/npm/dw/tsconfig-resolver/red?icon=npm