Building your own package

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 a package 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 package will not show up in search.

Step 4: Developing package

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

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

You will develop your package 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.

If the local editor fails to open, copy the URL printed in the console and open it in your favorite browser.

The local server requires a security token embedded in the URL to serve pages.

For a quick introduction on creating packages, try the simple package tutorial.

Step 5: Testing

In order to test your package, you need to create a new project, and manually add a reference back to the package 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 package 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 package

When you’re happy with the first version of your package, 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 package should show up.

Step 5: Approval

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

See approval for more details.

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

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 package in the editor. This feature only works for approved packages.

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