What do I do if a JavaScript library doesn't have type information?

[ornate rivet]

Sometimes I want to use a library that can be installed via npm i x, but npm i @types/x gives me a 404. On rare occasions, I do find a d.ts file directly inside node_modules/x.

I've followed the TypeScript compiler error messages a couple of times, which led me to define my own d.ts file for that library, but both times--for reasons I can't remember--I could never get my project to compile with that library's d.ts file in my local project.

What are my options here? I'm looking for a nice intersection between type safety for the library API, smallest effort required on my part, and good practice.

[cloud spade]

when using libraries (from npm), 3 options:

• the library provide its types (available when installing the package)
• types for that library have been published by the community (available when installing @types/package)
• you have to write the types yourself, and add them to your sources

there is a whole section about how to write the types for a library
https://www.typescriptlang.org/docs/handbook/declaration-files/introduction.html

main idea is that you have a .d.ts file looking something like

declare module "name of the library" {
  // list all the exported classes, types, functions, etc.
  
  // e.g.
  export class Foo {}
  export function bar(baz: boolean): number;
}

of course it depends on what the library does
not all libraries work in the same way

some of them export functions, while others add items in the global scope, or extend some other packages

@ornate rivet

[ornate rivet]

I've read that a few times, but if I recall, it's written from the perspective of someone who wrote the JavaScript. I'm not sure where I'm supposed to put that file after I write it when it is for another library

[cloud spade]

it's written from the perspective of someone who wrote the JavaScript
rigth, but it also applies if you want to write typings for any library in general

[ornate rivet]

Or maybe my issue was I wasn't sure how I'm supposed to modify the tsconfig file to recognize it

[cloud spade]

I'm not sure where I'm supposed to put that file after I write it when it is for another library
it doesn't really matter
the only thing that matters is that it must be included in your sources

