Package Development Workflow

When developing on a new or existing package it is important to note that Cloud9 has a special debug mode architected specifically for package development. When starting to develop on a package, it is a best practice to have two versions of your workspace open. One in normal mode and one in the debug mode. Use the one in normal mode to edit your plugin code and use the debug mode to run and test your package.

Create a new package

Create a new package from a template via the File menu in the top left corner of the UI. Select File/New Plugin/Full Plugin. (Note this menu option only appears if the workspace is running in debug mode).

[screenshot]

This will create a new folder in ~/.c9/plugins called plugin.default. You will also find a new favorite added to the tree, that points to this folder.

[screenshot]

The package template that is created contains the following files:

package.json - Contains information about the plugin that will be shown in the plugin marketplace
plugin.html - Contains any html that you might want to display
plugin.js - Contains the core plugin code to be executed
plugin_test.js - Contains the a template to write tests for your plugin
style.css - Contains any styling information for the plugin. 
README.md - Write here a description of your plugin

We have a tutorial on how to get started writing your first package, for more information on what to do with each of the files in the template.

Cloud9 debug mode

Open Cloud9 in debug mode via the menu Tools/Developer/Start in Debug Mode. Alternatively you can append ?debug=2 to the url of your workspace to get the same result. While in debug mode, you'll should see a green bar up the top that looks like this:

[screenshot]

Cloud9 in this debug mode will operate differently from Cloud9 in normal mode. The following behavior will be different in order to support plugin development:

  • state settings are loaded from localStorage to make sure that any state used for testing does not conflict with the state in the database.
  • Cloud9 will attempt to load all plugins from ~/.c9/plugins. (In normal mode, only those plugins that have been registered are loaded.)
  • Watchers are set on each of the plugins and they are automatically reloaded when you save changes. More on this below.
  • The log is much more verbose

Panic mode

To disable loading any plugins, append ?plugins=0 to the url of your workspace.

Editing & Debugging

Now that you have created your plugin stub and opened Cloud9 both in debug and in normal mode, we can start developing the first plugin of the package.

To test if the plugin stub is loaded press Cmd-I on Mac or Ctrl-I on Windows/Linux in the Cloud9 that is in Debug Mode ('C9Debug'). This will pop up a red DIV with a picture of a puppy on it and the text "Hello World". Hit that same key combo another time to hide it again.

[screenshot]

First open the browser's developer console (Cmd-Alt-J for Chrome on Mac). You will use the browser's developer console ('console') for debugging purpose. Any console.log() statement in your plugin or any exception that occurs will be shown in the console.

[screenshot]

Now go back to Cloud9 in normal mode ('C9Normal') to edit the plugin. Let's start by making a small change to plugin.js. Change the key binding to Cmd-Ctrl-I for Mac and Ctrl-Alt-I for Windows. After saving this change go back to C9Debug and try out the new key binding. You'll find the new key binding to be working already.

So what just happened here? C9Debug is watching for changes to all the custom plugins that are loaded and it will unload and then reload your plugin when the file is changed.

Currently this is only working for the .js files of the plugins. For any other files the plugin needs to be manually reloaded. For instance, try changing the background color to green instead of red in the style.css file. To reload the plugin go to the Cloud9/Preferences menu and then open the Plugin Manager pane. Find the name of your plugin in your package and press the 'Disable' button in the top. Then hit Enable again to load your plugin.

[screenshot]

Reloading plugins is an optimization that we've built to help you develop plugins faster by not having to reload Cloud9 every time. The technique has it's limits and so when you find yourself chasing a weird issue or when your plugin won't reload anymore, fall back to reloading your IDE. Simply press Command-R or Ctrl-R to reload the window or hit the refresh button.

Deleting a plugin

If you delete the folder from your favourites it will not delete the plugin, it only deletes the shortcut to the plugin. To delete the plugin you must navigate to ~/.c9/plugins/ in your terminal or local file browser (not the navigation tree inside cloud9, it doesn’t show here) and delete the plugin folder itself.

Publishing

Before publishing look at your packages package.json file and add your own personal details, with a name, description and license for the plugin.

Your plugin will also need to be in at least one category, you can find a list of valid categories here

Now you’ll need to set up a git repository for your plugin before you can publish. To do this first run git init in the plugin directory then go to github.com, create a new repository and link your plugin to it by doing something like the following:

git init
git remote add origin [email protected]:[username]/[reponame].git
git push -u origin master

Now you can run the following command inside your plugin folder (~/.c9/plugins/[pluginName]) to publish your plugin to the marketplace:

c9 publish [version]

version can be either a specific version number you’d like it to be (e.g. 0.1.2) or one of the following:

major - Increments the major number (X.0.0) by 1 and publishes
minor - Increments the minor number (0.X.0) by 1 and publishes
patch - Increments the patch number (0.0.X) by 1 and publishes

We use semver versioning for plugins, please follow that guide when deciding what patch level you’re releasing. Plugins with a version < 1.0.0 are considered beta.