Building your own extension

Step 1: Design blocks in the editor

It is easiest to tinker and design your blocks from the editor itself. Use the custom blocks feature for this purpose.

Step 2: GitHub setup

You will need to get a GitHub account and create a GitHub repository. At this time, other repository hosting solutions (GitLab, Bitbucket, etc.) are not supported.

Let’s say you want to create an extension called banana for target TARGET.

• create the repository in GitHub
• clone the repository into pxt-banana
• go to the folder for this repo

Step 3: Unpack your code

Install the PXT command line and use it to unpack the sources from a compiled file generated by clicking on Download.

• setup the target

  pxt target TARGET

• unpack the file

  pxt extract  HEXFILE

• build the project

  pxt build

• edit pxt.json and README.md with the right descriptions

• commit files to git: git add ., and commit them: git commit -m "Initial"

Make sure you keep the line for PXT/TARGET (where TARGET is the target id) in README.md. Otherwise, the extension will not show up in search.

Step 4: Developing extension

Now, you’re ready to develop your extension. You can do it with VSCode or from the web editor served from pxt serve.

• put the contents of your extension in main.ts
• add a sample program using the extension in test.ts
• use pxt to build and deploy the extension with tests; use the web editor to test in the simulator

You will develop your extension in pxt-banana, and then test this work by creating a second project (called, perhaps, “Just Look At It”) which includes a reference to pxt-banana.

For a quick introduction on creating extensions, try the simple extension tutorial.

Step 5: Testing

In order to test your extension, you need to create a new project, and manually add a reference back to the extensin you’ve been developing.

• Open the local editor and create a new project. For example, you might call it Just Look At It.
• Open the project settings by clicking the gear (Gear -> Project Settings)
• Click on Edit Settings As Text
• Add an entry under dependencies that points to your extension folder:

{
    "name": "banana test",
    "dependencies": {
        ...
        "banana": "file:../pxt-banana"
    },
    ...
}

• Reload the editor and the new blocks you developed in pxt-banana will be loaded into the project “Just Look At It.”

Step 4: Publishing your extension

When you’re happy with the first version of your extension, commit the changes and bump the version and push to github:

git commit -a -m "Amazing flying bananas"
pxt bump

The pxt bump will make sure there are no uncommited changes, bump the version number, create a git tag, and push everything to github.

In the editor, paste the full URL to your repo after selecting Settings -> Extensions. Your extension should show up.

Step 5: Approval

In order to be searchable by users, extensions need to be approved. GitHub organizations or individual repos can be approved.

See approval for more details.

Read more on defining blocks to learn how to surface your APIs into blocks and JavaScript.

Icon

The editor will automatically use any icon.png file when displaying the extension in the editor. This feature only works for approved extensions.

The icon should be sized with a 16:9 ratio and of at least 184 pixels wide.