(included in the "include" section of your tsconfig https://www.typescriptlang.org/tsconfig#include)

[ornate rivet]

ah ok

[cloud spade]

what people sometimes do is put them in a new typings folder at the top level of their project directory

src/
  index.ts
typings/
  my-package/
    index.d.ts
tsconfig.json

it can (or must, don't remember) also be listed in the "typeRoots" https://www.typescriptlang.org/tsconfig#typeRoots

so that TS loads those types

(they even mention the typings/ folder)

[ornate rivet]

ah, yes! I remember this was my problem. Let me refresh my memory

[uncut crescent]

If typeRoots is specified, only packages under typeRoots will be included

[cloud spade]

yes, ofc
(have to add node_modules/@types back)

[uncut crescent]

(so no, it's just include)

[uncut crescent]

(typeRoots is to do with packages, in case that wasn't clear from the quote)

[ornate rivet]

what's a "package"?

[uncut crescent]

npm package

[cloud spade]

a library

[ornate rivet]

ah. Duh

[cloud spade]

wdym? it can be any folder really
TS will search for typings in it

[ornate rivet]

Maybe they mean it won't use a .d.ts file in the current project?

[uncut crescent]

but the folder must contain packages

[ornate rivet]

I'm a little fuzzy, but I think my issue may have been I was using types instead of typeRoots

[uncut crescent]

for your own stuff it's still include/files/exclude...

types is the same (also refers to npm packages)

[ornate rivet]

this is for a scenario where I wrote the d.ts file for a library that didn't have one, and that file is in my local project

[uncut crescent]

still not a package

[cloud spade]

right, tho you could also add your typings to your src dir, included in the "include" property

[uncut crescent]

you can declare typings for a library in a regular old .d.ts, that's something typescript lets you do

[ornate rivet]

exactly. So how do I associate my d.ts file with the package?

[uncut crescent]

declare module './the-import.js' {
}

or something like that

the './the-import.js' must match however you're importing it in your js

[ornate rivet]

I remember doing something like that. Maybe I used a different keyword like namespace, can't remember

[uncut crescent]

i don't believe declare namespace does the same thing

[cloud spade]

a namespace is just an extra scope
but kinda avoided nowadays

[uncut crescent]

which is quite odd to be fair, considering namespace should be mostly an alias for the (mostly legacy) module...

[ornate rivet]

So are you saying if I wrap the entire d.ts content in declare module './the-import.js' { } all I need to do is include the d.ts file in tsconfig and it can be used for a package?

[uncut crescent]

yeah, it should

[cloud spade]

if it is for the whole package, no need for the file extension

[ornate rivet]

I tried so many iterations I want to say I tried that. But I'm pretty sure I didn't try 'blah**.js**' ever.

[ornate rivet]

"it's"? nm, I get it.

[novel crest]

n_n#2622

Playground Link

Preview:ts // @filename: foo.d.ts declare module "asdf" { export const t: string } // @filename: aaa.js import {t} from "asdf" const what = t // ^?

You can choose specific lines to embed by selecting them before copying the link.

[uncut crescent]

!ts

[novel crest]

// @filename: foo.d.ts
declare module 'asdf' {
    export const t: string;
}
// @filename: aaa.js
import { t } from 'asdf';
const what = t;
//    ^? - const what: string```

[uncut crescent]

to be fair i normally don't mess with modules

but i think it only works if the name is exactly the same

[cloud spade]

you usually do the typings for a whole package at a time, not file by file

[uncut crescent]

well, if it is .js typescript wouldn't know which .js it refers to anyway...

[ornate rivet]

why is the second filename a js extension? Should that be a ts?

[uncut crescent]

oh

yeah ts would work too

[ornate rivet]

yeah that's what I was doing

[uncut crescent]

was kinda assuming you were using js for some reason

https://www.typescriptlang.org/dev/bug-workbench/?#code/PTAEAEDMEsBsFMB2BDAtvAXKSB7HA6AE3wBcBnAKEPgGNZkAneUVHQgVwVAHJkzDI3UAG8KocaHgAPAA44GJUDRyIyikljUNoiAOYBuCgF8KICDAQp0WZLdKVoqOQpGhFR7AxyoefAd0NlVUUAdwALZEUAXjdDMwkAPQB+IA)

[novel crest]

@uncut crescent Here's a shortened URL of your playground link! You can remove the full link from your message.

n_n#2622

Playground Link

Preview:ts // @filename: foo.d.ts declare module "asdf" { export const t: string } // @filename: aaa.ts import {t} from "asdf" const what = t // ^?

You can choose specific lines to embed by selecting them before copying the link.

[cloud spade]

not a problem
as long as the typings are correct, they match with the imports, and the imports work at runtime, it's all good then

[uncut crescent]

!ts

[novel crest]

// @filename: foo.d.ts
declare module 'asdf' {
    export const t: string;
}
// @filename: aaa.ts
import { t } from 'asdf';
const what = t;
//    ^? - const what: string```

[uncut crescent]

but yeah works just the same for ts

[uncut crescent]

right

if the imports are .js, generally you wouldn't be able to import the package name anyway

and same if the imports are 'package-name' and you're trying to declare module 'the-package.js'...

[ornate rivet]

I feel like I could compile the d.ts file OR the rest of the project, but I couldn't figure out how to do both. This probably had to do with me using types/typeRoots without including the defaults or something. Hopefully, there's enough information in this thread to help me next time.

I have one more question based off of my hazy memory: I think I've seen a library that puts its d.ts inside its own package. Does that automatically work correctly, or do I have to modify typeRoots to use it?

[uncut crescent]

well... do you even need to compile the .d.ts?

[uncut crescent]

if it's a npm package, normally it will work out of the box if they've gone through the effort of writing the types in the first place

[ornate rivet]

I guess I meant I couldn't get my project to compile

[uncut crescent]

o_O

[split silo]

(d.ts aren't meant to be compiled)

[cloud spade]

if the library is written in TS, one can use tsc to generate the typings based on the TS code
if the library is writte in JS, one must write the corresponding typings by hand
once the typings are done, they must be references in the package.json
after that, the package can be published on npm

[ornate rivet]

Is this why that works: Does the package tsconfig.ts explain how to use its local d.ts file, and when I run tsc, it interprets that?

[uncut crescent]

nah, what ascor just said

typescript looks in the package.json for a types field, which tells it where to find the types for the library

if you have local .d.ts files specially for your project, they will be picked up just like your regular .ts files

unless it's not covered by the include for some reason

e.g. if your code is in src/ but the .d.ts isn't

[ornate rivet]

huh? Why does that exist in package.json? I thought package.json is pure JavaScript/node and therefore would be TypeScript agnostic

I could probably Google that one on my own, but my brain never would've assumed that was the way to do it

[uncut crescent]

i'm not sure tsconfig.json even exists on published packages

which i assume would be the reason why

[uncut crescent]

(nor would the .ts files, of course)

[cloud spade]

right, but packages originally written in JS don't have a tsconfig.json
tho they must be able to reference types for TS users
so the only config file left and unique to all packages is the package.json

[split silo]

package.json is anything you need for the project/package

[uncut crescent]

along with tests, documentation (other than doc comments) and the like

[split silo]

imports, exports, types, eslintconfig, various other stuff

[ornate rivet]

yeah now there are multiple threads of conversation at once so I made things really confusing. What I mean to say is that either tsc errors complained about the d.ts file, OR they complained about some other part of my project. This was in a scenario where the previous commit, everything compiled fine.

[cloud spade]

tsc has an option to check your .d.ts files (and also the ones coming from npm) to make sure they are correct
https://www.typescriptlang.org/tsconfig#skipLibCheck

[ornate rivet]

hm, you're right. Yet sometimes the d.ts files are? Or am I just smoking crack and I never saw that? I feel like they have been in a few packages I've imported (non-@types/ ones).

[ornate rivet]

How convenient; it doesn't mention the default 😛 Whatever that is is what I was using at the time.

Anyway, I really complicated this conversation, Sorry. I thought the first thread of discussion was over before I started the second but it wasn't.

You have all been very helpful and I think I can mark this as solved.