{"id":13402437,"url":"https://github.com/scratchfoundation/scratch-gui","last_synced_at":"2025-05-13T16:06:03.809Z","repository":{"id":37270600,"uuid":"68243930","full_name":"scratchfoundation/scratch-gui","owner":"scratchfoundation","description":"Graphical User Interface for creating and running Scratch 3.0 projects.","archived":false,"fork":false,"pushed_at":"2025-04-29T06:13:00.000Z","size":2459584,"stargazers_count":4613,"open_issues_count":1110,"forks_count":3776,"subscribers_count":209,"default_branch":"develop","last_synced_at":"2025-04-29T16:52:58.548Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"https://scratchfoundation.github.io/scratch-gui/develop/","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"agpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/scratchfoundation.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":".github/CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2016-09-14T21:14:10.000Z","updated_at":"2025-04-29T14:15:53.000Z","dependencies_parsed_at":"2023-09-27T11:52:02.187Z","dependency_job_id":"35b47d10-69c3-47bb-8a84-81b40455a5f6","html_url":"https://github.com/scratchfoundation/scratch-gui","commit_stats":{"total_commits":7629,"total_committers":108,"mean_commits":70.63888888888889,"dds":0.8719360335561672,"last_synced_commit":"c0c2f3e65ffd66626432e8c727048d2fd519b55d"},"previous_names":["llk/scratch-gui"],"tags_count":2821,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/scratchfoundation%2Fscratch-gui","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/scratchfoundation%2Fscratch-gui/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/scratchfoundation%2Fscratch-gui/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/scratchfoundation%2Fscratch-gui/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/scratchfoundation","download_url":"https://codeload.github.com/scratchfoundation/scratch-gui/tar.gz/refs/heads/develop","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":252590514,"owners_count":21772934,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-07-30T19:01:16.011Z","updated_at":"2025-05-05T22:48:01.314Z","avatar_url":"https://github.com/scratchfoundation.png","language":"JavaScript","funding_links":[],"categories":["JavaScript"],"sub_categories":[],"readme":"# scratch-gui\n\nScratch GUI is a set of React components that comprise the interface for creating and running Scratch 3.0 projects\n\nTo open the current build in your browser on Github Pages:\n\nhttps://scratchfoundation.github.io/scratch-gui/\n\n## Installation\n\nThis requires you to have Git and Node.js installed.\n\nIn your own node environment/application:\n\n```bash\nnpm install https://github.com/scratchfoundation/scratch-gui.git\n```\n\nIf you want to edit/play yourself:\n\n```bash\ngit clone https://github.com/scratchfoundation/scratch-gui.git\ncd scratch-gui\nnpm install\n```\n\n**You may want to add `--depth=1` to the `git clone` command because there are some [large files in the git repository\nhistory](https://github.com/scratchfoundation/scratch-gui/issues/5140).**\n\n## Getting started\n\nRunning the project requires Node.js to be installed.\n\n## Running\n\nOpen a Command Prompt or Terminal in the repository and run:\n\n```bash\nnpm start\n```\n\nThen go to [http://localhost:8601/](http://localhost:8601/) - the playground outputs the default GUI component\n\n## Developing alongside other Scratch repositories\n\n### Getting another repo to point to this code\n\n\nIf you wish to develop `scratch-gui` alongside other scratch repositories that depend on it, you may wish\nto have the other repositories use your local `scratch-gui` build instead of fetching the current production\nversion of the scratch-gui that is found by default using `npm install`.\n\nHere's how to link your local `scratch-gui` code to another project's `node_modules/scratch-gui`.\n\n#### Configuration\n\n1. In your local `scratch-gui` repository's top level:\n    1. Make sure you have run `npm install`\n    2. Build the `dist` directory by running `BUILD_MODE=dist npm run build`\n    3. Establish a link to this repository by running `npm link`\n\n2. From the top level of each repository (such as `scratch-www`) that depends on `scratch-gui`:\n    1. Make sure you have run `npm install`\n    2. Run `npm link scratch-gui`\n    3. Build or run the repository\n\n#### Using `npm run watch`\n\nInstead of `BUILD_MODE=dist npm run build`, you can use `BUILD_MODE=dist npm run watch` instead. This will watch for\nchanges to your `scratch-gui` code, and automatically rebuild when there are changes. Sometimes this has been\nunreliable; if you are having problems, try going back to `BUILD_MODE=dist npm run build` until you resolve them.\n\n#### Oh no! It didn't work!\n\nIf you can't get linking to work right, try:\n\n* Follow the recipe above step by step and don't change the order. It is especially important to run `npm install`\n  _before_ `npm link` as installing after the linking will reset the linking.\n* Make sure the repositories are siblings on your machine's file tree, like\n  `.../.../MY_SCRATCH_DEV_DIRECTORY/scratch-gui/` and `.../.../MY_SCRATCH_DEV_DIRECTORY/scratch-www/`.\n* Consistent node.js version: If you have multiple Terminal tabs or windows open for the different Scratch\n  repositories, make sure to use the same node version in all of them.\n* If nothing else works, unlink the repositories by running `npm unlink` in both, and start over.\n\n## Testing\n\n### Documentation\n\nYou may want to review the documentation for [Jest](https://facebook.github.io/jest/docs/en/api.html) and\n[Enzyme](http://airbnb.io/enzyme/docs/api/) as you write your tests.\n\nSee [jest cli docs](https://facebook.github.io/jest/docs/en/cli.html#content) for more options.\n\n### Running tests\n\n*NOTE: If you're a Windows user, please run these scripts in Windows `cmd.exe`  instead of Git Bash/MINGW64.*\n\nBefore running any tests, make sure you have run `npm install` from this (scratch-gui) repository's top level.\n\n#### Main testing command\n\nTo run linter, unit tests, build, and integration tests, all at once:\n\n```bash\nnpm test\n```\n\n#### Running unit tests\n\nTo run unit tests in isolation:\n\n```bash\nnpm run test:unit\n```\n\nTo run unit tests in watch mode (watches for code changes and continuously runs tests):\n\n```bash\nnpm run test:unit -- --watch\n```\n\nYou can run a single file of integration tests (in this example, the `button` tests):\n\n```bash\n$(npm bin)/jest --runInBand test/unit/components/button.test.jsx\n```\n\n#### Running integration tests\n\nIntegration tests use a headless browser to manipulate the actual HTML and javascript that the repo\nproduces. You will not see this activity (though you can hear it when sounds are played!).\n\nTo run the integration tests, you'll first need to install Chrome, Chromium, or a variant, along with Chromedriver.\n\nNote that integration tests require you to first create a build that can be loaded in a browser:\n\n```bash\nnpm run build\n```\n\nThen, you can run all integration tests:\n\n```bash\nnpm run test:integration\n```\n\nOr, you can run a single file of integration tests (in this example, the `backpack` tests):\n\n```bash\n$(npm bin)/jest --runInBand test/integration/backpack.test.js\n```\n\nIf you want to watch the browser as it runs the test, rather than running headless, use:\n\n```bash\nUSE_HEADLESS=no $(npm bin)/jest --runInBand test/integration/backpack.test.js\n```\n\n## Troubleshooting\n\n### Ignoring optional dependencies\n\nWhen running `npm install`, you can get warnings about optional dependencies:\n\n```text\nnpm WARN optional Skipping failed optional dependency /chokidar/fsevents:\nnpm WARN notsup Not compatible with your operating system or architecture: fsevents@1.2.7\n```\n\nYou can suppress them by adding the `no-optional` switch:\n\n```bash\nnpm install --no-optional\n```\n\nFurther reading: [Stack Overflow](https://stackoverflow.com/questions/36725181/not-compatible-with-your-operating-system-or-architecture-fsevents1-0-11)\n\n### Resolving dependencies\n\nWhen installing for the first time, you can get warnings that need to be resolved:\n\n```text\nnpm WARN eslint-config-scratch@5.0.0 requires a peer of babel-eslint@^8.0.1 but none was installed.\nnpm WARN eslint-config-scratch@5.0.0 requires a peer of eslint@^4.0 but none was installed.\nnpm WARN scratch-paint@0.2.0-prerelease.20190318170811 requires a peer of react-intl-redux@^0.7 but none was installed.\nnpm WARN scratch-paint@0.2.0-prerelease.20190318170811 requires a peer of react-responsive@^4 but none was installed.\n```\n\nYou can check which versions are available:\n\n```bash\nnpm view react-intl-redux@0.* version\n```\n\nYou will need to install the required version:\n\n```bash\nnpm install  --no-optional --save-dev react-intl-redux@^0.7\n```\n\nThe dependency itself might have more missing dependencies, which will show up like this:\n\n```bash\nuser@machine:~/sources/scratch/scratch-gui (491-translatable-library-objects)$ npm install  --no-optional --save-dev react-intl-redux@^0.7\nscratch-gui@0.1.0 /media/cuideigin/Linux/sources/scratch/scratch-gui\n├── react-intl-redux@0.7.0\n└── UNMET PEER DEPENDENCY react-responsive@5.0.0\n```\n\nYou will need to install those as well:\n\n```bash\nnpm install  --no-optional --save-dev react-responsive@^5.0.0\n```\n\nFurther reading: [Stack Overflow](https://stackoverflow.com/questions/46602286/npm-requires-a-peer-of-but-all-peers-are-in-package-json-and-node-modules)\n\n## Troubleshooting\n\nIf you run into npm install errors, try these steps:\n\n1. run `npm cache clean --force`\n2. Delete the node_modules directory\n3. Delete package-lock.json\n4. run `npm install` again\n\n## Publishing to GitHub Pages\n\nYou can publish the GUI to github.io so that others on the Internet can view it.\n[Read the wiki for a step-by-step guide.](https://github.com/scratchfoundation/scratch-gui/wiki/Publishing-to-GitHub-Pages)\n\n## Understanding the project state machine\n\nSince so much code throughout scratch-gui depends on the state of the project, which goes through many different\nphases of loading, displaying and saving, we created a \"finite state machine\" to make it clear which state it is in at\nany moment. This is contained in the file src/reducers/project-state.js .\n\nIt can be hard to understand the code in src/reducers/project-state.js . There are several types of data and functions\nused, which relate to each other:\n\n### Loading states\n\nThese include state constant strings like:\n\n* `NOT_LOADED` (the default state),\n* `ERROR`,\n* `FETCHING_WITH_ID`,\n* `LOADING_VM_WITH_ID`,\n* `REMIXING`,\n* `SHOWING_WITH_ID`,\n* `SHOWING_WITHOUT_ID`,\n* etc.\n\n### Transitions\n\nThese are names for the action which causes a state change. Some examples are:\n\n* `START_FETCHING_NEW`,\n* `DONE_FETCHING_WITH_ID`,\n* `DONE_LOADING_VM_WITH_ID`,\n* `SET_PROJECT_ID`,\n* `START_AUTO_UPDATING`,\n\n### How transitions relate to loading states\n\nLike this diagram of the project state machine shows, various transition actions can move us from one loading state to\nanother:\n\n![Project state diagram](docs/project_state_diagram.svg)\n\n_Note: for clarity, the diagram above excludes states and transitions relating to error handling._\n\n#### Example\n\nHere's an example of how states transition.\n\nSuppose a user clicks on a project, and the page starts to load with URL `https://scratch.mit.edu/projects/123456`.\n\nHere's what will happen in the project state machine:\n\n![Project state example](docs/project_state_example.png)\n\n1. When the app first mounts, the project state is `NOT_LOADED`.\n2. The `SET_PROJECT_ID` redux action is dispatched (from src/lib/project-fetcher-hoc.jsx), with `projectId` set to\n   `123456`. This transitions the state from `NOT_LOADED` to `FETCHING_WITH_ID`.\n3. The `FETCHING_WITH_ID` state. In src/lib/project-fetcher-hoc.jsx, the `projectId` value `123456` is used to request\n   the data for that project from the server.\n4. When the server responds with the data, src/lib/project-fetcher-hoc.jsx dispatches the `DONE_FETCHING_WITH_ID`\n   action, with `projectData` set. This transitions the state from `FETCHING_WITH_ID` to `LOADING_VM_WITH_ID`.\n5. The `LOADING_VM_WITH_ID` state. In src/lib/vm-manager-hoc.jsx, we load the `projectData` into Scratch's virtual\n   machine (\"the vm\").\n6. When loading is done, src/lib/vm-manager-hoc.jsx dispatches the `DONE_LOADING_VM_WITH_ID` action. This transitions\n   the state from `LOADING_VM_WITH_ID` to `SHOWING_WITH_ID`.\n7. The `SHOWING_WITH_ID` state. Now the project appears normally and is playable and editable.\n\n## Donate\n\nWe provide [Scratch](https://scratch.mit.edu) free of charge, and want to keep it that way! Please consider making a\n[donation](https://www.scratchfoundation.org/donate) to support our continued engineering, design, community, and\nresource development efforts. Donations of any size are appreciated. Thank you!\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fscratchfoundation%2Fscratch-gui","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fscratchfoundation%2Fscratch-gui","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fscratchfoundation%2Fscratch-gui/lists"}