Gatsby: docs: absolue imports

[moonmeister]

Summary

Currently the docs recommend to set absolute imports within webpack. While this does work it only applies to webpack. If you are trying to eject from gatsby's eslint rules or use other tools they will not know how to resolve these and will complain. For those using yarn 1 or 2 there is a better way:

the best practice is to set them in your package.json:

{
  "dependencies": {
      "hooks": "link:./src/hooks",
  }
}

I read this some where more authoritative but can't find where (yarn docs I believe), I'll keep looking and update this if I find the link.

https://yarnpkg.com/features/protocols

Motivation

This allows all tools to resolve these paths and preps you for yarn pnp.

Steps to resolve this issue

Draft the doc

• [ ] Update the doc, following the format listed in these resources:
  
  
  
  • Overview on contributing to documentation
  
  
  • Docs Templates
  
  
  • Example of a similar article
  
  

Open a pull request

• [ ] Open a pull request with your work including the words "closes #[this issue's number]" in the pull request description

[snitin315]

@moonmeister I would like to help with this one.

[moonmeister]

Go for it! Thanks! Ping me when you open the PR and I'll give it a look.

[stephenisau]

@moonmeister Can I work on this?

[moonmeister]

I don't care, I haven't seen another PR so go for it.

[laurieontech]

Thanks so much for opening this issue and doing the research.

However, if this solution is only available for yarn then I don't believe it's something we should include. As a general rule the docs are based on the assumption of using npm. Adding caveats about yarn is not something we've done in the past unless it was for contributing instructions.

I'm going to close this for the moment but if I'm incorrect about the intended change please feel free to re-open with additional context.

[moonmeister]

Laurie, is that really Gatsby's policy? every doc I've seen indicates commands and solutions for both npm and yarn. given Gatsby's dependency on yarn for its own project it seems strange you'd specifically exclude information that makes developers lives easier.

this is the difference between lots of manual configs and headaches to make things work together and a simple edit of the package.json.

update: oops wrong button, only meant to comment, not reopen. it's your call but seems like a strange rule.

[laurieontech]

The goal is to converge on a specific package manager in order to make it easier for users to move between docs and not have pre-requisite knowledge. Since npm is pre-packaged with Node.js and that's a dependency we specify, the docs have focused on npm.

That being said, I'd like to understand what you experienced a bit better to see if there is a way of including something in the docs that will prevent others having that issue going forward.

Your description mentions that the example works but only applies to webpack. Since the document this PR references is specifically about configuring webpack I'm wondering if there is more context. Can you provide an example of what you ran into?

[moonmeister]

Hey Laurie...without going to deep let me try to explain. Like I said above Changing the webpack config ONLY affects webpack resolutions. Gatsby is happy with this change and it let site's using only Gatsby's default configuration work. If I use Prettier, Eslint,typescript, testing libraries, etc which don't care about Webpack config, then these tools will fail when attempting to find these dependencies. These tools might be used explicitly or might be integrated with an IDE like VSCode and are suppose to "just work".

There are three solutions I am aware of...

First...reconfigure this for EVERY tool. Aka...Every other config must support and be configured to use the same aliases. This is cumbersome, repetitive, and not a good solution or user experience.

Second...Configure your other tools to use Webpack's resolutions...I'm not sure what kind of support there is for this in different tools. I have only done it in Eslint:

"settings": {
    "import/resolver": {
      "webpack": {
        "config": "./webpack.config.js"
      }
    }
  }

But someone has to have know how to do this (I recall spending a while figuring this out last year, when I had to do it)...it's a lot of time and energy that most may just give up on.

Third....the solution above...most modern tools use the resolve package which is what supports this link: format. yarn simply also uses the [email protected]+ package for module resolution and thus supports this format of aliasing modules. Not sure why npm doesn't support this but...then again..it's npm.

As a side note...i ran across this because I was playing with the new yarn 2 / pnp...this is a requirement for compatibility and can't support package specific resolution. Thus they moved these custom resolutions into the package.json where they should be.

Because this is a no config solution (effectively)...Whether or not a dev is using yarn 2 or 1 I think this is generally a really smart feature to use and saves devs time and headache.

I understand if Gatsby decides this is out-of-scope...but of all the things they document...this seems like a strange one to exclude.

[wardpeet]

Thanks @moonmeister, this shows how broken the ecosystem is, and Rome is being built.

I do feel your pain. I mostly use https://github.com/tleunen/eslint-import-resolver-babel-module which also tells me how to configure eslint, and because of babel, webpack has the right config as well. I haven't thought of link: before so TIL :). The problem with link as stated above its yarn only and we still have to tell babel to transpile `node_modules/hooks, as stated in our docs https://github.com/gatsbyjs/gatsby/blob/master/docs/docs/add-custom-webpack-config.md#modifying-the-babel-loader

What if we keep things as is but add a section about "yarn" + "link" and using multiple tools like eslint/typescript/.... We don't want to advocate yarn too much but If it's a small section, I think it's okay.

[moonmeister]

yeah, sounds good. Given that I can barely find any docs on this on the internet it's worth a small section so people at least know.

[laurieontech]

Thanks for chiming in Ward! Let’s do this, I’ll reopen the closed PR and discuss with the author how to change it around as a call out note?
Appreciate everyone’s insights on this!