Why Aurelia Struggles to Gain Popularity


I would like to also point out documentation, I’m a big lover of GitHub and use it every single day. What I wish Aurelia would adopt is to provide some quick documentation in each repo right in GitHub. I don’t want to open the Aurelia web site documentation to know what the GitHub repo/plugin does. Also almost none of them, even Aurelia plugins, have demos. I believe that at the very beginning all repos had docs via readme.md and demos (take aurelia/benchmarksfor example, it’s all in there on the first page of GitHub, even the demo). All new repos, nowadays just tell you that it’s part of the Aurelia family and the link is for aurelia.io which doesn’t help much, most people would click the link and close the page once they find that it doesn’t provide info of that plugin/repo. There’s a few Aurelia that I just don’t know or understand what they do, and since there’s no demo neither docs, I don’t bother going on the Aurelia doc site to find what that is… and I can surely assume that a lot of developers do exactly the same as I do and get turned away by not seeing the info they want in the usual place they look.

Take Aurelia/UX for example, I have a rough idea of how it looks like but the link to the Online Playground Gist, just doesn’t do anything on my side (all I see is Playground for Aurelia Ux component as the output), that is a turning me away… I’ve seen a working demo somewhere, but can’t remember where.

On the positive side, I like how the new sandbox & CDN with 2 script tags is going. I see big potential of including them in each of the Aurelia repos. Doing just that, would help in keeping the new developers interested to know more about the plugin. I’m an enthusiasm of Aurelia, unfortunately my work chose Angular (as you can guess for popularity), but I’m still doing quite a lot of work in Aurelia plugins and all of them have demos and docs right in GitHub, if you want to use it, this is what it looks like… Why not do the same for Aurelia itself? I know that not everything is demo(able), but for plugins (like UX), it should definitely have working demos (at minimum a working web page).

For reference the Aurelia plugins I support are Aurelia-Bootstrap-Plugins and Aurelia-Slickgrid, they both have demos and lots of docs, the latter has all it’s docs through Wiki and there’s a ton. Obviously what would be even better is to add the new sandbox instead of just GitHub web pages, but at least you can see the result without leaving GitHub (which is what I am trying to explain in this big post).


It would help early adoption if the default Readme.md could explain how to get up and running, preferably without pointing to ANY other gihub (or other) repositories). If there are more than 3 steps, that is too many! A disclaimer and little else does not encourage experimentation :slight_smile:

“Please keep in mind that XXX is still in (pre-)alpha/beta and by no means ready for production (or even development) yet. Many YYY features and ZZZ use cases around the public API are still untested and there will be several breaking changes to come.”


I found this site recently:

I noticed that there are 12 js frameworks listed on the homepage and Aurelia is not one of them.
If you go to the “Labs” tab you can find Aurelia, there is link to the source on github but it’s very old.

I am not sure how popular the todomvc site is, but having an up to date Aurelia example visible directly on the home page will be another good way to help it gain more popularity.

If i get chance i will create an up to date Aurelia version myself using the CLI / typescript / webpack.


Microsoft seem to be educationally steering (young?) developers away from MVC towards Razor Pages (which are not SPAs) to encourage single responsibility principle development though could still use only Identity pages for login/register/logout with an Aurelia (or other framework) SPA


