Debugging the Build Process

Because both the gatsby build and gatsby develop scripts are technically Node.js applications at their core, you can debug issues that occur within the execution of those scripts using commonly available standard approaches and tools for Node.js application development. Using Node.js debugging tools can be useful for situations where you need to identify a problem area in a gatsby-node.js file or another file that influences the build process or instantiation of the local development server.

For Gatsby developers familiar with debugging JavaScript in the browser, the console object is available with a console.log() method to print any values that need verification or introspection to the browser console during execution:

console.log(anObject)

Because the console object is also built into Node.js, you can add an invocation of console.log() to any executed code in your gatsby-node.js file or any other file—including Gatsby pages and components—to print the variable’s value into the terminal output, just like in the browser console. Consider the following example from gatsby-source-filesystem, in which we print the args variable to the Node.js console in the terminal:

// gatsby-node.js
const { createFilePath } = require("gatsby-source-filesystem")

exports.onCreateNode = args => {
  console.log(args)
  const { actions, node } = args
  if (node.internal.type === "MarkdownRemark") {
    const { createNodeField } = actions

    const value = createFilePath({ node, getNode })
    createNodeField({
      name: `slug`,
      node,
      value,
    })
  }
}

Observe the difference between console.log() statements that are executed at build time and can be seen in the terminal, like in the gatsby-node.js file, and those statements that are executed on the client side, whose results will display in the browser console instead of the terminal.

NOTE

If you use VS Code Debugger or Chrome DevTools for Node during the development process, these tools can help you perform similar debugging to that which you can do in a browser by connecting a debugger, even including the use of breakpoints. Consult the Gatsby documentation for in-depth guides to debugging Node.js with both VS Code Debugger and Chrome DevTools for Node.