I don’t know why, but UI-Router doesn’t seem to be very clear about their versions, maybe they are ashamed of the old ones. However, this is really confusing and might lead you to install the wrong one. Their links just redirect me in a circle without providing me with any real idea what to install. It’s really quite the achievement from people building a router to build the most confusing navigation EVER. Why is this? The UI Team had a successful project for Angular 1. It grew and grew and just as Angular 1 became a mess, so did UI-Router become a mess. So they rewrote the entire core in typescript and made it framework agnostic. Which in turn allowed them to provide implementations for Angular 1, Angular 2 and React. So today exist the following versions:
- 0.x.x for Angular 1. Probably what you are using in an existing angular 1 project
- RC1 for Angular 1, Angular 2 and React.
This means the confusion is especially for the Angular 1 users, as for React and Angular 2 users, there’s only one project (however badly documented and still RC 1).
Okay, so here’s what you really need, depending on your situation.
If you haven’t started your project yet or are early on
Then choose ui-router 1 for your project, either the Angular 2 flavor or React flavor (since I don’t assume you’ll use Angular 1). It’s in a late beta/ rc1 (release candidate 1) state as of January 2017.
For Angular 2:
npm install --save ui-router-ng2
The links you’ll need:
- Tutorial for Angular 2 / UI Router-1
- API-Reference: There’s none so far
npm install --save ui-router-react
If you have an existing Angular 1 app
Now this is where it gets confusing. You’ve probably built your codebase on UI-Router 0.x.x (e.g. 0.3.2) which they call UI-Router Legacy now. They’ve rewritten the entire codebase, which is UI-Router 1 now, which is just about to become “stable” in 2017.
So if you want just to update your probably existing UI-Router, then use:
npm install --save angular-ui-router
which install ui-router 0.4.2 as of January 25th 2017. Typical things you’ll find in your 0.x.x installation are things like `$stateChangeSuccess`.
The links you’ll need for working with ui-router 0.x.x:
- API Reference: https://ui-router.github.io/ng1/docs/0.4.2/index.html#/api
However, it doesn’t feel good to build more code on something that is now labeled UI-Router Legacy does it? You probably want to migrate away from it, but when is a good time?
If you’re already with Angular 1.5 or Angular 1.6 and use “component based architecture”
What’s really cool about UI-Router 1 is, that you can use a component as root for your view. So you can finally write EVERYTHING (except for services, of course) as a component! But be wary: A MIGRATION TO UI-ROUTER 1 MIGHT BE PAINFUL! They broke a lot of stuff and you should really factor in some time for a refactor!
How you can install it UI-Router 1:
npm install --save angular-ui-router@next
It’s in a RC (release candidate) state, and the way forward. You wouldn’t be in too much of a hurry for the migration, unless you’re introducing a lot of new views which you’d like to strap to components instead of the legacy views. However, don’t be hasty, as it’s RC 1, will bring a lot of breaking changes and is not really documented well yet. The links you’ll need for the migration are those:
Bonus: Can I install UI-Router with Bower?
It’s also considered legacy (god damn), but Angular 1 you can.
Installing “the latest legacy version” (0.x.x):
bower install angular-ui-router
Installing UI-Router 1:
For Angular 2 and React it’s not possible.