Configuring your Orion project

Everyone loves to customize stuff.

In Orion 11.0, we provided support for .tern-project files so you can do just that. A .tern-project file, for those unfamiliar with them, is a configuration file that lives at the root of your project, is entirely JSON, and tells Tern how and what to run with.

Lets see an example file (the one used in the Orion client):

{
  "plugins": {
    "node": {},
    "requirejs": {},
    "express": {}
  },
  "ecmaVersion": 5,
  "libs": [
    "ecma5",
    "browser",
    "chai"
  ]
}

See? It’s not so bad. Now lets talk about what all the parts mean, and why you would want to make one.

The first thing typically asked when talking about these files and configuring your project is: “what if I don’t have a .tern-project file?”. The short answer is; we start Tern with a default configuration that contains every plugin we pre-package in Orion.

The longer answer is:

1. you get all of the required core services plugins from Orion (like HTML support, parsing plugins, etc)
2. you get all of the pre-packaged plugins (mongodb, redis, mysql, express, amqp, postgres, node, requirejs and angular)
3. you get a default ECMA parse level of 6
4. you get a default set of definitions (ecma5, ecma6, browser and chai)

Basically, everything will work right out of the box, the downside is that you get a lot more stuff loaded in Tern than you might need (or want).

ecmaVersion

This is the most common element that people create a .tern-project file for, and its an easy one. If you are coding against ECMA 6, the defaults are fine. If you are not, its best to change this to be 5.

libs

This entry describes type libraries you want Tern to use. These libraries provide type information that is used for content assist and inferencing. At the moment, only the definitions that come pre-packaged in Orion can be entered in this list, which include  ecma5, ecma6, browser and chai.

I know what you are thinking. What if I have a definition not in the list I would like to use? We are working on support for custom definition files directly in the project, and providing a UI to install new ones.

plugins

This entry describes all of the plugins that you want Tern to run with. As mentioned, by default you get everything. Leave it out? You get everything. Empty plugins entry? You get everything.

Regardless of what you put in the plugins entry, you will always get the core services plugins that Orion needs to function – so no, you cannot break the tools.

While everything will work fine right out of the box with all plugins running – you can really improve the performance and memory usage of the tools if you tell us what support you actually need. For example, working on a node.js project? only include the node plugin. Working on AMD browser project? only include the requirejs plugin. You get the idea – only load what you actually need.

At the moment, the list of plugins that can be enabled is amqp, angular, express, mongodb, mysql, node, postgres, redis, requirejs. And yes, we are working on ways to provide your own.

loadEagerly

This entry is a list of files that are so important, that you just have to have Tern load them when it starts up. All joking aside, this entry is best for pointing Tern at the ‘main’ in your project. For example, say you were working on a web page. You could add index.html in the loadEagerly entry to have Tern automatically load that file and all the dependent scripts right away, so everything was primed and ready to go immediately (as opposed to Tern filling in its type information as you open and close files).

dependencyBudget

Don’t change this entry. Set too low, it will cause dependency resolution to time out (incomplete type information). Set too high, the IDE will wait longer before answering whatever you asked it (content assist, open decl, etc).

So thats it. Those are all of the supported entries that can appear in the .tern-project file. A pretty short list.

You can’t break the tools by setting a bad entry – we have sanity checking that will revert to a “something is wrong, load the defaults” state. We also have linting / sanity checking that will alert you if you have broken something in the file.

Tern project file linting

Broke the file and still navigated to another file (or maybe brought in a change from git that broke the file)? We will alert you that its bad in the banner, with a handy link to jump to the file and fix it!

Tern project file banner message

Remember, you can ignore all the warnings (if you really want to) and Tern will still start with the defaults as a safety measure.

Feeling a bit lazy and don’t want to type out a brand new file for your project? Just open up the new (empty) .tern-project and hit Ctrl+Space, which will auto-magically insert a shiny new template for you.

Happy configuring!