7 ms·

Tsdocs.dev: Type docs for any JavaScript library

224 points by webartisan 3y ago

waldofind 3y ago
Looks like rust inspired (docs.rs) but for the typescript ecosystem. Neat!
- radicalriddler 3y ago
  I saw this on twitter a week or two ago and that's exactly how he explained the purpose
conandole 3y ago
A good example of a well documented library is three.js https://tsdocs.dev/docs/three/0.159.0/classes/Bone.html https://tsdocs.dev/docs/three/0.159.0/classes/Bone.html It’s fun to just read through all of the different entities in the 3D ecosystem, even though I’ve only used it only a couple of times.
- prideout 3y ago
  Agreed although I'm somewhat confused since the three js source code is JavaScript not TypeScript.
  - WorldMaker 3y ago
    It is auto-redirecting to the @types/three package and getting the types from DefinitelyTyped. You can see that in the breadcrumbs, but it might be something that could be better highlighted (and maybe even redirect the URL to make even more obvious to developers).
- _the_inflator 3y ago
  Great reference. To this date, one of the best well-documented code is jQuery: https://github.com/jquery/jquery/blob/main/src/core/init.js https://github.com/jquery/jquery/blob/main/src/core/init.js I learned a lot from looking into the code.
montyanderson 3y ago
It might have just received the hug of death. Otherwise, this is fantastic; I've been looking for something like this.
- teaearlgraycold 3y ago
  Should get those bytes on a CDN!
coderag 3y ago
For me, its stuck at Installing package and extracting docs... with a nice toaster GIF
pastelsky 3y ago
Author here: I created this because I found myself peeping inside type declaration files too often, and the only way to do that was by installing the package first. tsdocs.dev helps you check the API surface of a good number of JS libraries and their past versions — usually a quick search away. There's something powerful about speed and being able to answer questions in seconds that usually take minutes. edit: The server might be overloaded with requests as we prime up our caches, but do visit back after HN's done hugging us to death. You can show your support and help cover a part of server costs if this (or bundlephobia.com) saved you time. https://github.com/sponsors/pastelsky https://github.com/sponsors/pastelsky
- karpour 3y ago
  Congrats, this looks fantastic and will be useful for many!
- WorldMaker 3y ago
  Found a fun error "TypeDefinitionResolveError" for a package that includes Typescript sources. Best guess, it may be related to the package.json uses a modern "bare" exports field ("exports": "./index.js"; no "main", no "types") where "index.ts" exists in the package as well. (Not a lot of projects use this today, but it is a modern way to publish projects that will likely increase.) Typescript itself works just fine with this with this type of package with "moduleResolution": "node" (tsconfig/CLI options) with recent version using recent enough ES targets or with "moduleResolution": "node16" in older versions/older ES targets/non-ES targets. https://tsdocs.dev/search/docs/butterfloat https://tsdocs.dev/search/docs/butterfloat Hope that's useful enough to debug the error.
- maxloh 3y ago
  There isn't a LICENSE file in the repo. Can you add one?
