@cloudcannon/suite/src/collections/_state/setup.md

A suite of gulp tools to manage static sites on CloudCannon

---
title: Setup
package: State
order_number: 2
subtasks:
  - name: build
    desc: Copies the JSON files from the reports directory to the build destination directory, along with an HTML template. This acts as a static site you can use to visualise dependencies.
    code: gulp state:build
  - name: clean
    desc: Deletes everything in the build destination directory.
    code: gulp state:clean
  - name: dependencies
    desc: Scans the compiled site for asset references, builds a dependency graph, and creates a JSON file report in the reports directory.
    code: gulp state:dependencies
  - name: dependents
    desc: Reads the report generated by `state:dependencies`, builds a reversed graph, and creates a JSON file in the reports directory. Make sure to run `gulp state:dependencies` first, if you are running this subtask manually.
    code: gulp state:dependents
  - name: find-unused
    desc: Scans the dependency tree and prints unused assets to the console. Make sure to run `gulp state:dependencies` first.
    code: gulp state:find-unused
---
To use this package, add `suite.state(gulp)` to your Gulpfile:

```js
/* gulpfile.js */
const gulp = require("gulp");
const suite = require("@cloudcannon/suite");

suite.state(gulp);
```

### Usage

Running `gulp state` will build a dependency graph and save it as JSON in your `reports/` directory. A local webserver will be started on port 9001, using the JSON file to create an interactive visualisation of the dependency graph.

> The state package needs to scan your compiled site - make sure you run `gulp dev:build` before `gulp state`.
{: .explainer}

```sh
$ gulp state
[16:39:37] Using gulpfile ./gulpfile.js
[16:39:37] Starting 'state'...
[16:39:37] Starting 'state:get-filename-list'...
[16:39:38] Finished 'state:get-filename-list' after 1.25 s
[16:39:38] Starting 'state:dependencies'...
[16:39:38] Finished 'state:dependencies' after 458 ms
[16:39:38] Starting 'state:dependents'...
[16:39:38] Finished 'state:dependents' after 2.43 ms
[16:39:38] Starting 'state:clean'...
[16:39:38] Finished 'state:clean' after 42 ms
[16:39:38] Starting 'state:build'...
[16:39:38] Finished 'state:build' after 14 ms
[16:39:38] Starting 'state:serve'...
[16:39:39] Finished 'state:serve' after 15 ms
[16:39:39] Finished 'state' after 1.78 s
```

In the visualiser, you can toggle between viewing the dependencies of an asset, and viewing the dependants of an asset.


Running `gulp state:find-unused` will print a list of unused assets to the console. This uses the dependency graph in `reports/`, so make sure to run `gulp state:dependencies` or `gulp state` first.

{% include package-subtasks.md %}