# scratch-gui
#### Scratch GUI is a set of React components that comprise the interface for creating and running Scratch 3.0 projects
[](https://travis-ci.com/LLK/scratch-gui)
[](https://greenkeeper.io/)
## Installation
This requires you to have Git and Node.js installed.
In your own node environment/application:
```bash
npm install https://github.com/LLK/scratch-gui.git
```
If you want to edit/play yourself:
```bash
git clone https://github.com/LLK/scratch-gui.git
cd scratch-gui
npm install
```
## Getting started
Running the project requires Node.js to be installed.
## Running
Open a Command Prompt or Terminal in the repository and run:
```bash
npm start
```
Then go to [http://localhost:8601/](http://localhost:8601/) - the playground outputs the default GUI component
## Developing alongside other Scratch repositories
### Getting another repo to point to this code
If you wish to develop `scratch-gui` alongside other scratch repositories that depend on it, you may wish
to have the other repositories use your local `scratch-gui` build instead of fetching the current production
version of the scratch-gui that is found by default using `npm install`.
Here's how to link your local `scratch-gui` code to another project's `node_modules/scratch-gui`.
#### Configuration
1. In your local `scratch-gui` repository's top level:
1. Make sure you have run `npm install`
2. Build the `dist` directory by running `BUILD_MODE=dist npm run build`
3. Establish a link to this repository by running `npm link`
2. From the top level of each repository (such as `scratch-www`) that depends on `scratch-gui`:
1. Make sure you have run `npm install`
2. Run `npm link scratch-gui`
3. Build or run the repositoriy
#### Using `npm run watch`
Instead of `BUILD_MODE=dist npm run build`, you can use `BUILD_MODE=dist npm run watch` instead. This will watch for changes to your `scratch-gui` code, and automatically rebuild when there are changes. Sometimes this has been unreliable; if you are having problems, try going back to `BUILD_MODE=dist npm run build` until you resolve them.
#### Oh no! It didn't work!
If you can't get linking to work right, try:
* Follow the recipe above step by step and don't change the order. It is especially important to run `npm install` _before_ `npm link`, because installing after the linking will reset the linking.
* Make sure the repositories are siblings on your machine's file tree, like `.../.../MY_SCRATCH_DEV_DIRECTORY/scratch-gui/` and `.../.../MY_SCRATCH_DEV_DIRECTORY/scratch-www/`.
* Consistent node.js version: If you have multiple Terminal tabs or windows open for the different Scratch repositories, make sure to use the same node version in all of them.
* If nothing else works, unlink the repositories by running `npm unlink` in both, and start over.
## Testing
### Documentation
You may want to review the documentation for [Jest](https://facebook.github.io/jest/docs/en/api.html) and [Enzyme](http://airbnb.io/enzyme/docs/api/) as you write your tests.
See [jest cli docs](https://facebook.github.io/jest/docs/en/cli.html#content) for more options.
### Running tests
*NOTE: If you're a windows user, please run these scripts in Windows `cmd.exe` instead of Git Bash/MINGW64.*
Before running any test, make sure you have run `npm install` from this (scratch-gui) repository's top level.
#### Main testing command
To run linter, unit tests, build, and integration tests, all at once:
```bash
npm test
```
#### Running unit tests
To run unit tests in isolation:
```bash
npm run test:unit
```
To run unit tests in watch mode (watches for code changes and continuously runs tests):
```bash
npm run test:unit -- --watch
```
You can run a single file of integration tests (in this example, the `button` tests):
```bash
$(npm bin)/jest --runInBand test/unit/components/button.test.jsx
```
#### Running integration tests
Integration tests use a headless browser to manipulate the actual html and javascript that the repo
produces. You will not see this activity (though you can hear it when sounds are played!).
Note that integration tests require you to first create a build that can be loaded in a browser:
```bash
npm run build
```
Then, you can run all integration tests:
```bash
npm run test:integration
```
Or, you can run a single file of integration tests (in this example, the `backpack` tests):
```bash
$(npm bin)/jest --runInBand test/integration/backpack.test.js
```
If you want to watch the browser as it runs the test, rather than running headless, use:
```bash
USE_HEADLESS=no $(npm bin)/jest --runInBand test/integration/backpack.test.js
```
## Publishing to GitHub Pages
You can publish the GUI to github.io so that others on the Internet can view it.
[Read the wiki for a step-by-step guide.](https://github.com/LLK/scratch-gui/wiki/Publishing-to-GitHub-Pages)
## Donate
We provide [Scratch](https://scratch.mit.edu) free of charge, and want to keep it that way! Please consider making a [donation](https://secure.donationpay.org/scratchfoundation/) to support our continued engineering, design, community, and resource development efforts. Donations of any size are appreciated. Thank you!