- spankalee 3y ago
  This is really awesome work! This takes a big burden off of individual packages from publishing their own API docs (having done that I know how hard it can be!), and having a centralized API viewer can offer a lot of advantages over separate docs. A couple of things I would suggest: 1. Track re-exports and cross-package references and allow crossref links to go into other packages. If package A uses rxjs, then links to the rxjs types should go to the canonical definitions in the rxjs package. (figuring out the canonical declaration can be tricky because it's not always the original declaration though) 2. Organizing by type isn't always a great introduction or way to navigate a package. On the Lit project at https://lit.dev/docs/api https://lit.dev/docs/api we re-organized the API docs by categories and the most important API surfaces. There aren't standard jsdocs for this, but a few straightforward things like @category could be used to offer an alternate top-level nav for a package. Also consider supporting the @packageDocumentation tag from tsdoc. 3. Consider showing files other than the README. Relative links to things like CONTRIBUTING.md currently break. Alternatively interpret all relative links as pointing to github.com or npmjs.com. It'd be great to have a way to link from the README into API docs to guide readers. The community doesn't have a great convention for this unfortunately.
WorldMaker 3y ago
Some quick bits of feedback after a small bit of skimming (between bad gateway errors, sorry for contributing to all the over-traffic): - It would be great to see some of the fields from package.json shown as an overview above/next to the README of packages. The homepage and repository fields in particular are often quite useful to have quick access to. You could pull up npmjs.com directly next to this site, but it might be nice to have it all in one place. - In cases where there is an auto-redirect from package-name to @types/package-name it might be nice to still show the README (and package.json metadata if added) of the original package-name. - Typedoc upstream includes a dark theme and does the prefers-color-scheme auto-setup. This might be nice to have here, too.
- matsz 3y ago
  > it might be nice to still show the README (and package.json metadata if added) of the original package-name This would be great, @types/* docs are rarely ever useful. Although it'd be still nice to indicate that the types are not available in the original package.
esamatti 3y ago
This is awesome! Thanks for sharing.
jjice 3y ago
This is great, bookmarked. I hope we can see this in search results in the future. I started a new job in TypeScript back at the beginning of the year and the lack of standardized library documentation viewing is a surprising gap in the TS ecosystem. This is great, thank you!
whoisthemachine 3y ago
This is a better looking version of what Java and C# have had for a long time (kudos to the author for that!), is that the inspiration for this tool? https://docs.oracle.com/javase/8/docs/technotes/tools/windows/javadoc.html https://docs.oracle.com/javase/8/docs/technotes/tools/window... https://dotnet.github.io/docfx/ https://dotnet.github.io/docfx/ I saw the author mentioned in another comment that they found themselves peeping inside type declaration files "too often". While I do often use sites generated by the above tools to discover new API's that suit my needs, diving into the actual code using a good decompiler is still my first move, as it is often cheaper than seeking out the documentation online, and it will show me the actual implementation as well. So in my opinion there is no shame in looking inside the declaration files!
- WorldMaker 3y ago
  The direct relative tool to javadoc/docfx is Typedoc [1], which this tsdocs.dev hosts (a fork of). The benefits tsdocs.dev adds on top of Typedoc are the ability to open any arbitrary npm package (plus some smarts for @types/ package redirects) inside a hosted Typedoc whether or not that package's own docs site includes a Typedoc view or not. I use (Markdown plugin versions of) Typedoc output in some of my packages' docs sites. It is a handy tool and I know some users appreciate having it built with the other docs. I'm also personally equally likely to jump directly to a declaration file rather than pull up a documentation site, but I appreciate things like Typedoc when I do find them on other projects' documentation sites, and I appreciate tsdocs.dev for giving a way to further do it for arbitrary packages that don't include it, even if in many cases that won't be the first tool I use for the job because I'm comfortable enough directly in declarations files. (Also, you mention a good decompiler, its important to remember that Typescript declaration files generally aren't decompiler artifacts and may be inaccurate to the code actually running. I'm more likely to trust a package that generates its own Typedocs in their documentation as that implies they keep their declarations up to date and/or write their library in Typescript directly. In other sorts of projects for me sometimes the next jump from the declaration file is to the source files. I've PRed a lot of declaration file fixes over the years.) [1] https://typedoc.org/ https://typedoc.org/
turboturbo 3y ago
For `@remix-run/react`, I get the following error: UNEXPECTED_DOCS_POLL_FAILURE 500 {"statusCode":500,"error":"Internal Server Error","message":"Cannot read properties of undefined (reading 'changePriority')"}
ttyyzz 3y ago
Bad gateway / Error code 502
jstasiak 3y ago
Looks like a great initiative – I wish there was a reliable TS/JS equivalent of https://docs.rs https://docs.rs (even considering rustdoc's deficiencies[1]). I went through this exercise recently and so far my experience with trying to produce documentation from a somewhat convoluted TS codebase[2] has been disappointing. I would claim it's a consequence of the library's public (user-facing) API substantially differing from how the actual implementation is structured. Typedoc produces bad results for that codebase so sphinx-js, which I wanted to use, doesn't have much to work with. I ultimately documented things by hand, for now, the way the API is meant to be used by the user. Compare: https://ts-results-es.readthedocs.io/en/latest/reference/api/index.html https://ts-results-es.readthedocs.io/en/latest/reference/api... vs https://tsdocs.dev/docs/ts-results-es/4.1.0-alpha.1/index.html https://tsdocs.dev/docs/ts-results-es/4.1.0-alpha.1/index.ht... https://www.jsdocs.io/package/ts-results-es#package-index https://www.jsdocs.io/package/ts-results-es#package-index [1] https://github.com/rust-lang/rust/issues/66249 https://github.com/rust-lang/rust/issues/66249 [2] https://github.com/lune-climate/ts-results-es https://github.com/lune-climate/ts-results-es
simonsarris 3y ago
Wow it works quite well: https://tsdocs.dev/docs/gojs/2.3.12/classes/Diagram.html https://tsdocs.dev/docs/gojs/2.3.12/classes/Diagram.html vs the real docs https://gojs.net/latest/api/symbols/Diagram.html https://gojs.net/latest/api/symbols/Diagram.html Somewhat a problem: The constructor for the class is halfway down the page, and there's no scrollbar!
deleted 3y ago
[deleted]
Rapzid 3y ago
Awesome. What do you think about this long standing Typescript issue? https://stackoverflow.com/questions/57683303/how-can-i-see-the-full-expanded-contract-of-a-typescript-type https://stackoverflow.com/questions/57683303/how-can-i-see-t... It's been my experience introducing and pushing Typescript at multiple companies that people get lost, frustrated, and then push back because they can't untangle and make sense of type hierarchies in order to satisfy the compiler... Even I get tired of control clicking up and down hierarchies trying to build a mental model of exactly what's expected. It's amazing to me that this issue has been ignored so long by the TypeScript team.
- k__ 3y ago
  As far as I know you get something like that with Zod. The inferred static types don't have names anymore, they just include the resulting types.
stevage 3y ago
This looks great. It's a little bit confusing comparing these docs vs "official ones". Consider: https://tsdocs.dev/docs/tonal/5.1.2/interfaces/_internal_.Chord.html https://tsdocs.dev/docs/tonal/5.1.2/interfaces/_internal_.Ch... https://tonaljs.github.io/tonal/module-Chord.html https://tonaljs.github.io/tonal/module-Chord.html There seem to be things missing from each.
Kab1r 3y ago
> TypeDefinitionResolveError > Failed to resolve types for this package. This package likely does not ship with types, and it does not have a corresponding package `@types` package from which reference documentation for its APIs can be built. I was hoping it would work with libraries that don't ship with types.

224 points by webartisan 3y ago

waldofind 3y ago

Looks like rust inspired (docs.rs) but for the typescript ecosystem. Neat!

radicalriddler 3y ago
I saw this on twitter a week or two ago and that's exactly how he explained the purpose

conandole 3y ago

A good example of a well documented library is three.js https://tsdocs.dev/docs/three/0.159.0/classes/Bone.html https://tsdocs.dev/docs/three/0.159.0/classes/Bone.html It’s fun to just read through all of the different entities in the 3D ecosystem, even though I’ve only used it only a couple of times.

prideout 3y ago
Agreed although I'm somewhat confused since the three js source code is JavaScript not TypeScript.
- WorldMaker 3y ago
  It is auto-redirecting to the @types/three package and getting the types from DefinitelyTyped. You can see that in the breadcrumbs, but it might be something that could be better highlighted (and maybe even redirect the URL to make even more obvious to developers).
_the_inflator 3y ago
Great reference. To this date, one of the best well-documented code is jQuery: https://github.com/jquery/jquery/blob/main/src/core/init.js https://github.com/jquery/jquery/blob/main/src/core/init.js I learned a lot from looking into the code.

montyanderson 3y ago

It might have just received the hug of death. Otherwise, this is fantastic; I've been looking for something like this.

teaearlgraycold 3y ago
Should get those bytes on a CDN!

coderag 3y ago

For me, its stuck at Installing package and extracting docs... with a nice toaster GIF

pastelsky 3y ago

Author here: I created this because I found myself peeping inside type declaration files too often, and the only way to do that was by installing the package first. tsdocs.dev helps you check the API surface of a good number of JS libraries and their past versions — usually a quick search away. There's something powerful about speed and being able to answer questions in seconds that usually take minutes. edit: The server might be overloaded with requests as we prime up our caches, but do visit back after HN's done hugging us to death. You can show your support and help cover a part of server costs if this (or bundlephobia.com) saved you time. https://github.com/sponsors/pastelsky https://github.com/sponsors/pastelsky

karpour 3y ago
Congrats, this looks fantastic and will be useful for many!
WorldMaker 3y ago
Found a fun error "TypeDefinitionResolveError" for a package that includes Typescript sources. Best guess, it may be related to the package.json uses a modern "bare" exports field ("exports": "./index.js"; no "main", no "types") where "index.ts" exists in the package as well. (Not a lot of projects use this today, but it is a modern way to publish projects that will likely increase.) Typescript itself works just fine with this with this type of package with "moduleResolution": "node" (tsconfig/CLI options) with recent version using recent enough ES targets or with "moduleResolution": "node16" in older versions/older ES targets/non-ES targets. https://tsdocs.dev/search/docs/butterfloat https://tsdocs.dev/search/docs/butterfloat Hope that's useful enough to debug the error.
maxloh 3y ago
There isn't a LICENSE file in the repo. Can you add one?
spankalee 3y ago
This is really awesome work! This takes a big burden off of individual packages from publishing their own API docs (having done that I know how hard it can be!), and having a centralized API viewer can offer a lot of advantages over separate docs. A couple of things I would suggest: 1. Track re-exports and cross-package references and allow crossref links to go into other packages. If package A uses rxjs, then links to the rxjs types should go to the canonical definitions in the rxjs package. (figuring out the canonical declaration can be tricky because it's not always the original declaration though) 2. Organizing by type isn't always a great introduction or way to navigate a package. On the Lit project at https://lit.dev/docs/api https://lit.dev/docs/api we re-organized the API docs by categories and the most important API surfaces. There aren't standard jsdocs for this, but a few straightforward things like @category could be used to offer an alternate top-level nav for a package. Also consider supporting the @packageDocumentation tag from tsdoc. 3. Consider showing files other than the README. Relative links to things like CONTRIBUTING.md currently break. Alternatively interpret all relative links as pointing to github.com or npmjs.com. It'd be great to have a way to link from the README into API docs to guide readers. The community doesn't have a great convention for this unfortunately.

WorldMaker 3y ago

Some quick bits of feedback after a small bit of skimming (between bad gateway errors, sorry for contributing to all the over-traffic): - It would be great to see some of the fields from package.json shown as an overview above/next to the README of packages. The homepage and repository fields in particular are often quite useful to have quick access to. You could pull up npmjs.com directly next to this site, but it might be nice to have it all in one place. - In cases where there is an auto-redirect from package-name to @types/package-name it might be nice to still show the README (and package.json metadata if added) of the original package-name. - Typedoc upstream includes a dark theme and does the prefers-color-scheme auto-setup. This might be nice to have here, too.

matsz 3y ago
> it might be nice to still show the README (and package.json metadata if added) of the original package-name This would be great, @types/* docs are rarely ever useful. Although it'd be still nice to indicate that the types are not available in the original package.

esamatti 3y ago

This is awesome! Thanks for sharing.

jjice 3y ago

This is great, bookmarked. I hope we can see this in search results in the future. I started a new job in TypeScript back at the beginning of the year and the lack of standardized library documentation viewing is a surprising gap in the TS ecosystem. This is great, thank you!

whoisthemachine 3y ago

This is a better looking version of what Java and C# have had for a long time (kudos to the author for that!), is that the inspiration for this tool? https://docs.oracle.com/javase/8/docs/technotes/tools/windows/javadoc.html https://docs.oracle.com/javase/8/docs/technotes/tools/window... https://dotnet.github.io/docfx/ https://dotnet.github.io/docfx/ I saw the author mentioned in another comment that they found themselves peeping inside type declaration files "too often". While I do often use sites generated by the above tools to discover new API's that suit my needs, diving into the actual code using a good decompiler is still my first move, as it is often cheaper than seeking out the documentation online, and it will show me the actual implementation as well. So in my opinion there is no shame in looking inside the declaration files!

WorldMaker 3y ago
The direct relative tool to javadoc/docfx is Typedoc [1], which this tsdocs.dev hosts (a fork of). The benefits tsdocs.dev adds on top of Typedoc are the ability to open any arbitrary npm package (plus some smarts for @types/ package redirects) inside a hosted Typedoc whether or not that package's own docs site includes a Typedoc view or not. I use (Markdown plugin versions of) Typedoc output in some of my packages' docs sites. It is a handy tool and I know some users appreciate having it built with the other docs. I'm also personally equally likely to jump directly to a declaration file rather than pull up a documentation site, but I appreciate things like Typedoc when I do find them on other projects' documentation sites, and I appreciate tsdocs.dev for giving a way to further do it for arbitrary packages that don't include it, even if in many cases that won't be the first tool I use for the job because I'm comfortable enough directly in declarations files. (Also, you mention a good decompiler, its important to remember that Typescript declaration files generally aren't decompiler artifacts and may be inaccurate to the code actually running. I'm more likely to trust a package that generates its own Typedocs in their documentation as that implies they keep their declarations up to date and/or write their library in Typescript directly. In other sorts of projects for me sometimes the next jump from the declaration file is to the source files. I've PRed a lot of declaration file fixes over the years.) [1] https://typedoc.org/ https://typedoc.org/

turboturbo 3y ago

For `@remix-run/react`, I get the following error: UNEXPECTED_DOCS_POLL_FAILURE 500 {"statusCode":500,"error":"Internal Server Error","message":"Cannot read properties of undefined (reading 'changePriority')"}

ttyyzz 3y ago

Bad gateway / Error code 502

jstasiak 3y ago

Looks like a great initiative – I wish there was a reliable TS/JS equivalent of https://docs.rs https://docs.rs (even considering rustdoc's deficiencies[1]). I went through this exercise recently and so far my experience with trying to produce documentation from a somewhat convoluted TS codebase[2] has been disappointing. I would claim it's a consequence of the library's public (user-facing) API substantially differing from how the actual implementation is structured. Typedoc produces bad results for that codebase so sphinx-js, which I wanted to use, doesn't have much to work with. I ultimately documented things by hand, for now, the way the API is meant to be used by the user. Compare: https://ts-results-es.readthedocs.io/en/latest/reference/api/index.html https://ts-results-es.readthedocs.io/en/latest/reference/api... vs https://tsdocs.dev/docs/ts-results-es/4.1.0-alpha.1/index.html https://tsdocs.dev/docs/ts-results-es/4.1.0-alpha.1/index.ht... https://www.jsdocs.io/package/ts-results-es#package-index https://www.jsdocs.io/package/ts-results-es#package-index [1] https://github.com/rust-lang/rust/issues/66249 https://github.com/rust-lang/rust/issues/66249 [2] https://github.com/lune-climate/ts-results-es https://github.com/lune-climate/ts-results-es

simonsarris 3y ago

Wow it works quite well: https://tsdocs.dev/docs/gojs/2.3.12/classes/Diagram.html https://tsdocs.dev/docs/gojs/2.3.12/classes/Diagram.html vs the real docs https://gojs.net/latest/api/symbols/Diagram.html https://gojs.net/latest/api/symbols/Diagram.html Somewhat a problem: The constructor for the class is halfway down the page, and there's no scrollbar!

deleted 3y ago

[deleted]

Rapzid 3y ago

Awesome. What do you think about this long standing Typescript issue? https://stackoverflow.com/questions/57683303/how-can-i-see-the-full-expanded-contract-of-a-typescript-type https://stackoverflow.com/questions/57683303/how-can-i-see-t... It's been my experience introducing and pushing Typescript at multiple companies that people get lost, frustrated, and then push back because they can't untangle and make sense of type hierarchies in order to satisfy the compiler... Even I get tired of control clicking up and down hierarchies trying to build a mental model of exactly what's expected. It's amazing to me that this issue has been ignored so long by the TypeScript team.

k__ 3y ago
As far as I know you get something like that with Zod. The inferred static types don't have names anymore, they just include the resulting types.

stevage 3y ago

This looks great. It's a little bit confusing comparing these docs vs "official ones". Consider: https://tsdocs.dev/docs/tonal/5.1.2/interfaces/_internal_.Chord.html https://tsdocs.dev/docs/tonal/5.1.2/interfaces/_internal_.Ch... https://tonaljs.github.io/tonal/module-Chord.html https://tonaljs.github.io/tonal/module-Chord.html There seem to be things missing from each.

Kab1r 3y ago

> TypeDefinitionResolveError > Failed to resolve types for this package. This package likely does not ship with types, and it does not have a corresponding package `@types` package from which reference documentation for its APIs can be built. I was hoping it would work with libraries that don't ship with types.