Docz: onCreateWebpack is never called ?

[MaximeHeckel]

Bug Report

Describe the bug

I added a custom gatsby-node.js in my docz project (v2.0.0-rc.67) with onCreateWebpackConfig but it seems that it's actually never called whether it's when running docz dev or docz build.

exports.onCreateWebpackConfig = ({ plugins, actions }) => {
  const { setWebpackConfig } = actions;
  setWebpackConfig({
    plugins: [plugins.define({
     FOO: 'BAR'
    )]
  });
};

If I try to log process.env.FOO in my code it's undefined.

To Reproduce
I even tried to throw an error in the mix, it never seems to be reached although the gatsby-node.custom.js is in the resulting .docz gatsby project.

exports.onCreateWebpackConfig = ({ plugins, actions }) => {
  const { setWebpackConfig } = actions;
   throw hello // <- never reached
  setWebpackConfig({
    plugins: [plugins.define({
     FOO: 'BAR'
    )]
  });
};

Environment

• docz version: [e.g. 2.0.0-rc.x]
• OS: macOS 10.15
• Node/npm version: [e.g. Node 10]

Additional context/Screenshots
Add any other context about the problem here. If applicable, add screenshots to help explain.

[rakannimer]

Hey,

onCreateWebpackConfig should be called. It's placed in gatsby-node.custom.js and then required and called from .docz/gatsby-node.js

I think I can see 2 problems with your config:

1. Not prefixing FOO with process.env
2. Not wrapping BAR with a JSON.stringify

Does replacing your file with the below work ?

exports.onCreateWebpackConfig = ({ plugins, actions }) => {
  const { setWebpackConfig } = actions

  setWebpackConfig({
    plugins: [
      plugins.define({
        'process.env.FOO': JSON.stringify('BAR'),
      }),
    ],
  })
}

[MaximeHeckel]

I just gave it a try with this exact implementation but when running console.log(process.env.FOO) in one of the components I'm writing the documentation for I get undefined

[MaximeHeckel]

Little update @rakannimer I found out what is happening, it's pretty much due to our own setup but you'll probably find this interesting:

I thought it was not important but we're doing an import statement in our gatsby-node.js

const { getVarDefs } = require('./tools/build/envVars');

this gets passed to the gatsby-node.custom.js in .docz when running yarn docz dev
which ends up being imported within .docz/gatsby-node.js with:

try {
  gatsbyNodeCustom = require('./gatsby-node.custom'); <== THIS FAILS! the message: Cannot find module './tools/build/envVars' so it becomes a NO_OP and fails silently 
} catch (err) {
  gatsbyNodeCustom = {
    onCreateWebpackConfig: NO_OP
  };
}

So we ended up with a silent error hence why I was thinking onCreateWebpackConfig was not called.
we can work around this by importing everything from the standpoint of .docz but perhaps it is something you want to support in the GA release of DOCZ 2.0

[rakannimer]

Ohh ! Thanks for sharing what happened.

That makes a lot of sense and often trips me up too !

This is definitely something that should be improved from docz's side.

I think we should log the error when it fails to make sure the user knows that an error occurred and make it a bit smarter (it should differentiate between not finding the file and failing to require it).

We should also maybe add a warning in the docs about requiring relative paths in files that are synced to .docz.

Let's keep this issue open to track the progress on this 👍

[stefcameron]

We should also maybe add a warning in the docs about requiring relative paths in files that are synced to .docz.

Yes, please, I think that would be really helpful.

[dpvitt]

Surfacing these errors or adding to docs would definitely help here! Just lost quite a bit of time trying to figure out this issue too 👍 🎉

[rakannimer]

Hey @stefcameron & @dpvitt

I'm very sorry you had to waste time on this !

As a fellow noob in writing documentation where do you suggest we put this ?

In the readme or should we add a FAQ section with question/answer format ?

[dpvitt]

All good, I'm wondering if we could avoid copying this to /.docz to avoid this confusion altogether?

styleguide/.docz/gatsby-node.js:

try {
  gatsbyNodeCustom = require('../gatsby-node')

Looking at your current docs I'd be tempted to create a new markdown file, something like custom_config.md or advanced_usage.md that has more information about adding Gatsby node apis. I'd also probably link to that from the migration guide.

[rakannimer]

I'm wondering if we could avoid copying this to /.docz

That would be pretty hard if I'm not mistaken.

Adding something like custom_config.md or advanced_usage.md

That would probably be the best way to go, I think with a link from the migration guide

[stefcameron]

@rakannimer I think a two-pronged approach would be best:

1. Make sure the error is properly surfaced when it happens instead of letting it get swallowed-up and silently ignored (since docs, as beautiful and complete as we make them, are seldom fully read...).
2. Add an "advanced" section next to this one on the Docz Site https://www.docz.site/docs/powered-by-gatsby#gatsby-api-and-hooks since that's where the onCreateWebpackConfig hook is already being explained, and give an example.

[tripphamm]

I noticed that there's now a note in the docs about this, but I missed it on the first time through. It would have been really helpful if the error showed up in the logs when building. I think that an argument could be made that the error shouldn't just be logged, but that it should cause the build to fail. If someone adds a custom gatsby-* config and it's being ignored, that's probably something that they'll need to fix.

I'm happy to open up a PR to log that error (or to let it throw) rather than swallowing it if y'all are open to it.

[stefcameron]

@tripphamm

I think that an argument could be made that the error shouldn't just be logged, but that it should cause the build to fail.

That's my thinking too (suggestion 1 ☝️)!

[stale[bot]]

This issue has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs. Thank you for your contributions.