Isomorphic-git has hit 1.0, with the promise of tighter IDE and Typescript integration, albeit with a long list of breaking changes.

The just over two years old project aims to be “a pure JavaScript reimplementation of git that works in both Node.js and browser JavaScript environments” while the “’isomorphic’ in isomorphic-git means that the same code runs in either the server or the browser.”

The 1.x version was debuted by project William Hilton in a blog post this week. Top of Hilton’s list of improvements is better IDE integration.

“Thanks to improvements in TS 3.7, we can auto-generate the declaration file using tsc –declaration –allowJs,” he wrote. “This has the added benefit that the JSDoc is also included in the index.d.ts which leads to a much richer IDE integration.” While this means the main description body and example code are shown, “Sadly, parameter descriptions still aren’t shown”.

Functions have been tweaked so that core object interfaces are “reused wherever possible”, resulting in “a cleaner API where the documentation comes to you, right where you are.”

Overall TypeScript Integration has been improved, so that return types “gel with TS better now” while exceptions “are also well-typed now, so you can access their .data property with confidence”.

Hilton also promised “More Good Defaults, Fewer Bad Defaults”, with a number of helpful behaviours that were previously opt-in now set as defaults. For example, the init function “doesn’t overwrite your config file if it already exists”, while the checkout function “now warns about conflicts instead of blindly overwriting files”, and the commit function “doesn’t silently remove submodules”. Likewise, a number of default behaviours have been removed, such as “automatically appending .git to the end of URLs when you clone them” which could break cloning for some servers.

Hilton also wrote that the latest version now embraces callbacks, while “the plugin system and its awkward global state and funky namespace ‘cores’ are gone.” This would be safer, have better locality and would enable some “cool” new behaviours, he said.

Hilton also wrote, “It is safe to say that the API for isomorphic-git will remain backwards compatible and have no breaking changes for at least a year, possibly two or three. Because I want you to always be able to upgrade to the latest and greatest version of isomorphic-git without having to change any of your code.”

But…as this is a major release, there is a longish list of breaking changes in this version, including the aforementioned plugin system. Likewise, the supported node and browser versions have been bumped. You can see the full list of breaking changes on Hilton’s post.