How to Create a Starter Kit

OpenZeppelin Starter Kits are the easiest way to get started building an Ethereum powered apps. Bundled with all the tools necessary to get started, you can be up and running with a working smart contract powered app in less than a few minutes.

Given the success and positive feedback of tutorial kit and GSN kit as well as the interest of other companies into creating their kits, we’ve decided to create a guide on how to do it.

Why Should I Create a Starter Kit?

It is still very hard for new developers to enter the Ethereum ecosystem compared to Web2. New developers suffer from a lack of comprehensive documentation and a huge upfront commitment. Starter kits represent a bridge between Web2 and Web3 supercharged to bootstrap developers into the Ethereum ecosystem within minutes, using familiar concepts and technologies, such as React, NPM, and Mocha, while introducing Web3 components like Infura, OpenZeppelin, Truffle, and Rimble. Creating a starter kit dedicated to a particular project or tool is a great way to spotlight it for new developers in the space as well as to create hands-on experience and materials to run workshops. GSN Starter Kit is an example of a project focused starter kit which helped to kickstart Gas Station Network.

How to Create a Starter Kit

To create an OpenZeppelin Kit you’ll need to publish a GitHub repo containing your kit project. The GitHub repo has to contain a kit.json configuration file and have a stable branch. The repo should have a meaningful README.md file walking users through installation, running and building a kit. The stable branch will be used as a source for the kit’s deployment. Use the stable branch only for kit releases. The tutorial kit is a good example.

Checklist

  • Create a GitHub repo
  • Create a stable branch on the repo
  • Add a valid configuration file to the root of the repo
  • Add desired tools and packages to the repo
  • Add meaningful README.md file to the repo
  • Push a release version to a stable branch

Configuration file

Every Starter kit must include a kit.json configuration file. This file has the following structure:

    {
      "manifestVersion": "0.1.0",
      "message": "More at https://github.com/OpenZeppelin/starter-kit",
      "files": [
        ".gitignore",
        "LICENSE",
        "client",
        "contracts",
        "migrations",
        "package.json",
        "solhint.json",
        "test",
        "truffle-config.js"
      ],
      "hooks": {
        "post-unpack": "npm install && cd client && npm install"
      }
    }

manifestVersion

A version of a manifest that ensures proper handling of a kit. Always use the version provided in the documentation. Do not bump it to publish a new version of a kit.

Message

A message displayed in the terminal immediately after installation. Keep it short and to the point.

Files

An array of files and folders to be copied from the repo. An empty array would result in copying all the files.

Hooks

An object containing terminal commands to execute during unpacking. Currently, only the post-unpack hook is supported, which is executed right after unpacking a kit.

How to Test a Starter Kit

Once your starter kit is ready it is always a good idea to give it a test run. It is possible to install a starter kit from any Git branch using syntax npx openzeppelin unpack 'yourGitHubHandle/yourRepoName#branch', for example npx openzeppelin unpack 'OpenZeppelin/starter-kit#develop'. Make sure your starter kit runs fine on Linux, Mac OS, and Windows. We have experienced installation and running issues depending on a platform.

How to Release a New Version

Once you’ve added desired changes to your starter kit, push them to the stable branch and they will be instantly available using an unpack command.

How to Install a Starter Kit

Running a command npx openzeppelin unpack yourGitHubHandle/yourRepoName will install a starter kit in the current directory, for example npx openzeppelin unpack 'OpenZeppelin/starter-kit'.

Getting listed at OpenZeppelin website

We value community contribution and would love to list your Starter Kit on the OpenZeppelin website. Every submitted kit undergoes a screening process to ensure safety. To start the process send us an email with your desired kit name and description, along with a link to its GitHub repo. Once the kit is verified, the short name is assigned to it to simplify installation, like openzeppelin unpack gsn.

We welcome projects to build their kits to showcase their products and ideas. As always any feedback and comments appreciated!

1 Like

Hey @asselstine! I’ve spotted you have apollo-link-ethereum-example which I am dying to check out. Given it is a Create React app it makes it a perfect target for Starter Kit :heart_eyes:

1 Like

I see, so the started kits are create-react-apps? That could be worthwhile.

Regarding that, there is an interesting update regarding ALE. We’ve simplified the codebase dramatically and redesigned the interface and will be releasing the new framework under a different name very soon!

I’ll keep you posted…it’s much simpler to understand now!

2 Likes

Would love to try it. Let me know as soon as it out!

1 Like