CreateExtension.md

Creating an extension

This guide will go over how to quickly and easily create a basic Roc extension, be that a package or a plugin.

Normal Extension

1. Create the project

We will use a Roc template to create our extension but you do not have to do that.

We will start by creating a new project using the init command in Roc.

Creating a package

$ mkdir my-package && cd my-package
$ roc create init rocjs/roc-template-package

Creating a plugin

$ mkdir my-plugin && cd my-plugin
$ roc create init rocjs/roc-template-plugin

2. Define the Roc Object

A Roc extension is something that exports an object named roc from its main file. This object, called the Roc Object, can define a number of things like commands and configuration, all documented here. Roc enforces that the Roc Object contains at least a name, a version and one more thing other than description. The name and the version will automatically be fetched from the extensions package.json if not manually provided.

An example of a simple plugin  

package.json

{
  "name": "roc-plugin-example",
  "version": "1.0.0",
  "main": "index.js"
}

index.js

module.exports = {
  commands: {
    example: 'git log',
  },
};

When the plugin is installed we are able to run roc example to in turn run the git log command.

Existing extensions
A great place for inspiration on how to structure extensions is to look at the existing one under the rocjs organisation on GitHub.

3. Publish, Building, and more

A Roc extension is like any npm module and nothing special is needed to build or publish them. However when installing from the template a convenient tool will be provided called roc-internal-dev that can be used to make the process simpler.

roc-internal-dev uses Roc internally and all the available commands that are available can be listed using npm start.

Standalone Extension

A standalone extension is an extension that does not have a package.json and normally is the first version of an extension that is used directly in a Roc project without the need to publish it. See more here about the standalone property.

Relevant questions from FAQ

• I have some logic in my roc.config.js that I would like to make into an extension, how can I do that?
• I want to add some functionally to my project that can’t be done through the project API and is something strictly unique to this specific project, what is the best way to go about this?