Description
Seeding a thread for feedback on / issues with Go To Source Definition (#48264) ahead of the 4.7 release.
TL;DR
TypeScript 4.7 (already in nightly) and VS Code 1.67 (already released) will contain a new navigation command called “Go To Source Definition” that attempts to find a definition in non-ambient TypeScript or JavaScript code. (Ambient code means .d.ts files or declare contexts inside regular TS files—in other words, definitions separated from concrete implementation.) The most common reason to use this is if you want to look at the JS implementation of something you imported from node_modules, where Go To Definition only jumps to .d.ts files.
Our ability to find concrete definitions in JS when Go To Definition returns only .d.ts files varies wildly based on a lot of complicated stuff. Sometimes this feature returns results that we can be nearly 100% confident in. Sometimes it returns a guess that definitely might be wrong. Sometimes it returns nothing. If it does something that surprises you, I would like to hear about it here, even though it might be a known limitation. Make sure to include:
- The code you triggered the request on
- The import statement importing the thing you tried to navigate to
- What result(s) were returned, if any (screenshot is ok for these top 3)
- What version of the library you tried to navigate to is in your node_modules (check its package.json)
- If you had a corresponding
@typeslibrary in your node_modules, and what version it is
Known limitations
-
The main thing that makes this feature go from 100% confidence to guesses that could go wrong is JavaScript whose exports we can’t analyze, probably because they have some kind of UMD wrapper. When that happens, we try guesses. The quality/presence of guesses is impacted by:
- How closely the directory structure of a
@typespackage, if present, matches that of its JS counterpart - Whether declarations in a single JS file share the same name with others at the same level of nesting. For example,
import { add } from "lodash"currently returns three results; two refer to the correct function, but one is a false positive (SetCache.prototype.add): -
- How closely the directory structure of a
-
Function parameters, and properties accessed on them, are unlikely to return any results, because definition information doesn’t tell us every caller of the function—we only know where the parameter itself is declared, and what type it expects. The values passed into it could come from anywhere, even if in practice they have a single definition provided by a library:
import yargs from "yargs"; // ^ works here yargs(process.argv.slice(2)) .command( // ^ works here "$0 <traceDir>", yargs => yargs.positional("traceDir", { // ^ goes to arrow function param // ^ doesn't find anything!
FAQ and Q that should be FA but aren’t
Can you please make this the default / give me an option to make this the default for Go To Definition / ⌘-click?
Not right now, but comment / 👍 an existing relevant comment if you feel strongly about this and tell me a bit about why.
Can I make a keyboard shortcut for this?
Yes. Command palette → Preferences: Open Keyboard Shortcuts (JSON)
{
"key": "cmd+shift+F12",
"command": "typescript.goToSourceDefinition",
"when": "editorTextFocus"
}What’s the difference between this and Go To Implementations?
Go To Implementations is an interesting algorithm that does a lot of different things and is a bit hard to explain holistically. The two commands are similar in that they both avoid returning ambient results. However, Go To Implementations uses Find All References under the hood to (among other things) search for values that satisfy some type. Go To Source Definition mostly uses Go To Definition under the hood, which traces variables/properties to their declarations and through imports/exports. It does not try to find the origin of every possible value that might come to inhabit that variable/property. The thing that makes Go To Source Definition different from every other command is that if Go To Definition returns only results in .d.ts files, it will try again with a different module resolver that completely ignores .d.ts files, allowing it to find JS files that are otherwise “shadowed” by .d.ts files in your actual compilation.
I’m a DefinitelyTyped maintainer. What can I do to increase the chances Go To Source Definition works on exports from my definitions?
Ensure the directory structure of your definitions is identical to that of the JS library you’re typing (at least as far as the public API goes). This means don’t move types out of index.d.ts into a helpers.d.ts just for code organization—helpers.d.ts should only exist if it types a helpers.js file. Conversely, if the JS library is broken up into many files that all get re-exported by the index/main file, declare your types in these files and re-export them too. (This is the correct way to author DT libraries anyway; Go To Source Definition compatibility is just a secondary benefit.)
I’m a library author who ships my own types. What can I do to make Go To Source Definition work on exports from my library?
Consider if it’s appropriate to ship your TypeScript sources to npm. If you do, make sure you compile with "declarationMap": true and ship your .d.ts.map files to npm too. When you do that, Go To Definition will already navigate to your .ts sources, making Go To Source Definition unnecessary (it simply executes Go To Definition when this happens).