Context for the architectural design problems Aurajs solves + real examples of how to couple Aurajs with existing frameworks

[CalebGilbert]

Hi all, I apologize in advance if my ambition to share my thoughts/feedback outstrips my talents for doing so.

tldr; The Aurajs site/homepage/github do not give enough context and origin to the architectural design problems Aurajs actually solves (unlike the article that was the genesis of Aurajs, which imho does a great job). In addition, actual examples of how to couple Aurajs with existing Framework (e.g., Backbone, Angular) would be extremely helpful in terms of getting people started, as well as giving context for what Aurajs actually is and how it can be used.

---

Firstly, I'd like to share how I discovered Aurajs, because it relates to the rest of my points directly (and incidentally gives a decent back history of Aurajs):

It all started with finding Patterns For Large-Scale JavaScript Application Architecture (this article by everything I can tell was the genesis for Aurajs). Everything in this article really clicked with me and was easy to absorb since it was using language that I was already familiar with (when I found Aurajs, language was initially a stumbling block for me since Aurajs had switched up some of the language that was used in the article). Also, and unfortunately, for anyone finding this article today there are no links/mentions from that article to Aurajs, though Addy Osmani does mention at the bottom of the article that he's working 'on releasing a free boilerplate pack for this post when time permit'.

A bit later in time, Addy Osmani apparently gave a presentation in which he covers everything from the original article above and also gives what I assume is the first preview of Aurajs (which wasn't yet released) Large-scale JavaScript Application Architecture. This is a good resource because it helps tie the ideas from the original article to Aurajs. (something which doesn't existing on the Aurajs site/homepage/github currently)

So to summarize, I believe there is a large disconnect between what is well-explained in both the original article and the presentation slides, and what is currently presented on the Aurajs site/homepage/github (which to me is not very easy to follow or to glean much context from).

A bit of Googling around and seeing the number of people that have starred this project on Github leaves me with the impression that a lot of people are interested in Aurajs, but that Aurajs is too far over their head in many cases. I believe this could be changed if Aurajs communications/documentation does a better job of walking people through the really-big-picture architectural problems it is solving, as well as real examples of how Aurajs can tie into their current framework(s).

[addyosmani]

Thanks for your detailed feedback. It's really humbling to read that you've been keeping track of the large-scale JS architecture concepts over time and following the direction of where Aura has been going.

I take personal blame for the disconnect between the concepts in the original article and the current status of the project. Whilst Aura 0.9.x doesn't necessarily implement all of the same patterns from the article (permissions for example, which we found to be of less value than originally thought), I could tie in Aura to the article in a way that makes everything a little more clear. Perhaps a Large-scale JS application architecture V2.

I could probably cite how we went about solving particular problems (such as mediators) in Aura where we describe these patterns in the article so that developers have more context. There's definitely changes we can make to improve the disconnect.

[Saturate]

I agree with @CalebGilbert, I have had my trouble trying to connect RequireJS, Backbone and Aura together into my app. Some of the issues were my own fault, but there are things that could have used some examples or best practices.

To summarize what I have been dealing with I'll list a few points.

Lack of new examples

I had a hard time finding examples that just worked, the https://github.com/aurajs/examples was a good idea, but there were many issues and outdated grunt tasks. I created an Issue where I tried to list the things that were and are missing, but I think I'll just made a pull request to fix them.

I found Hull, they made some pretty nice things with AuraJS and that did help me quite a lot. Thumbs up for them.

Routing & different pages

When I started out I had some trouble working out how Aura would work with the Backbone router. It would be nice if this was explained with some examples. I found two possible solutions, where I always load the app via a viewport component that initializes the router:

• The router then loaded a page component that included the needed sub components.
• Having sub-views triggered by the rotuer that determined what components that had to be loaded.

I'm still not 100% sure that I am doing this the optimal way, and I feel there is a need for some guidance on this.

Component - Models, Colletions & Views

I had to think too much before finding out how to share a sandbox between the Models and Views in a Component. Complex components are lacking examples with Models, Collections and more views. You will eventually find out how to do this, but the lack of a best practice or an endorsed way of doing it made me wonder if I was doing it right, a example would speed up the learning.

How does this work with Grunt

How do I build the project. There are no good examples of this as the one provided does not work. I did set up my own Gruntfile. But we need an example of this.

Quick summarize of the summarize...

I really like the Aura way of doing things, and I am glad that I took my time getting to know it. But a improvement would be to remove the "Am I doing this the right way?" - factor.

@addyosmani Can I count on getting some feedback, if I make pull requests to the examples? Mostly the Backbone one.

[Florian-R]

I can't agree more with all the points stated by @Saturate.

I'm actually having a hard time sharing Backbone Models and Collections between components without having to rely on some sort of global or coupling between them, and sadly all exemples i can find are out of date (most of them where published when the project was still named Backbone-aura).

Maybe this repo and Aura docs aren't the best place to talk/show examples about these kinds of patterns, and a better place is needed by Aura community to discuss without polluting this repo?

[chirimoya]

+1

[addyosmani]

I just wanted to update the the thread to say that we would be more than happy to provide feedback on any and all PRs which attempt to improve the disconnect between the original article and Aura in its current form. Whether these are against examples, the project docs or tooling :)

Because Aura started off as a reference (example) implementation of the scalable architecture I originally talked about, the project has had a long history of trying to play catch-up in terms of examples and where patterns are being evolved. It remains a great reference, but we still have a lot of work to do to make this properly production ready on the documentation front.

Any help is always welcome :)