From 580793634d53fe2acf1b6b372c15fe27a965d9b0 Mon Sep 17 00:00:00 2001 From: Dustin Schau Date: Tue, 19 Feb 2019 12:53:44 -0600 Subject: [PATCH] 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 --- docs/docs/debugging-cache-issues.md | 36 ++++++++++++++++++ packages/gatsby-cli/README.md | 54 +++++++++++++++------------ packages/gatsby-cli/package.json | 3 +- packages/gatsby-cli/src/create-cli.js | 8 +++- packages/gatsby-cli/src/index.js | 4 +- packages/gatsby/src/commands/clean.js | 16 ++++++++ www/src/data/sidebars/doc-links.yaml | 2 + 7 files changed, 95 insertions(+), 28 deletions(-) create mode 100644 docs/docs/debugging-cache-issues.md create mode 100644 packages/gatsby/src/commands/clean.js diff --git a/docs/docs/debugging-cache-issues.md b/docs/docs/debugging-cache-issues.md new file mode 100644 index 0000000000000..6f493b6cf99c3 --- /dev/null +++ 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 index 9422d4803ec31..0120c19a84853 100644 --- 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 index ae310fbefdb6d..05d54829a1ee4 100644 --- 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 index 2e23dccccc2dd..9c87fcf0c4c7a 100644 --- 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 index ce8ba8012092d..91c709aaa6364 100755 --- 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 new file mode 100644 index 0000000000000..b9e0752c21694 --- /dev/null +++ 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 index 103ca8ba5c3b2..ca90326ab5ebb 100644 --- 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