Thanks again for the feedback. In the last couple of weeks we’ve taken some action to address a few things:

  • Location of Documentation - Interestingly, every repo has had its own documentation, in a standard “docs” folder for years. At various points in time the README files pointed directly to that. However, what we’ve found is that this actually hurt our documentation efforts. For people who wanted to actually fix, add to and create new/better documentation, it made it almost impossible to contribute, resulting in most of the documentation problems we have today. As a result, in the last couple of weeks, we’ve moved all documentation to the “documentation” repo (following another typical pattern for GitHub orgs). What we haven’t done yet is update all the repo README files. I think that makes perfect sense to do. We’ll work to do that in the next week or two so that anyone reading the README files will get pointed to the correct location. But, for a project this size, it’s turned out to not be maintainable (and actually destructive) to spread the documentation out across dozens of repos. For vNext, we have a middle ground that gets us the best of both worlds. Because vNext is being developed in a monorepo, all core libraries, plugins, etc. are in a single repo and all docs pertaining to them are in a “docs” folder within that single repo.
  • Authoring of Documentation - In our documentation, we used some custom markup for code samples and a couple other things. All that has been removed and replaced with simple Markdown which enables it to render correctly on GitHub now and also with enhanced rendering on our site. Furthermore, the documentation is now organized in folders that exactly match the table of contents on the web site. In fact the ToC on the site is generated from the folder structure of the documentation. Furthermore, every folder has a README with a description of what documentation is in that folder, so all folder-views render nicely on GitHub. We’re going to continue to improve this as well.
  • Samples/Examples/Demos - Maintaining samples for a project this large is very challenging. While at Microsoft, I watched the whole company struggle with this exact problem for the entire time I was there. It’s a big challenge when you think about keeping samples up to date, in sync with changes, versioning, organization, etc. We have had some samples in our docs, particularly in the binding documentation for a while, but it has been difficult to maintain and keep working, which is why our samples did not grow to cover more areas. However, new tools like codesandbox.io are making it easier for us to solve this problem. In the last couple of weeks, we’ve removed our custom inline demo solution and moved the entire binding docs over to using codesandbox. We now have a way to organize, maintain, update and share these samples both with integration into the site/docs and independent of the site docs. In fact, if you visit our home page, we just launched an update there in the last couple of days which embeds a few sandboxes directly. We built these sandboxes directly to mirror what we’ve seen on other sites, like React, so we can show how much simpler and cleaner the same thing is with Aurelia.

We’ll continue to work on improving the documentation and samples situation. I’m personally spending time working on it now. There’s a lot of work to do there but I’m trying to chip away at it little by little each week. One of the next things that’s coming up is a simple way for documentation contributors to preview their documentation edits as they would look directly on the web site. It’s not necessary but we’ve heard from a number of people that they want to test it out so they can be sure it looks great both on GitHub and on the web site. So, we’re going to enable that. At the same time, I’ll be writing some new documentation targeted towards contributors (some of you and hopefully more soon :smile:) so that it’s clear how to cotribute both to the codebase and to the documentation.

Finally, everything that we’re improving for our vCurrent documentation is something we’re bringing over for vNext, so that when that launches all of this will be in place from the beginning.

It’s Thanksgiving today in the USA, so let me also take this opportunity to thank all of you for being part of the Aurelia community. Thank you especially to those who are so passionate to see Aurelia improve and for your constant feedback that we value so dearly.


Rob, thanks for the great work. I hope you had time to spend relaxing today!


Just wanted to follow up. Community member and book author @sean.hunter.aus has been helping us on the README file action item identified above. Thanks to his contribution, we’ve pushed out an incremental update to the aurelia-framework readme file. You can find it in the usual place here:


Since we have a lot of repos under the Aurelia org, before we propagate this general pattern across all repos (quite a bit of work), we’d like to get your feedback and make any revisions, to ensure that we’ve got something that you all think is going to be valuable to both you and to people who encounter Aurelia for the first time.

If you get a chance, please have a look, and let us know what you think. Again, thanks for all the passionate feedback here. It really helps us all work together better to make Aurelia the best it can be.


The navigation looks fine. Any chance of adding a Quick Start for Net Core 2.1 including links to project templates for the Microsoft Stack users? Net Core 2.2 is just around the corner and looking forward to a Microsoft Open ID Connect based authorization server (https://github.com/aspnet/Announcements/issues/307) :slight_smile:


Great work! but please consider not calling it Aurelia Script. When I first saw it I thought you are creating a new language. Unless that’s what you are doing (which would be bad) . Looking forward to vNext.


Maybe this is little late, but the most problem I had with Aurelia is with unit testing.

First of all, it is difficult to get the test setup right (but I guess that is not Aurelia specific).

Secondly, it seemed that the tests are not running in complete isolation, as often I had this experience that dis/enabling one test affects the other test cases. Here is a similar example.

I hope that it will be better in vNext. Also it would be helpful if a recommendation of test setup comes from Aurelia team. Personally, I don’t care about the test setup as long as it operates in a predictable fashion :slight_smile:

Thank you for the awesome framework :slight_smile:


Thanks for the feedback @Sayan751 I think we’ve got this solved already for vNext as we have over 40,000 tests for the framework itself now. We’ll be looking to package up any helpers based on our testing work there and provide those to the community. That said, I think the way vNext is designed just makes testing much easier to begin with as well. It’s definitely something that was on our list to improve.


Awesome!! looking forward to it :slight_smile: