Why Aurelia Struggles to Gain Popularity

Well I think the discussion is more or less settled now, but the key takeaway is that seemingly small things like this can make a big difference.

Common composition scenarios like this need to have an abundance of examples and documentation. We need to somewhat keep an eye on the API surface of competing frameworks (Angular and Vue in particular, since those tend to be the ones that Aurelia would be considered as an alternative of; React OTOH is kind of a unique beast that needs a different approach), and make sure that the things we also support, are documented properly, as well as their differences to how these problems are solved in other frameworks.

Whether or not @danny’s company decides to go with Aurelia will likely determine whether or not another dozen (or more) developers end up investing themselves in Aurelia, which then propagates onward.

This is not an uncommon scenario and it has to be easy for people to find the right docs/examples. How do you even know what to search for, if you don’t know that replaceable is there to fill some of the feature gaps of shadow slots?

@Eisenbergeffect are we taking this into account with the new docs?

If we take proper care of this area, it will be much more likely for existing Aurelia users as well as newcomers to stay with Aurelia, and to convince their peers/managers to do so as well.


Yes, this is mostly already taken care of in the content plan for the new docs. For example, we’re trying to use less technical terms for page titles. So, instead of “templating” or “binding”, or something that is a framework-specific term, you’ll have an article named “Displaying Basic Data” or “Working with Collections”. Each article will also have a description, keyword metadata, etc. combined with full-text search, which will all feed into the docs search engine. Beyond that, most articles will have a “next” button at the bottom, pointing you to an article that follows the current topic, and many will have a “related” section for related articles both on the site and for relevant web standards. Furthermore, there is an entire area of the docs that is completely focused on code samples for common problems. These will be designed to “copy/paste” into your own solution, as much as we can make them. We’ve got ideas for what to put there and that will also grow extensively over time based on all of your input (and contributions :smile:).

I should also mention that we’re re-organizing the content a lot and adding a lot of new content. With Aurelia 1, even if a topic was extensively covered, the information was often spread out over many articles. We’re moving related content closer together and trying to create something that’s more coherent. To help us with this, we’ve hired a professional technical writer to review our plans, articles, etc. and help us produce the best content we can.

Hopefully the combination of all these factors in the new docs will make Aurelia much easier to not only learn, but for experienced devs as well to quickly reference or find an example of what they are trying to do.


You have hit the nail on the head here. I would not have known about replaceable. I just tried searching it in the Aurelia documentation… the first result was “Customizing Conventions” which does not even mention replaceable.

The issue here is that I am the sole developer championing Aurelia. Our internal dev mailing list has over 70 people (and that is just for one section of my organisation). When the issue is discussed in our tech lead meetings, all the other devs hear is “this thing is harder to do in Aurelia than Angular or Vue”. They don’t care why.


Me too.

I am pretty sure the replaceable was the old way to compose view before shadow dom slots was implemented. Shadow dom slots syntax is more intuitive and easy to understand, so v1 doc didn’t mention replaceable at all.

I am so glad the old replaceable can fill the gap of shadow dom slots. This particular use case of replaceable in table should be and will be documented in Aurelia 2.


I know it is far from final, but one thing I noticed while browsing the vnext docs on Github is how many articles are in the “Getting Started” section (18!). The other frameworks only have 3-5 of them. Personally seeing a long list of things I should read just to “get started” makes it hard for me to get invested. A perfect example of this is IdentityServer 4, simply too much to consume before I feel like I know what I’m doing. I liked how back in the day there was a separate soup to nuts series for Caliburn.Micro to consume after I’d already gotten started that was clearly separate from the initial setup. I suggest this be broken up a little more?


@CuddleBunny Would you mind opening an issue on GitHub for that so we can discuss further? I’m open to any recommendations for naming and grouping of articles.

1 Like

Done: https://github.com/aurelia/aurelia/issues/574


I hope no one minds that I am reviving this thread.

I’m a python developer using Django in most of my work. I have a lot of experience with Angular, some experience with Vue, lately with Aurelia. I am a passionate Django developer, but I struggle trying to get frontend frameworks to work well with Django. I find that Aurelia is an incredibly good fit for Django and I feel strongly that Aurelia could profit by promoting this angle a bit more. Here are my main points.

  1. Django is python, and tries to stay pythonic wherever possible. Expect for the HTML Templating there is no magic DSL, or new language format. It’s all standard python and HTML, and the quality of the programming is very high, while remaining understandable. Aurelia also uses existing standards and accepted programming patterns rather than inventing new meta DSLs magic languages. Programming Django makes you a better Python programmer, programming Aurelia makes you a better Typescript programmer ( so much so, that I have even begun to use typing in python, making me an even better Python programmer ) Its all just lovely.

  2. Aurelia does not force an all or nothing method upon the developer. In various Django conferences and blogs a bleak future is being forecast in which Django only provides an API interface and the frontend is all just SPA Angular, Vue, or React. This is a shame. Django has a lot of great functionality that is wasted and has to be rebuilt in the frontend. Django + Aurelia works great and allows the developer to choose which responsibilities are handled by the frontend and backend flexibly. This would make long time Django developers happy. thanks => aurelia.enhance()

  3. (Related to 2) I think many Django developers are desperate to get away from using jQuery. Those that have used Angular know the joys of data binding, but struggle to integrate it with all the great Django features they are used to. When you let Angular in, it takes over and does not want to play nice with Django, its frustrating, and leads to the unnecessary splitting of server-side app and client-side app. Many people have just resigned themselves to this being the new way, but it does not have to be like this. thanks.again => aurelia.enhance()

  4. Django is a very active community, there are yearly big conferences, and many smaller ones all over. Many tutorial videos sites and channels with lots of follower. Presenting Aurelia as a great fit for Django would give Aurelia good access and presence in an active community that is searching for exactly this thing. I also find that Django ( and Python ) developers enjoy reading and writing high quality code, Aurelia fits here as well.


@aGustafson Since you have your first experiences with this combo do you think you could create sort of a baby-steps article which could also be promoted on the official blog perhaps? That might be a good start in the right direction


Yes, definitely. I’m making notes for a simple example game, where Django manages backend validation and Aurelia enhances the frontend. I’ll try to put something together next week.


Very interesting post. Did you build an SPA with Aurelia and Django or did you use Aurelia to enhance only part of the page (like we would typically do with vue or React)? I’m asking because I am a Django developer myself and wander how we could fit those two together aside from building an SPA and Django only doing the API stuff (currently at work we combine Django with React).


@aGustafson and @Jenselme trying not to sound unpolite I’d kindly ask to open up a new topic as that is a very interesting discussion which might get lost in this large thread. I’m definitely interested to see whats coming out of this

1 Like

Yes, we’ll take this to another topic, and I’ll reference it here, as well as in the two Django specific topics. Just to answer @Jenselme quick, I use Aurelia to enhance Django pages. I use the built in CLI Bundler, add an http proxy to Browser-Sync for live reloading, and can even use Django Compressor to shrink the Aurelia bundle down a bit.

edit: I created a sample Django/Aurelia project as Tutorial.
Topic is here: Enhancing Django with Aurelia


In my opinion docs and framework are the best, the problem maybe, big companies competing with angular, react this gives ideia of long support. I was using Silverlight and then Knockout, one of the this that I hate on Microsoft recently is this attempt to gain more people on trending tenclogies and let old dotnet guys like me seeing Knockout die on their projects and Aurelia struggling to compete with larger teams like angular. Not sure about blazor but seems like another trap. Really hard to achitects and developers to convince and take risks on framework that start to get unsupported and unmantenaid plugin if they are

1 Like


No mention of Aurelia. Says it all really.

1 Like

Well, it’s a bit unfortunate, probably side effects of not doing any marketing :smiley:

1 Like

Great marketing can work with word-of-mouth. Great sample apps for example. I’ve shown tons of people the main page sample app todo list, and that is what people first see about Aurelia.

  • Benchmarks: If you have objective measured metrics, such as speed of loading DOM benchmarks. Then easily, there will be blogs saying “aurelia is fastest vs react/vue” that alone will make a huge difference (but such blogs I haven’t spotted yet, mainly because someone needs to go around emailing the blog authors saying to test this framework as well----or write a medium.com blog article about benchmarks themselves).
  • Stars on Github: Time and effort should be spent on Github.com “stars” that’s how you go up the ranks. 11k already for Aurelia, not bad. Just need more github users to support or star it.
  • Documentation: Beautiful, pretty, syntax highlighted, easy to understand documentation is vital. It can make or break your app. The only complaints I hear from junior / mid-level engineers about Aurelia when they use it is this summary line I’ve concentrated out of what they complain about: “not enough examples and documentation is a bit advanced [as in makes assumptions about beginners]”
  • Examples: Following up on that, great examples on the main page can be a great help. The guides have 2-3 tutorials. Make sure every example is super easy to setup. I’m liking the new aurelia-cli 1.2.3
  • Avoid Breaking Changes: Yes Aurelia 2 may have breaking changes, but if so, a very explicit easy-to-find guide prominent on the front pages that show you MIGRATE Aurelia 1 to Aurelia 2. Or “Quick list: what not to do in Aurelia 2 after Aurelia 1” … Some quick Cheat SHEETS (Did I tell you how awesome cheat sheets are?) on how I should use Aurelia 2 (I’ve seen talk about it for a long while, but I have absolutely zero clue what Aurelia 2 looks like for now or will look like). Aurelia-cli 1.2.3 looks awesome, but I already encountered some bugs with setting up environment files in prod build. So breaking changes hasn’t happened in Aurelia itself, but aurelia-cli has had some issues which is what a lot of people rely on.
  • more gifs – Aurelia blog has some nice screen-gifs showcasing Aurelia. Please more of that EVERYWHERE… Gifs are so spectacular for marketing.
  • Powerpoint - You don’t have to spend big money on advertising. In fact, don’t spend anything on marketing before Aurelia 2.0… But easily get someone to make a nice analytical Powerpoint that a corporate leader can see and say “hey, why should I use Aurelia over react/vue/ASP.net/PHP/drupal/SpringBoot” and the emphasis should be “don’t have to find trained engineers, just get some comp-sci kid from college and let him look at a few guides on Aurelia and ECMAScript and he should be good to go.”

If you debate anyone on framework wars today, and ask “Why not Aurelia?” after they used Aurelia: the 3 answers will be: "(1) not popular, not enough examples… (2) can’t find the right way to do this in Aurelia docs… (3) [little detail issues that are derived from lack of experience with Aurelia]: ‘needed dashes in html, camel-case in javascript’, ‘my VariableChange handler didn’t work’, ‘bindingEngine when do i need it’



The docs have changed for the better a lot, but to me it´s still a huge issue.

Hopefully AU2 docs will start with tutorials that give your self-efficacy a boost.



Another vote for this. Documentation is the biggest downfall of the framework. 2nd is marketing. I’m going to be positive that things will be better for 2.0

I know it’s open source, and I wish I could contribute, but there are many reasons why I can’t.


Docs are already off to a fantastic start in v2. I’m not to worried about them at this point so long as they’re close to finished before a documented pre-release.