BetterScratch docs.

Getting started

The Chrome Web Store listing is coming soon. The website’s Add to Chrome buttons currently open the Store homepage. They don’t install the extension yet.

Install the current development version

1. Use a BetterScratch release ZIP, or build the extension from its source. Unzip a release into a permanent folder.
2. Open chrome://extensions in Chrome and enable Developer mode.
3. Choose Load unpacked and select the extracted folder containing manifest.json. If you built from source, select dist/ inside the extension project.
4. Refresh your Scratch tabs. Open BetterScratch’s toolbar popup and choose Open workbench to adjust your preferences.

Update an existing installation

Replace the extension files, reload its card at chrome://extensions, and refresh your Scratch tabs. Chrome may ask you to approve access to api.scratch.mit.edu for public-data features.

Appearance & homepage

BetterScratch refreshes the homepage, project pages, profiles, studios, messages, My Stuff, and Search/Explore. Its styling stays out of the Scratch editor.

• Themes: choose Light, Dark, or System. New installations default to Dark; saved preferences are preserved.
• Accents: choose Orange, Blue, or Teal.
• Density: choose Comfortable or Compact spacing.
• uWidget: select Welcome, Statistics, Activity, Continue, Custom, or Hidden. Choose a compact or expanded height.
• Sidebar: use the homepage navigation and dashboards for overview, project rankings, engagement, and your shelf. Collapse it when you need room. It hides on narrower screens.

Activity and Continue use optional local project-page visit history. They don’t represent project edits or successful saves.

Project tools

Remix tree

Open Remix tree beside the native Remix button to explore a project’s public remix relationships in a separate tab. Browse branches, follow parent/original projects, and open project thumbnails. Branches load as you explore, with pagination for larger sets.

Public-data access must be enabled. Private and deleted projects, missing API results, and complete historical trees may not be available.

Distraction-free viewing

Use the focus icon after Copy Link to hide surrounding notes and lower-page content. Select it again to exit. Scratch’s original player and fullscreen control remain available.

Save to shelf

Select the bookmark icon after Copy Link to save a project link locally. A check indicates it’s on your shelf. Select it again to remove the link. Find saved projects on the homepage and in the workbench.

The shelf holds up to 100 links. Adding beyond that limit drops the oldest saved link. Saving doesn’t favorite, share, change, or delete the original Scratch project.

Scratch News

BetterScratch announcements are shown alongside native Scratch News. Scratch’s own news items remain available.

Statistics & badges

Public insights

Profiles, the Statistics uWidget, and the homepage dashboard can show public project counts, follower information, views, loves, favorites, and remixes. Look for the displayed coverage and source timestamp.

Each snapshot reads up to 40 public projects. For larger accounts, engagement is a sample and the project count is a lower bound. Follower totals are exact only below the first-page limit; larger accounts show confirmed lower bounds. Unavailable data is marked unavailable.

Statistics cache for five minutes; profile and verification lookups cache for one hour. Newly observed followers are changes in a sampled list over seven days. The first check establishes a local baseline; these aren’t confirmed follow dates.

Community recognition

BetterScratch badges recognize Scratch Team accounts using Scratch’s API flag, accounts with a confirmed 1,001st follower, and selected community accounts viralgoose and -technify-. Exactly 1,000 followers doesn’t qualify.

Tooltips and accessible labels explain each qualifying reason. Badges are BetterScratch recognition—not official Scratch verification, proof of identity, or an endorsement. Biographies and self-described roles aren’t used as evidence.

Finding projects

Trending and popular projects

Open Trending projects in the extension’s homepage sidebar or workbench Statistics section. Choose Trending or Popular and keep Scratch’s order, or sort the first 40 returned projects by views, loves, or favorites. These are rankings within the loaded list, not global or country user leaderboards.

The website Stats tab lets you look up public profiles and browse the same feeds. A cached Vercel function reads the public API. It doesn’t store a database of accounts or produce global or country user rankings.

Search, Explore, and My Stuff have a title filter and live counts for projects already loaded on the page. Newly loaded results are included automatically.

The filter doesn’t search every project on Scratch or fetch your private inventory. Use Scratch’s original sorting and load-more controls to expand the results you’re browsing.

Preferences

Open the extension popup, then the workbench. Its live appearance preview lets you choose themes, accents, spacing, and widget options. Individual switches control the page upgrades, project tools, shelf, public data, badges, and history.

Export preferences as JSON to keep a backup, or import a BetterScratch version 1 preference file. Reset restores defaults. Saved theme preferences remain in effect until you change or reset them. Reduced motion is available, and the main power switch turns BetterScratch off.

Preferences use Chrome sync. Project links and visit history stay local to the device.

Privacy & permissions

• Storage: saves preferences, your local project shelf, visit history, banners, and caches.
• Public API access: reads from https://api.scratch.mit.edu/*. Requests omit account cookies and credentials.
• Scratch pages: the content script runs on https://scratch.mit.edu/*; editor, embed, and fullscreen routes are excluded from the redesign.

No analytics, third-party statistics service, account tokens, remote code, or project-file changes. Visit history is off by default. Public-data features and badges can be disabled independently.

The extension doesn’t read private project data. Different Scratch accounts sharing a browser profile can share its device-local shelf and visit history.

Troubleshooting

Changes aren’t showing

Reload BetterScratch at chrome://extensions, then refresh the Scratch page. Check that BetterScratch and the relevant feature switch are enabled. Unknown page layouts may receive badges only, without restyling.

Statistics or remix branches won’t load

Check that public-data access is enabled and Chrome has granted API host permission. Network failures and rate limits can make data unavailable. Use the tree’s retry control when offered, or try again later.

A badge is missing

A failed lookup doesn’t produce a badge. Cached results may lag account changes. Avatar-only links, editable inputs, plain comment prose, and inline mentions inside descriptions are intentionally excluded.

Something looks different in the editor

BetterScratch excludes editor routes and editor DOM. If another extension changes the editor, review that extension’s settings separately. Some native and third-party controls retain their own appearance.

Development

The extension and website are separate projects. The website uses HTML, CSS, browser JavaScript, and one Vercel API function; the extension uses React, TypeScript, and Vite.

Extension

Run these commands from the BetterScratch extension folder. Node.js 22.20 or later is recommended.

npm ci
npm run dev
npm run check
npm run package

npm run check runs lint, tests, TypeScript checks, production builds, and the bundled smoke check. npm run package creates an installable release ZIP. Development previews are at /settings.html and /popup.html; they don’t exercise Chrome extension APIs.

Website

Run this from the website folder, then open http://127.0.0.1:4173.

npm run dev

Edit pages and assets in dist/ and the stats function in api/stats.js. Use Node.js 22 or later. To host on Vercel, import the website’s GitHub repository. Use Other as the framework and dist as the output directory; vercel.json skips building and installation. For a larger repository, select website as the root directory.

Reference docs

Read the project’s technical documentation and remaining release checks. These are Markdown files included with this website.

BetterScratch is independent and is not affiliated with Scratch Foundation or MIT.