TernJS plugin for Sublime Text

As Credits page says, Emmet is going to be a brand name for tools for web-developers. And today I want you to present a new tool: Sublime Tern.

What is TernJS?

TernJS is a JavaScript inferring engine written by Marijn Haverbeke. Basically, it can trace context object in JavaScript and give you some info about it: its type, available properties, definition and so on. It can provide you with great advantages while editing JavaScript code: correct code completions, basic refactoring (like variable renaming) and location of object definition. Also, it’s written in JavaScript and it can be extended.

Usually, features like valid code completions and variable renaming are available in big IDEs like Eclipse and WebStorm, but now they are coming into your favourite editor with Sublime Tern plugin!

How to install

Sublime Tern can be installed as any other plugin with Package Control:

  1. In ST editor, call “Install Package” command from Command Palette.
  2. Find “TernJS” in plugins list and hit Enter to install it.

When installed, Sublime Tern will automatically download PyV8 binary required to run this plugin. If you experience issues with PyV8 loader, you can install it manually.

Warning: if you have Emmet plugin installed (and you really should :-) and using Sublime Text 2, you have to make sure you have the latest PyV8 binary. It must be automatically updated within 24 hours (you need to restart ST2 editor), but you can forcibly update it:

  1. Quit ST2 editor
  2. Completely remove PyV8 package (remove this folder from ST2’s Packages folder)
  3. Start ST2 editor. Latest PyV8 should be downloaded and installed automatically.

With old PyV8 binary, you’ll experience a lot of crashes.

How to use it

You should keep in mind a few things before using Sublime Tern plugin.

Projects first

To get most of Sublime Tern plugin, you should edit your files inside Project. When you open a JavaScript file in ST editor, plugin automatically detects project for it and loads all JS files from it for code completion (read “Configuring Project” section below to alter this behaviour).

Otherwise, if you’re editing file outside project, code completion and other actions will work for this file only.

Slow start

When you open JS file from project for the first time, you may experience editor slow down, especially for large projects. It’s because Sublime Tern plugin loads and analyses JS files from your project so you have to wait a bit.

Also, you may receive a “slow plugin” warning in Sublime Text 2: you can either skip it or disable this warning.

Reload TernJS

If you create or update files outside ST editor, or you believe that TernJS doesn’t contains most recent version of your project files, you can force Sublime Tern plugin to update it’s state. Simply call “TernJS: Reload” action from Command Palette to re-initialize TernJS servers.

Available actions

All actions are available in ST’s Command Palette and have no default keyboard shortcuts. You can define them by your own, valid command names are:

Configuring project

By default, Sublime Tern loads all JS from your project folder and provides completions for standard ECMA5 objects like String, Array etc. If you want to load specific files only or have completions for browser objects or jQuery, you need to configure project first.

In Sublime Text, projects are defined by simple JSON file with .sublime-project extension. You can add ternjs section into .sublime-project file to set-up TernJS for your project.

The example project file with TernJS config may look like this:

{
    …

    "ternjs": {
        "exclude": ["wordpress/**", "node_modules/**"],
        "libs": ["browser", "jquery"],
        "plugins": {
            "requirejs": {
                "baseURL": "./js"
            }
        }

    }
}

Available options:

Known issues

Sometimes, especially on complex libraries like jQuery or Underscore.js, you may experience heavy slowdowns or even crashes. Check ST console for possible errors. If you see something like this:

RangeError: Maximum call stack size exceeded ( js/infer.js @ 43 : 21 )

…you should:

  1. Report to main TernJS repo (like so).
  2. Exclude this file(s) from project config with include and exclude preferences (see “Configuring Project” section above).

Please note that Sublime Tern (as TernJS itself) is in early beta stage and may not work properly or even crash your editor. If you experience issues with code completions or crashes, you should report directly to main TernJS repo or Sublime Tern plugin repo.

comments powered by Disqus