7

Github Project repo: https://github.com/Fralleee/lerna-intellisense-jsdoc-vscode

I have a monorepo project with two packages (Web & API). These are linked using Lerna. The Web project imports the API package, and the API requests are documented using JSDoc.

The documentation gets loaded perfectly if the API package is released and imported from NPM. working example

However, if it is run locally via Lerna & Webpack dev server, the documentation is lost and only available in the local code (in the API folder). not working

I have tried writing the documentation using modules and namespaces and searching for different types of solutions, but none seem to work.

The JSDoc and function:

/**
 * Get comments from JSON placeholder API
 * @namespace API
 * @module
 * @param {GetCommentsRequestExample} input PostId
 * @returns {Promise.<GetCommentsResponseExample>} Array of comments
 */
export const getComments = input => apiGet('https://jsonplaceholder.typicode.com/comments', input, GetCommentsRequest, GetCommentsResponse)

I can't figure out why the JSDoc works when the package is released but not when run locally.

EDIT after 2 hours of extra testing

I export everything using an index file in the API package. This index file imports everything from the package and then ships it like a single entry point.

If I define the function and JSDoc inside this index file directly, the JSDoc is available to other packages, even when run locally.

two different approaches

So it seems to be an issue with export -> import -> export again that messes up the JSDoc. This is not a solution since the Api-package has too much code to fit into a single file.

Fralle
  • 889
  • 6
  • 12

1 Answers1

5

I had this exact problem with VSCode and Lerna. The solution was to add a jsconfig.json to the root of the monorepo (or wherever the lerna.json is located).

It happens because VSCode needs to be told it is supposed to look for hints in the src/ directories of each package. I think it looks for the file specified in the main property of package.json by default (so when the package is built, it can see hints in this file - obviously no good for development!)

Some assumptions for an example configuration below:

  1. You have a packages/ directory containing all your packages
  2. Each package has a src/ directory containing the code
  3. Your packages have a namespace @foo (e.g., packages are called @foo/API or similar)

Add the following to jsconfig.json:

{
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "@foo/*": ["packages/*/src"]
    }
  }
}

After restarting VSCode / re-opening the folder the IntelliSense hints should show up correctly. If you are not using a namespace for your packages you can add multiple lines to paths instead, explicitly pointing to the correct src/ directory or use the include syntax from the documentation.

Hope this helps!

EDIT:

Each package needs a jsconfig.json too, so that it knows how to resolve sibling packages properly, e.g.,

{
  ...
  "paths": {
    "@foo/*": ["../*/src"]
  }
  ...
}
plasmid87
  • 1,450
  • 1
  • 14
  • 20
  • Awesome, this kind of resolved it. However not fully (maybe it isn't possible?). The intellisense I get from the root jsconfig is not as detailed as the one I get from each package locally (each package has its own jsconfig aswell). For example I can't use object as type definitions, also it seems to lose the return declaration from the intellisense. https://i.imgur.com/ncH59GK.png When you resolved your problems, did you happen to resolve these issues aswell? I have tried removing each packages jsconfig, this only reduced the more detailed intellisense to the same used globally. – Fralle Jul 31 '19 at 07:46
  • Unfortunately I think it's just the way the different "peek" functions work. I get the same behaviour when I hover (green in your screenshot) and then when typing the function (red in your screenshot). I just had a look at the VSCode docs and it looks like this is just the way VSCode does it: https://code.visualstudio.com/docs/languages/typescript#_hover-information - have a look at the hover information vs signature help and I think it's the same as what we're seeing – plasmid87 Jul 31 '19 at 08:48
  • Yeah, hover information displays more detail, however what I meant was that intellisense and hover detail information is lost when I hover a function from another package, but it's available if I hover inside the package. Only thing available is the JSDoc but not the intellisense – Fralle Jul 31 '19 at 08:54
  • Ah I see what you mean. Sorry I haven't seen this problem before. It could be an extension changing the behaviour or maybe my setup has something different about it – plasmid87 Jul 31 '19 at 09:02
  • Uploaded a very miniature/basic version of my repo to github if you would like to test it out and see. https://github.com/Fralleee/lerna-intellisense-jsdoc-vscode – Fralle Jul 31 '19 at 09:13
  • I just made a pull request - there was a missing step - each package also needs a `jsconfig.json` paths set - I'll update my answer – plasmid87 Jul 31 '19 at 09:36
  • Hmm, the hover information from "requestFromIndex" was always available (declared in index) but the "requestFromSrc" isn't, and that is kind of the issue. Not sure if this solved it, it doesn't seem like it. – Fralle Jul 31 '19 at 09:56
  • Let us [continue this discussion in chat](https://chat.stackoverflow.com/rooms/197265/discussion-between-plasmid87-and-fralle). – plasmid87 Jul 31 '19 at 10:27