feat(gatsby-cli): add a clean command to wipe out local dirs (#9126)

* feat: add a clean command to the CLI * chore: minor tweak * chore: lint * refactor: move info to separate command; re-use in clean * chore: fix lint error * feat: add options including --no-install * chore: fix typo * docs: update readme with defaults * chore: bump to node 6; not node 4 requirement * chore: update readme * chore: update crlf * chore: mrege * chore: add clean command (drop info command) * fix: reduce reliance on certain gatsby version * chore: the env-info command is removed * chore: remove option from command handler * chore: remove info separate file * chore: remove node_modules and install from clean command * chore: add a plugin comment * docs: add a debugging cache doc * chore: tweak dir * chore: Update packages/gatsby-cli/src/create-cli.js Co-Authored-By: DSchau <DSchau@users.noreply.github.com>
gatsbyjs · Feb 19, 2019 · 5807936 · 5807936
1 parent 6b09fe4
commit 5807936
Show file tree

Hide file tree

Showing 7 changed files with 95 additions and 28 deletions.
diff --git a/docs/docs/debugging-cache-issues.md b/docs/docs/debugging-cache-issues.md
@@ -0,0 +1,36 @@
+---
+title: Debugging Cache Issues
+---
+
+There can be certain scenarios in which the Gatsby caching mechanism appears to fail, which leads to issues like:
+
+- Content not appearing when it should
+- Changes to plugin source code not appearing to be invoked appropriately
+
+and more! If you've found yourself writing a script like:
+
+```json:title=package.json
+{
+  "scripts": {
+    "clean": "rm -rf .cache"
+  }
+}
+```
+
+consider utilizing the `gatsby clean` command which will help to resolve caching issues for you.
+
+First - make sure the version of `gatsby` specified in your `package.json` dependencies is _at least_ `2.1.1`, and then make the following change to `package.json`:
+
+```json:title=package.json
+{
+  "scripts": {
+    "clean": "gatsby clean"
+  }
+}
+```
+
+Now when you issues arise that seem to be related to caching, you can use `npm run clean` to wipe out the cache and start from a fresh slate.
+
+_Note: If you find yourself using this command regularly, consider helping us out and [responding to our Github Issue][github-issue] with clear reproduction steps._
+
+[github-issue]: https://github.com/gatsbyjs/gatsby/issues/11747
diff --git a/packages/gatsby-cli/README.md b/packages/gatsby-cli/README.md
@@ -2,7 +2,8 @@
 
 The Gatsby command line interface (CLI). It is used to perform common functionality, such as creating a Gatsby application based on a starter, spinning up a hot-reloading local development server, and more!
 
-## Note on globally installed executables
+Let's you create new Gatsby apps using
+[Gatsby starters](https://www.gatsbyjs.org/docs/gatsby-starters/).
 
 The Gatsby CLI (`gatsby-cli`) is packaged as an executable that can be used globally--in fact, this was previously how we recommended using the CLI.
 
@@ -37,38 +38,36 @@ for more.
 
 ### `develop`
 
-At the root of a Gatsby site run `gatsby develop` to start the Gatsby
+At the root of a Gatsby app run `gatsby develop` to start the Gatsby
 development server.
 
 #### Options
 
-|     Option      | Description                                     |
-| :-------------: | ----------------------------------------------- |
-| `-H`, `--host`  | Set host. Defaults to localhost                 |
-| `-p`, `--port`  | Set port. Defaults to 8000                      |
-| `-o`, `--open`  | Open the site in your (default) browser for you |
-| `-S`, `--https` | Use HTTPS                                       |
+|     Option      | Description                                     |   Default   |
+| :-------------: | ----------------------------------------------- | :---------: |
+| `-H`, `--host`  | Set host.                                       | `localhost` |
+| `-p`, `--port`  | Set port.                                       |   `8000`    |
+| `-o`, `--open`  | Open the site in your (default) browser for you |             |
+| `-S`, `--https` | Use HTTPS                                       |             |
 
 Follow the [Local HTTPS guide](https://www.gatsbyjs.org/docs/local-https/)
 to find out how you can set up an HTTPS development server using Gatsby.
 
 ### `build`
 
-At the root of a Gatsby site use `gatsby build` to do a production build of a
-site.
+At the root of a Gatsby app run `gatsby build` to do a production build of a site.
 
 #### Options
 
-|            Option            | Description                                                                                                 |
-| :--------------------------: | ----------------------------------------------------------------------------------------------------------- |
-|       `--prefix-paths`       | Build site with link paths prefixed (set pathPrefix in your config)                                         |
-|        `--no-uglify`         | Build site without uglifying JS bundles (for debugging)                                                     |
-| `--open-tracing-config-file` | Tracer configuration file (open tracing compatible). See https://www.gatsbyjs.org/docs/performance-tracing/ |
+|            Option            | Description                                                                                                 | Default |
+| :--------------------------: | ----------------------------------------------------------------------------------------------------------- | :-----: |
+|       `--prefix-paths`       | Build site with link paths prefixed (set pathPrefix in your config)                                         | `false` |
+|        `--no-uglify`         | Build site without uglifying JS bundles (for debugging)                                                     | `false` |
+| `--open-tracing-config-file` | Tracer configuration file (open tracing compatible). See https://www.gatsbyjs.org/docs/performance-tracing/ |         |
 
-### Serve
+### `serve`
 
-At the root of a Gatsby site use `gatsby serve` to serve the production build of
-the site for testing.
+At the root of a Gatsby app run `gatsby serve` to serve the production build of the site
 
 #### Options
 
@@ -79,17 +78,26 @@ the site for testing.
 |  `-o`, `--open`  | Open the site in your (default) browser for you                                          |
 | `--prefix-paths` | Serve site with link paths prefixed (if built with pathPrefix in your gatsby-config.js). |
 
-### Info
+### `clean`
+
+At the root of a Gatsby app run `gatsby clean` to wipe out the cache (`.cache` folder) and `public` directories. This is useful **as a last resort** when your local project seems to have issues or content does not seem to be refreshing. Issues this may fix commonly include:
+
+- Stale data, e.g. this file/resource/etc. isn't appearing
+- GraphQL error, e.g. this GraphQL resource _should_ be present but is not
+- Dependency issues, e.g. invalid version, cryptic errors in console, etc.
+- Plugin issues, e.g. developing a local plugin and changes don't seem to be taking effect
+
+### `info`
 
 At the root of a Gatsby site run `npx gatsby info` to get helpful environment information which will be required when reporting a bug.
 
 #### Options
 
-|       Option        | Description                                             |
-| :-----------------: | ------------------------------------------------------- |
-| `-C`, `--clipboard` | Automagically copy environment information to clipboard |
+|       Option        | Description                                             | Default |
+| :-----------------: | ------------------------------------------------------- | :-----: |
+| `-C`, `--clipboard` | Automagically copy environment information to clipboard | `false` |
 
-### Repl
+### `repl`
 
 Get a node repl with context of Gatsby environment
 

diff --git a/packages/gatsby-cli/package.json b/packages/gatsby-cli/package.json
@@ -54,6 +54,5 @@
   },
   "yargs": {
     "boolean-negation": false
-  },
-  "gitHead": "5bd5aebe066b9875354a81a4b9ed98722731c465"
+  }
 }
