David Deraedt

So, now that you've installed some extensions for Brackets, what about building one?

Since Brackets is built using web standards, this is far easier than you imagine. It's also a very rewarding experience, one you can quickly get hooked to.

Using an extension template

A typical way to begin with extension development is to just copy and paste an existing extension relatively close to what you want to achieve. This is a valid way to get started, but keep in mind that not all extensions are up to date and do not necessary showcase the latest best practices. Also, some can be really hard to read, especially if you're new to extension development.

Alternatively, you can use my own Brackets Extension Toolkit which will provide you with a dedicated template which you can just drag and drop to the extension/user folder.

Whatever option you choose, once you're relatively comfortable, I recommend storing your own custom template in the extension/disabled folder to quickly access it later and just copy it to your the user folder.

Understanding Brackets' extension API

If you look at an extension from the first time, chance are you'll feel a bit lost. The bottom line is, Brackets extensions are modules (see requirejs Simplified CommonJS Wrapper), and they need to access other Brackets modules to do anything.

Most of the time, the first thing you'd do is register a command ID with a function so that when this ID is invoked, the function gets executed. This is the job of the CommandManager module. If you add an menu item through the Menus module, the corresponding command ID will be invoked, resulting in the execution of the function.

Here's a very small "hello world" example to illustrate this:

define(function (require, exports, module) {
    'use strict';

    var CommandManager = brackets.getModule("command/CommandManager");
    var Menus          = brackets.getModule("command/Menus");

    var COMMAND_ID = "Hello.World";

    function sayHello() {
        console.log("Hello World");
    }

    CommandManager.register("Hello World", COMMAND_ID, sayHello);

    var menu = Menus.getMenu(Menus.AppMenuBar.FILE_MENU);
    menu.addMenuItem(COMMAND_ID);
}

However, such simple examples won't get you very far. You'll quickly need to learn more about and the API exposed by those other modules. Unfortunately, as of today, there is no real comprehensive API documentation.

The Brackets Extension Toolkit was precisely built to make it easier to understand extension development. It uses its own source code to progressively guide you.

Additionally, I'd suggest reading a few things, including:

• Brackets' source code itself. It is of course the ultimate and only reliable source of information. If you installed the extension toolkit, simply select Help > Open Brackets src. Start by taking a look at Document, Editor, EditorManager, FileUtils and of course all installed extensions.

• The Brackets wiki is full of useful informations (if you can find them), in particular the How to write extensions page which covers basics you should now about. There again, the toolkit includes a shortcut to this wiki under the Help menu.

• If you intend to make an extension which somehow edits your the code of the current document, it's a good idea to get familiar with CodeMirror, the project responsible for the underlying code edition logic.

• My Brackets general architecture could also help you understand how Brackets work, hopefully.

Also, if you plan to include some UI, be sure to check the Extension UI Guidelines draft on the wiki.

Set up Brackets for development

To properly debug an extension within Brackets, select
Debug > Show Developer Tools to open the Chrome developer tools. Note that, in the current version (sprint 14), it opens it in the current Chrome browser window, so make sure you have one open besides Brackets.

Then, you need to disable the cache. You can do that from the option panel.

After that, you'll quickly realize that writing code and testing the result from the same interface is just not the way to go. This is exaclty why you have a New Brackets Window under the Debug menu.

I strongly recommend testing from this second window. You'll then have to set up the developer tools from this window, as explained in the section above. This is what my typical setup looks like:

Working from a Brackets repo clone

As you probably know, Brackets is a simple CEF shell executing some local web contents. By default Brackets starts its execution from the code stored within the application contents folder. As you can guess, it's not such a great idea to edit code directly from this folder.

It's a better option to work from a separate copy of the Brackets source. A good way to do that would be to just clone the Brackets repo from github. If you have the github client for mac or for windows, you just need to go click on the clone button from this repo homepage, and choose and a local destination on your disk.

This will of course have the advantage to let you work with the latest code, making sure your extension is up-to-date.

To tell Brackets to start from a different folder, you just need to press shift while launching the app. Alternatively, you can use the setupforhacking script included with the app.