Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

[docs] describe console logging of the build process #18816

Merged
merged 3 commits into from
Oct 29, 2019
Merged
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
37 changes: 30 additions & 7 deletions docs/docs/debugging-the-build-process.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,13 +4,9 @@ title: Debugging the Build Process

Gatsby's `build` and `develop` steps run as a Node.js application which you can debug using standard tools for Node.js applications.

In this guide you will learn how to debug some code using:
In this guide you will learn how to debug some code using various techniques.

- [VS Code debugger (Auto-Config)](#vs-code-debugger-auto-config)
- [VS Code debugger (Manual-Config)](#vs-code-debugger-manual-config)
- [Chrome DevTools for Node](#chrome-devtools-for-node)

As an example, use the following code snippet in a `gatsby-node.js` file:
As an example consider the following code snippet in a `gatsby-node.js` file:

```js:title=gatsby-node.js
const { createFilePath } = require("gatsby-source-filesystem")
Expand Down Expand Up @@ -40,6 +36,33 @@ TypeError: Cannot read property 'internal' of undefined
D:/dev/blog-v2/gatsby-node.js:6:12
```

## Debugging with Node.js' built-in console

One of the fastest ways to gain insight into Gatsby's build process is using the `console` functionality [built into Node.js](https://nodejs.org/en/knowledge/getting-started/the-console-module/). This works similar to how you might be used to in the browser.

Adding a `console.log` statement in the sample from above will print the variable into your terminal. There you might notice that `args` contains a lower-cased node variable.

```diff:title=gatsby-node.js
const { createFilePath } = require("gatsby-source-filesystem")

exports.onCreateNode = args => {
+ console.log(args)
muescha marked this conversation as resolved.
Show resolved Hide resolved
const { actions, Node } = args
if (Node.internal.type === "MarkdownRemark") {
const { createNodeField } = actions

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

To read more about Gatsby's build process, check out the differences between [build and runtime](/docs/overview-of-the-gatsby-build-process#build-time-vs-runtime). Generally spoken, Node.js is responsible for building Gatsby pages and therefore its' built-in objects like `console` can be used at build time. At client-side [runtime](/docs/glossary#runtime), the browser's `console.log` API will add messages to the developer tools console.

## VS Code Debugger (Auto-Config)

If you use VS Code and its integrated terminal, you can configure it to automatically create the debug config for you.
Expand Down Expand Up @@ -140,7 +163,7 @@ Now you can resume code execution by clicking the "resume" icon in the DevTools

To inspect variables you can hover your mouse over them or go to the `Scope` section in the right-hand pane (either collapse the "Call Stack" section or scroll through it to the bottom).

In the example `Node` is `undefined` and to figure out why, let's go backwards. `Node` is extracted from `args` so examine that by hovering `args`:
In the example `Node` is `undefined` and to figure out why, hover over `args` where `Node` should be destructured from.

![Examine variable](./images/chrome-devtools-examine-var.png)

Expand Down