This repository is your one-stop-shop for developing scratch extensions for PRG curricula.
It forks a few of the official Scratch codebases, which the Personal Robotics Group (PRG) manages and extends to meet its needs. These exist as git submodules located inside of the scratch-packages/ folder.
- scratch-packages/scratch-gui/
- prg-raise-playground-scratch-gui forks the scratch-gui package. See our changes.
- scratch-packages/scratch-vm/
- prg-raise-playground-scratch-vm forks the scratch-vm package. See our changes.
Looking for the old documentation (<= Sept. 2022)? Head here.
This section contains concise explanations on how to accomplish something (often just a couple of terminal commands to run). If you need more info please check out one of the lower sections.
Assuming you have...
- Git installed (if not, jump to: Git)
- (Windows only) WSL setup (if not, jump to: Windows Setup)
- Node is installed (if not, jump to: Node)
- PNPM is installed: PNPM
- VS Code installed with Typescript Extension added (if not, jump to: Vs Code)
Run the following from the command line:
(NOTE: If using gitpod, this all will be done for you on startup)
git clone --recurse-submodules [email protected]:mitmedialab/prg-extension-boilerplate.git
# Clone the repository (including git submodules: scratch-gui and scratch-vm) onto your computer. This could take a while (~5m), grab a beverage!
cd prg-extension-boilerplate/
# Change directory (cd) to the repository
git checkout dev
pnpm install
# This will symlink the packages together to allow for seamless local development, and installs dependencies for each package.
# This should only need to be ran once (unless you checkout a branch that adds new package dependencies).
# Takes ~1.5 minutes the first time it runs, and is much quicker (a few seconds) for later installs / updates
pnpm dev -i examples
# This starts up a development server, serving the two "example" extensions.
# It takes about ~20s to initially startup and serve everything.
# Open http://localhost:8601/ in your browser (keep refreshing if nothing's coming up)To make a new extension, run the following commands:
cd prg-extension-boilerplate/ # If not already there
# Change directory (cd) to prg-extension-boilerplate/
git checkout dev
git pull # Update branch with any remote changes
git checkout -b <my branch> # Checkout your 'feature' branch, e.g. git checkout -b new_rad_extension
pnpm new:extension <folder to contain extension>
# For example: pnpm new:extension my_awesome_extension
# If succesful, the output of this command will tell you where to find your new extension file.
# It will be an index.ts file, and its documentation should help you get startedIf you're a pro extension-maker, use the following command to make a new extension that contains no documentation and/or filler text.
pnpm new:extension <folder to contain extension> barebones
# Note the 'barenones' at the endAfter you've made your extension, run the following commands to serve it locally and view it in your browser.
cd prg-extension-boilerplate/ # If not already there
# Change directory (cd) to prg-extension-boilerplate/
pnpm dev -i <folder name of extension(s)>
# For example: pnpm dev -i my_awesome_extension
# Start a development server to view your extension and reload it as you make changes
# This command will take ~20s to startup and serve everything to http://localhost:8601/
# Note: you can use the '-i' shorthand instead of writing out '--include'
pnpm dev -i <folder name of extension(s)>
# Alternatively, serve all the currently implemented extensions
pnpm dev -i all
# NOTE: This will be much more intensive on your computerThen, after navigating to http://localhost:8601/, follow the 'Adding Extensions' guidance in the official extension documentation to add your extension to the workspace.
As long as the development server is running (meaning the pnpm dev command is still executing), every change you make to the extension file(s) will trigger the page to refresh and your changes will be reflected automagically 🪄.
To learn how to manage git-tracking and deploying your extension, please head to the CICD.md (continuous integration & continuous delivery / deployment) documentation.
Once you've created your extension and opened the corresponding index.ts file in VS Code, you might be wondering where to start.
First, read through the documentation of the index.ts file (written inside of code comments).
Also, try hovering over fields to view their documentation (typically a summary, examples, and a longer desrciption).
Still stuck? Check out our From 0 to Extension guide and/or contact more experienced extension developers, like Parker or Maya
... Coming soon ...
Currently, depending on what's new to you, here are some recommendations:
- New to Javascript and Typescript? Follow this javascript tutorial and then check out the Typescript handbook
- Know javascript but new to Typescript? Check out the Typescript handbook
- Know javascript/typescript but never made an extension before? Nice! The documentation of the template
index.tsshould be enough to get you started (and if not, please give us that feedback) - New to the extension framework (but had developed extensions in the past)? The Porting an extension to Typescript guide is likely for you!
Probably will have:
- Full step-by-step guide on:
- What is an extension?
- How do you make one using the typescript framework
- Video tutorial
- FAQ?
An exciting feature of PRG's work to expand the Scratch Extension workflow is that you can easily create custom UIs for your extensions.
We require you to implement this interface in the Svelte front-end framework. Hop down to the Svelte dependency to configure your development environment, understand why we chose svelte, and start learning the ropes.
Then, head over to the Extension specific section on adding / developing UI.
Not interested in setting up your local environemnt?
Please setup and perform all commands through Node on Windows Subsystem for Linux.
Please install git, which helps us with source control -- basically, how we preserve and share (changes to) the code.
Like many web development projects, this project requires node.
If you don't have Node installed, check out this page on how to download it.
In October 2022, node 18 LTS will be released, making it slightly harder to get node 16 LTS. Before then, we either need to upgrade webpack to be able to use node 18, or revise the above instructions to help users locate node 16.
PNPM (Performant Node Package Manager) is a package manager that enhances dependency management for JavaScript projects by storing package files globally and using symbolic links in the node_modules folder. This approach reduces disk space usage and maintains the module dependency tree, making it a faster and more space-efficient alternative to traditional package managers like NPM, Node's default package manager.
If you've already installed Node, you'll likely have NPM automatically installed. Run the command below to install PNPM using NPM.
npm install -g pnpmIf you don't have NPM, you can follow these instructions to install PNPM.
We encourage you to use VS Code since it has great Typescript support. Also, it's easier to offer tips and tricks if most of us use the same text editor.
Here's how to install VS Code.
Of course, if you prefer a different editor, go ahead and use it (but do so at your own 'risk').
We recommend adding the following VS Code extensions (which you can do like so):
- Typescript
- Svelte (Only if you are developing custom UI for your extensions)
If you will be implementing custom UI windows for your extension, you'll need to work with Svelte.
As noted above, you should install the Svelte Vs Code Extension.
If you're wondering why we chose Svelte, it's because:
- It offers a great typescript-developer expererience
- It allows you to use a single file to define the css/html/javascript (or in our case, typescript) that makes up an interface
- Just works more often than other frameworks
- It is (debatebly) more beginner friendly than other frameworks, since there aren't as many advanced concepts to understand
- But the tradeoff is you have to learn some svelte-specific concepts that you likely haven't seen anywhere else, like: Reactive Assignments, Reactive Statements, Bindings, etc. But these are all innovative concepts intended to make your life easier.
The best way to learn how to write Svelte is through following their interactive tutorial (which takes ~2hrs total, but spending just 30 minutes on it would get you a long way).
If you see the following:
> [email protected] build /Users/brian/code/aied/test/test2/packages/scratch-render
> webpack --progress --colors
sh: webpack: command not foundThis may mean you have a half-installed node_modules version of webpack. Try starting fresh!
Note the LICENSEs and especially TRADEMARKs for each Scratch component project carefully — e.g., you may not use the Scratch name, logo, cat, etc. in derivative projects without permission.