Inadvertent mixing of v1 with v2

I’ve been trying to learn Aurelia, and have encountered some serious difficulties.
I was ready to switch away from Aurelia, but decided to give it another try.

I now believe that the issue that has caused me the most trouble is the inadvertent inclusion of Aurelia modules from both v1 and v2.
Apparently this is easy to do, and this took me quite a while to figure out.

I think there are a few things the Aurelia team can do to help:

  1. Please have all documentation clearly indicate which version is it for.
    I’ve found that I can navigate within the v1 docs or the v2 docs without confusion. But when I use a search engine, I can’t easily determine to which version the docs apply. So while trying to learn Aurelia, it is very easy to get versions crossed in example code.
    I would like a version in the URLs. And also some sort of branding on each page, such as a logo or color scheme.
  2. Please disallow using v1 libraries and v2 libraries in the same app.
    I think I got in trouble when I used a 3rd party library which used the version that was different from the one I was intending to use.
    It would be great to get a build error upon mixing libraries.
  3. The above issue also led to mixed TypeScript typings.
    This only complicated work on my app.
    I looked at your typings, and it seems like your packages provide their own typings (as opposed to getting them from npm via @types). So I think you already have a clean solution.
    I’m not sure how preventing mixed typings can be accomplished, but if mixed libraries produce an error as suggested in (2) above, I think the problem of mixed typings goes away.

I think we can start solving this by encouraging all the plugins to brand themselves with v2 so that it won’t be mixed. Aurelia v1 has been out for a long time, and v2 not out of alpha, I think you can safely assume that everything you see is for v1.

Btw, are you developing using v1 or v2?

I think I found v2 first, but did the tutorials using v1, but not realizing they were v1.

It sounds like I should be using v1.
So I’ll make sure I’m using v1, taking care to check the versions of the docs I reference, and any libraries or typings I use.

1 Like