dts-alias
v1.0.7
Published
Tiny cli utility to fix unresolved type aliases in type definitions.
Downloads
15
Readme
dts-alias
Tiny cli utility to fix unresolved type aliases in type definitions until something like #30952 is hopefully implemented.
Install
npm install -g dts-alias
Usage
dts-alias [...tsc cli options]
// to turn on verbose output just set the DEBUG environment variable:
DEBUG=true tsc [...tsc cli options]
This utility should be passed any options you pass to tsc
when emitting your definitions (technically not all of them, see notes).
I recommend just keeping a separate tsconfig like tsconfig.types.json
for emitting your types so you can just make a script that does:
tsc -p tsconfig.types.json && dts-alias -p tsconfig.types.json
Internally it will just run tsc --showConfig [...tsc cli options]
to view the config just as typescript would resolve it (e.g. in the case of extends, etc).
Then it searches for all .d.ts
files in compilerOptions.outDir
and using compilerOptions.paths
, searches for any import statements and replaces any aliases it finds with the first path specified in compilerOptions.paths
(keeping in mind the baseUrl
of course).
In the special case of root dir aliases (e.g. @/*: [src/*]
), the root dir will just be removed. Instead of changing a path to something like ../src/folder
, it will get changed to ./folder
, the same folder, but in the output directory.
Notes
- It only checks for import statements.
- Technically only options/flags that affect the following
compilerOptions
need to be passed:paths
,rootDir
,outDir
,baseUrl
, or which config is used (--project/-p
flag). - In the case of listing multiple paths per path, it ignores other paths and does not try to verify the path exists/resolves correctly.
Why
While babel + babel-plugin-module-resolver can be used to transpile typescript with aliases correctly resolved, the only thing that can emit .d.ts
definition files is tsc
itself. But since the aliases aren't changed, this can lead to problems where the types seem to work perfectly fine when developing the package, but some types fail to resolve correctly when using the package as a dependency.
For example, say you have a library, and a function inside of it imports a type from an alias @/types
and then proceeds to use that as a return type:
lib
src
func.ts
import {SomeType} from "@/types"
export function func (): SomeType {...}
types
index.ts
export type SomeType = string
When built, babel can be made to correctly resolve the alias for func.js
, but dist/func.d.ts
will still contain the unchanged import {SomeType} from "@/types"
.
While developing lib
, because the tsconfig still tells typescript where to map @/types
everything will seem to work like normal. The type for func
will be correct, i.e. string
.
But when lib
is used in another project, the return type of func
will be any
. This is because typescript will look at import {SomeType} from "@/types"
and not be able to resolve it.
Or even worse, suppose your project is also using @/*
as an alias and it also has it's own type folder. In this case typescript might be able to resolve it, but to the wrong place! When resolving, typescript is only looking at the top level tsconfig so it will attempt to resolve "@/types"
in lib
using the paths in the project's tsconfig which will point @/types
to the project's type folder!
This is usually not a problem, but if you happened to export a type with the same name but with a different type, it would change the type of lib's func
!
project
node_modules
lib
dist
func.d.ts
import {SomeType} from "@/types" // resolves to project's src/types
export function func (): SomeType {...} // SomeType is now number!
src
types
index.ts
export type SomeType = number