diff --git a/packages/gatsby-cli/src/create-cli.js b/packages/gatsby-cli/src/create-cli.js
@@ -91,7 +91,7 @@ function buildLocalCommands(cli, isLocalSite) {
       report.verbose(`set gatsby_executing_command: "${command}"`)
 
       let localCmd = resolveLocalCommand(command)
-      let args = { ...argv, ...siteInfo, useYarn }
+      let args = { ...argv, ...siteInfo, report, useYarn }
 
       report.verbose(`running command: ${command}`)
       return handler ? handler(args, localCmd) : localCmd(args)
@@ -247,6 +247,12 @@ function buildLocalCommands(cli, isLocalSite) {
     },
   })
 
+  cli.command({
+    command: `clean`,
+    desc: `Wipe the local gatsby environment including built assets and cache`,
+    handler: getCommandHandler(`clean`),
+  })
+
   cli.command({
     command: `repl`,
     desc: `Get a node repl with context of Gatsby environment, see (add docs link here)`,

diff --git a/packages/gatsby-cli/src/index.js b/packages/gatsby-cli/src/index.js
@@ -17,9 +17,9 @@ const updateNotifier = require(`update-notifier`)
 // Check if update is available
 updateNotifier({ pkg }).notify()
 
-if (verDigit < 4) {
+if (verDigit < 6) {
   report.panic(
-    `Gatsby 1.0+ requires node.js v4 or higher (you have ${version}). \n` +
+    `Gatsby 1.0+ requires node.js v6 or higher (you have ${version}). \n` +
       `Upgrade node to the latest stable release.`
   )
 }

diff --git a/packages/gatsby/src/commands/clean.js b/packages/gatsby/src/commands/clean.js
@@ -0,0 +1,16 @@
+const fs = require(`fs-extra`)
+const path = require(`path`)
+
+module.exports = async function clean(args) {
+  const { directory, report } = args
+
+  const directories = [`.cache`, `public`]
+
+  report.info(`Deleting ${directories.join(`, `)}`)
+
+  await Promise.all(
+    directories.map(dir => fs.remove(path.join(directory, dir)))
+  )
+
+  report.info(`Successfully deleted directories`)
+}
diff --git a/www/src/data/sidebars/doc-links.yaml b/www/src/data/sidebars/doc-links.yaml
@@ -195,6 +195,8 @@
           link: /docs/debugging-replace-renderer-api/
         - title: Debugging the build process
           link: /docs/debugging-the-build-process/
+        - title: Debugging Cache Issues
+          link: /docs/debugging-cache-issues/
         - title: Trace Gatsby builds
           link: /docs/performance-tracing/
     - title: Adding website functionality