Go To Source Definition feedback thread

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 @types library 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 @types package, 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):
  • 

• 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).

[jasonwilliams]

Hey @andrewbranch great work on this, I had a quick Q (you kind of mentioned it in your original comment).

Shouldn’t “Go To Definition” be the default for this and there should be a separate command for going to the type definition? I only ask this because it will be inconsistent with other languages being used in VSCode where “Go To Definition” would go to the original source definition of that symbol. I feel like most people using the “Go To Definition” command are expecting it to go to the source code not the type, so I was surprised to see the solution was not to change it but instead add a new command.

This will end up making TS/JS a “special snowflake” in the VSCode UI where you need to navigate to another command to get the same result that you’d have from other languages. I could be wrong but that seems to go against VSCode’s goal to have familiar UX across all languages

[remcohaszing]

I would love this to be the behaviour when I use <kbd>Ctrl</kbd> + Click. In my experience the current behaviour of Go to Definition is pretty useless. This new Go to Source Definition option fixes that. I kind of understand why this isn’t the default behaviour from reading previous comments, but I don’t see why this behaviour can’t be opt-in.