emberjs
Should Mirage be the back end of the tutorial?
I was just helping some newcomers go through the ember guides, and Mirage seems to be causing some potentially un-needed complexity. It boils down to two reasons:
- Developers who have come out of a "vanilla" JavaScript course like FreeCodeCamp have learned to look at their dev tools network tab for XHR debugging. In some cases they feel like they've been robbed of one of their key tools, and I tend to agree with them.
- Using mirage, or anything based around Pretender, is different from the way an app will end up consuming data in a "real" situation.
My proposed change (I'm volunteering if there's consensus that this is ok) is to replace mirage with use of http mocks and ember-cli.
I realize that when you end up deploying the app, ember-cli won't end up providing this data, but I propose that we handle that as a separate problem (i.e., providing a read-only "production" API for "guides projects" that anyone can use via heroku or something) in the interest of making things as simple and pure to official ember stuff as possible. Again, I'm volunteering to build said API in the interest of improving learning material for newcomers.
Finally, there's enough complexity involved with using ember and ember-data together straight from the start. Involving another addon leaves newcomers confused as to where the lines between these libraries are, and more importantly, the "usual stuff people use" vs the stuff that's included with the guides for convenience or happenstance.
Thanks for raising the issue. Its an interesting one. We'll bring it up for discussion at the next learning team meeting, and we'll update this issue on what we decide (+link to notes on the discussion).
Let me know if I can be of help on this issue. We have an issue on the backlog to make Mirage able to serve out of Ember CLI (from node), which would bring back the network tab. The next goal after that is to have Mirage read model definitions from Ember Data, if you happen to be using it.
If we had these features it might make the experience feel more like using Rails with SQLite out of the box. If it feels right I can do some recruitment to get these features in faster.
I've had seen an increase in success teaching ember (measured by post-workshop survey to measure depth and breadth of understanding) since I rewrote my curriculum to start with the simplest, purest and most basic teachable piece possible (HTML and data binding in application.hbs) first, and then very gradually layering things on.
- There's this ember-cli thing. You only need
ember newfor now (we'll explain more later) - Raw HTML in
application.hbs(note: I run into problems here with the welcome screen since we don't have this file by default anymore 😢 -- we runember g template application) - Create an application controller, and introduce the concept of a template's "context". Try some data binding
- Use handlebars-included and ember-included helpers like
ifandeach - Define your own helper
- Build unit tests around that helper
- Introduce the concept of a component, define a component
- Build integration tests for that component
- Introduce the router as a finite state machine, and routes as things that facilitate transitions between known states
- Build your first acceptance test
- etc...
Ember-data comes much later, and of course mirage would have to come after that (if at all).
The benefit of this approach is that we start with the smallest functional atom of an ember-cli ember app that's possible, and then explain as we introduce new concepts one-by-one.
As things stand now, beginners are left without an understanding of where the lines are between ember, ember-data and mirage, because they're all thrown at the reader at once. It feels very much like someone decided they wanted an example that they could deploy a "server-less" app (the vast majority of apps are not like this), and worked backwards.
This makes a lot of sense to me, especially if you consistently see confusion arise during teaching. I've also had to explain that Mirage is not Ember Data many times. It's a lot of abstraction all at the beginning.
Thanks for this feedback. Its useful to understand your experience teaching intro workshops and learn what has worked for you.
The reason we included mirage in the tutorial is...
- Mirage is very frequently used for acceptance testing in ember, (otherwise requiring a data setup/teardown infrastructure). I do think this an important technology to familiarize developers with.
- We desired to give tutorial followers an application that they could easily run locally without a deployment with server persistence.
We also wanted to follow a workflow that one might start an app with, and have that as a possible pattern for future work, though there are obviously other possible ways to do it that would be as effective.
We did talk about it some last week (will post minutes soon) at our learning meeting and will likely discuss again this week. I think there are some things we can do to more clearly address some of the concerns you mention without completely blowing up the tutorial as is. @locks mentioned contacting you this week to get more info. We'll leave this issue open as we work through ways to address
Thanks
Looking forward to doing whatever I can to make this more approachable for beginners. I'm not looking to "blow up" the existing guides, but as soon as I started hovering over beginners' shoulders as they started going through the example, the sticking points were very clear. A little simplification (introduce way fewer concepts in early steps) would go a long way.
Thanks, so given issue #1708 I propose we track this issue as finding possible alternatives to using Mirage, wether it be using a hosted service or other solution. Possibly also still using mirage but introducing it later in the tutorial with more care.
Discussed some in previous ember learn meeting. No set decisions made on a solution yet: https://github.com/emberjs/core-notes/blob/master/docs-team/2016-10/october-13.md#tutorial-back-end
It seems that the goal would be to serve JSON API out of the box, right? That would be most congruent with Ember Data's default adapter/serializer, and would be one less thing to think about.
I've been working on an internal project tentatively named ember-cli-fortune, which just adds ember-cli integration with Fortune.js + Fortune JSON API, and it's used in some demo projects. What it does:
- Statically analyzes Ember Data models and generates a database schema based on that.
- Adds server middleware that responds to everything in JSON API 1.0, even things in the spec that Ember Data doesn't support yet.
- Uses an in-memory database that gets populated by fixtures, all updates persist until the server is restarted. This can be configured to use a production database such as Postgres or MongoDB, since Fortune.js itself is a database abstraction layer.
- For testing, the server runs in the client, with Pretender integration built-in (!) this works as long as no Node.js-only packages are used and no server-only code is relied upon. Alternatively the dev server can be re-used here as well, which would lift the client-only restrictions and be able to see the network requests while testing.
The idea is that one can simply set up Ember Data models, install ember-cli-fortune, add some initial data, and be done with it.
It's not released yet, since I've had no time yet to document it and make a website with guides for it, though I don't expect that there will need to be much of a guide since it's expected to be plug and play. The source code isn't even long at all, ~300 LOC, it's mostly glue code between the AST parser Acorn, Pretender, Ember, and Fortune. Without Pretender it would be much less code.
If there is interest I'm open to discuss this as an alternative to HTTP mocks and/or Mirage.
Quite a lot:
- It is written for Node.js first, with performance in mind.
- Since it's running a server, one can inspect all of the network traffic.
- One can re-use the same server for development and production by swapping the database.
- All of the optional, non-trivial JSON API features come for free. For example, one does not need to implement sparse fieldsets, include, sorting, pagination, filtering, it's already built-in.
- One does not need to define models separately from Ember Data, which are usually just duplicated anyways.
- Zero API (except test helpers), which makes it very friendly for beginners. It works without having to set it up, beyond supplying missing information such as
attr()without a type.
Has consideration been given to a hosted solution, or a "one click deploy" back end on something like heroku?
The idea here is it would be a back end that "just works" and is nearly 100% set up for the learner, so that additional server-side complexity/setup (mirage, http mocks, fortune, etc...) doesn't compete with core ember concepts for attention and learning bandwidth.
It would make sense that this would be written in JS so that it's easy for the community to maintain. Maybe fortune would fit well here too?
Updated the title of the issue to focus the discussion away from http mocks
Has consideration been given to a hosted solution, or a "one click deploy" back end on something like heroku?
Yes, you can find it in core-notes.
Has consideration been given to a hosted solution, or a "one click deploy" back end on something like heroku?
I have thought about setting up some managed application service for Fortune.js, but I wouldn't have the business skills or money to keep it running.
The idea here is it would be a back end that "just works" and is nearly 100% set up for the learner, so that additional server-side complexity/setup (mirage, http mocks, fortune, etc...) doesn't compete with core ember concepts for attention and learning bandwidth.
Yeah, that would be a goal of ember-cli-fortune to require no effort to use it, and that it just works in the background.
It would make sense that this would be written in JS so that it's easy for the community to maintain. Maybe fortune would fit well here too?
Sure, it's 100% JS. Also, since the ember-cli integration is fairly concise, it wouldn't be too much of a burden.
Just want to reiterate that I am 100% on board with whatever's easiest and best for beginners. Let me know if you need anything from me.
Yes, you can find it in core-notes.
After reading through the whole collection of notes a few times, here's the most meaningful stuff I could find.
- Recent discussion in response to this issue being opened.
- Decision to go with mirage/TDD from about a year ago, but sadly not a lot of information concerning the basis of this decision.
I can't really glean from the notes whether we're rehashing a discussion that's been had, or whether a "deploy it yourself to heroku" 100% complete API (in place of having to learn mirage and ember simultaneously) is new territory or not.
[tracking comment]
Local:
- express.js
- mirage
- ???
Hosts:
- https://zeit.co/now
- http://heroku.com/
- https://runkit.com/home
APIs:
- https://firebase.google.com/
- public
- GitHub
- ???
I can't really glean from the notes whether we're rehashing a discussion that's been had, or whether a "deploy it yourself to heroku" 100% complete API (in place of having to learn mirage and ember simultaneously) is new territory or not. @mike-north
We did have these discussions, it's probably in Slack logs then :
I think this is the gist of it:
- We host
Too expensive.
- Self-hosted / Local
Instead of having to learn mirage, you have to learn how to setup a whole backend. Plus the account creation for the hosting service.
- Firebase-style
Needs custom adapter if using with Ember Data. Needs account creation.
- Public APIs
Rate limiting. One workshop was blacklisted because they were making the calls from the same IP and hadn't remembered to warn the API owner.
- We host: Too expensive.
Based on what? I know node doesn't necessarily scale as well as Elixir/Phoenix, but I've been able to workshop with ~300 students concurrently hitting an API at the same time, using heroku's $7/month dynos
- Self-hosted / Local: Too burdensome
With heroku this boils down to a one-button deploy after account creation. in your app.json it's possible to specify addons (i.e., postgres) and run a postinstall to setup the initial data in the DB. If we're weighing the conceptual burden of managing mirage against creating a heroku account and clicking a button, I'm not sure if there's much of a contest.
- Firebase-style: Too complicated
Agree, and it also has the disadvantage of not being an overly common use case for managing persisted state in ember apps
- Public APIs: Too error-prone
Agree. I am often burned by the GitHub API, and the hoops to jump through to get an OAuth token are prohibitively complicated
@mike-north and whomever else cares, I wrote a json-api mock server for ember-data https://github.com/runspired/json-api-mock-server/, and am slowly growing it to support more things (needs fixtures supports, needs documentation on serializer customization because non-json-api payloads are supported so long as you supply a serializer and schema))
I've also been debating setting up a heroku instance running this with some common model scenarios to use as mock data in ember-twiddle
A refined server that people new to ember can just point to, would reduce the number of simultaneous things they need learn/do during the tutorial quite nicely.
@mike-north not necessarily, if the tutorial has an addon, that addon could mount my project with the required models. Extra advantage is that in the console you get pretty notifications about the request :)
I definitely understand some of the pains and appreciate @mike-north sharing how he teaches (wish I had such training when I started!). There may be ways to improve how mirage is introduced/used in the guides and there are definitely pain points (such as debugging flows) but I'd like to throw in a counterexample to the ongoing discussion.
We recently had a developer go through the Guides as her first exposure to Ember.js. After completing them, we were pleasantly surprised to see her not only able to understand the various parts of our production app and be able to contribute, but also able to read and understand and even write her own acceptance tests with the mirage setup we had with no further instruction from any existing developers.
This lined up with @toddjordan's goal of:
- Mirage is very frequently used for acceptance testing in ember, (otherwise requiring a data setup/teardown infrastructure). I do think this an important technology to familiarize developers with.
- Mirage is very frequently used for acceptance testing in ember, (otherwise requiring a data setup/teardown infrastructure).
Do we have any data that indicates how widely-used mirage is, relative to something that's almost ubiquitous (i.e, ember-data)? This doesn't quite jive with what I've seen in the wild (I tend to see more Pretender than Mirage tbh). Maybe other people have hard data that I don't have?
I do think this an important technology to familiarize developers with.
I don't think anyone's saying that mirage is unimportant or not worth familiarizing developers with.
@SaladFork's new developer would likely have had similar success if the learning path had led from "core ember concepts" to a separate learning trail for any relevant addons. She's representative of the group of people who currently make it through the guides in their current form.
My efforts are aimed at broadening our user base, and allowing people like her to continue to have success, while opening the door to others who are currently getting stuck right at the start, before they can even get off the ground.
Regardless of final approach, I think a tutorial addon (supplying data) and baking a standard mock setup into twiddle for use in twiddle's would be amazing for helping beginners / tinkerers / bug reporters
@runspired I love this idea, especially for Twiddle. In the event that a hosted solution requires more effort and is a ways out, we could use Mirage to do this today with an addon that (1) includes Mirage as a dependency and (2) predefines several models w/relationships and sets up their endpoints (user, post, comments). We should be able to build that today without much trouble.
Do we have any data that indicates how widely-used mirage is, relative to something that's almost ubiquitous (i.e, ember-data)? This doesn't quite jive with what I've seen in the wild (I tend to see more Pretender than Mirage tbh). Maybe other people have hard data that I don't have?
@mike-north If you go by npm downloads and github stars/forks then mirage is more popular than pretender. Its not a real fair comparison though, as they have different jobs, and mirage is actually built using pretender. If you are developing an acceptance testing suite, then mirage has more for you to organize/manage your data. Pretender is great for adhoc testing integration tests (though I'm not saying it can't, shouldn't, or is not used for acceptance).
The ember-data to mirage comparison is also not real fair, since more people probably don't acceptance test than do. While ember data is seen as part of the ember core framework for data access (it comes out of the box with CLI, released on the website, has a core team) You can certainly do acceptance tests without mirage using a real data persistence, or alternative stubbing technologies, but mirage is what I've observed, based on teams, podcasts, literature, downloads, etc as the way a lot of ember teams tend to solve it.
But again, I am not arguing that nothing should be done. I think we can push introducing mirage until further along, and I think it worth looking at solutions for the tutorial that can give users an example of data access without having to learn or mess with new concepts, allowing them to focus on ember-data basics.
My efforts are aimed at broadening our user base, and allowing people like her to continue to have success, while opening the door to others who are currently getting stuck right at the start, before they can even get off the ground.
Agree ❤️, and thanks for contributing to this discussion. Its certainly clear that there are different personas using the guides, and providing useful content to both is important.