This is Scratch’s open source web client! This is the code for much of the Scratch website.
In particular, this codebase includes code for:
The scratch-www project has lots of aspects of its design that are particular to our backend systems. To use it for your own project, you would have to look at all the places it makes backend calls, and create your own backend systems to perform those functions.
The scratch-gui project, on the other hand, is designed to be able to be used by anyone, without needing to create backend systems, though it also can support backend systems for project and asset saving.
We welcome your contributions to this codebase! You may want to start by browsing the current list of open issues labeled "help wanted".
Contributing to scratch-www can be more difficult than contributing to scratch-gui. This is because scratch-gui can be run on its own, without needing any other services to be running, while scratch-www needs to communicate with several backend systems that the Scratch team runs (see "How this fits in with other Scratch repos" above). If you are new to contributing to Scratch's source code, we suggest you start by becoming familiar with scratch-gui and its list of open issues labeled "help wanted".
To contribute, please follow the standard steps for contributing to a project on GitHub.
See the LICENSE file in this repo.
Here are some resources to help you get acquainted with how we’re working on the Scratch codebase:
Significant core technologies this codebase uses include:
Our tests use:
Make sure you have installed:
It's important to make sure that all of the dependencies are up to date because the scratch-www code only works with specific versions of the dependencies. You can update the packages by using the command:
These warnings can be safely ignored:
npm WARN firstname.lastname@example.org requires a peer of react@^0.14.0 but none was installed. npm WARN email@example.com requires a peer of react@^0.14.0 but none was installed. npm WARN firstname.lastname@example.org requires a peer of redux@^2.0.0 || ^3.0.0 but none was installed. npm WARN email@example.com requires a peer of react@^0.14.7 but none was installed. npm WARN firstname.lastname@example.org requires a peer of react@^0.14.8 but none was installed.
These currently exist in static/js/lib .
You can either "build" the site a single time, by running:
npm run build
Or, you can run a server that rebuilds the files as you edit them, by running the commands:
npm run translate npm start
npm run translate builds the intl directory. The site will build fine without it,
but translatable text strings will not show up correctly until you have built intl.
npm start watches any update you make to files in either
./src and triggers a rebuild of the project. In development,
the build is stored in memory, and not served from the
Once you have built the local site, using either
npm run build or
the site hosted on your local machine can be accessed by a web browser by entering
localhost:8333 into your browser's address bar.
npm start, here are some important log messages to keep an eye out for:
webpack: bundle is now VALID.– The bundle has been loaded into memory and is now viewable in the browser. This will show up both once
npm starthas completed its setup, and also once updates you make to files have been re-compiled for viewing in the browser.
webpack: bundle is now INVALID.– If you see this, then it means you have made updates to files that are still being compiled for browser viewing. Pages will still be viewable, but they will not see any updates you made yet.
To stop the
npm start process which is making the site available to your web browser
(created above in "To Build"), use
^C (control-c) in the terminal.
npm start can be configured with the following environment variables, by setting them in
the beginning of the command, before
||Hostname for API requests|
||Hostname for asset requests|
||Hostname for backpack requests|
||Hostname for project requests|
||DSN for Sentry|
||Pass-through location for old site|
||Where to log Google Analytics data|
||Port for devserver (http://localhost:XXXX)|
NOTE: Because by default
API_HOST=https://api.scratch.mit.edu, please be aware that, by default, you will be seeing and interacting with real data on the Scratch website.
Most of our unit tests run using Jest, but older unit tests use the TAP framework.
To build the application and run all unit and localization tests, use the command:
To run a single unit test file from the command-line using Jest, use the command:
PATH/TO/FILENAME with the actual path to the file you wish to run.
Our integration tests assume that a larger environment is running than just scratch-www on its own; for instance, many require that a test user be able to log in to the site, which requires backend and database support.
By default, tests run against our Staging instance, but you can pass in a different location with the ROOT_URL environment variable (see below) if you want to run the tests against another location--for instance, your local build.
We are transitioning from using TAP to using Jest as our testing framework, so for the time being our tests run using both.
To run all integration tests from the command-line:
SMOKE_USERNAME=username SMOKE_PASSWORD=password ROOT_URL=https://scratch.mit.edu npm run test:integration
To run a single file from the command-line using Jest:
SMOKE_USERNAME=username SMOKE_PASSWORD=password ROOT_URL=https://scratch.mit.edu node_modules/.bin/jest ./test/integration/filename.test.js
To run a single file from the command-line using TAP:
SMOKE_USERNAME=username SMOKE_PASSWORD=password ROOT_URL=https://scratch.mit.edu node_modules/.bin/tap ./test/integration-legacy/smoke-testing/filename.js -R classic --no-coverage --timeout=3600
-R classicmakes tap use the old reporting style, which avoids an error with the "nyc" package
--no-coverageis because we do not use the coverage-tracking feature of tap
timeoutargument is for the length of the entire tap test-suite; if you are getting a timeout error, you may need to adjust this value (some of the Selenium tests take a while to run)
Integration tests can be run using Saucelabs, an online service that can test multiple browser/OS combinations remotely. (Currently, all tests are written for use for Chrome on Mac).
You will need a Saucelabs account in order to use it for testing. If you have one, you can find your Access Key:
To run tests using Saucelabs, run the command:
SMOKE_USERNAME=username SMOKE_PASSWORD=password SAUCE_USERNAME=saucelabsUsername SAUCE_ACCESS_KEY=saucelabsAccessKey ROOT_URL=https://scratch.mit.edu npm run test:integration:remote
NOTE: Currently Jest tests will not run with Saucelabs.
||Location you want to run the tests against|
||Username for Scratch user you're signing in with to test|
||Password for Scratch user you're signing in with to test|
||Tests with Sauce Labs or not. True if running test:smoke:sauce|
||Run browser in headless mode. Flaky at the moment|
||Username for your Sauce Labs account|
||Access Key for Sauce Labs found under User Settings|
Deploying to staging or production will upload code to S3 and configure Fastly.
npm install virtualenv ENV . ENV/bin/activate pip install -r requirements.txt npm run build && npm run deploy
||Fastly service ID for
||Fastly API key for
||Activate changes and purge all after configuring|
||AWS access key id for S3|
||AWS secret access key for S3|
||S3 bucket name to deploy into|
For development on Windows, you will probably need to use a program that provides you a Unix interface.
There are several options for doing this:
In addition, you will need to install Node; here are instructions for installing Node on WSL.
We're currently in the process of transitioning into this web client from Scratch's existing structure. As we transition, there are going to be some issues along the way that relate to how this client needs to interact with the existing infrastructure to work properly in production.
On top of migrating to using this as our web client, Scratch is also transitioning into using a new API backend, Scratch REST API (closed-source). As that is also currently in development and incomplete, we are set up to fall back to using existing Scratch endpoints if an API endpoint does not exist – which is where the
FALLBACK comes in.
Most of the issues we have currently revolve around the use of
FALLBACK. This variable is used to specify what URL to fall back onto should a request fail within the context of this web client, or when using the
API_HOST. If not specified in the process, it will not be used, and any request that is not made through the web client or the API will be unreachable.
FALLBACK=https://scratch.mit.edu allows the web client to retrieve data from the Scratch website in your development environment. However, because of security concerns, trying to send data to Scratch through your development environment won't work. This means the following things will be broken for the time being:
Additionally, if you set
FALLBACK=https://scratch.mit.edu, be aware that clicking on links to parts of the website not yet migrated over (currently such as
My Stuff, etc.) will take you to the Scratch website itself.