Ember.js Basics - Project Structure

One of the things that tripped me up when I first started using Ember.js was a lack of guidance in project structure. The early guides and samples placed all of the JavaScript into a few files and all of the templates were contained in script blocks inside of a single HTML file. To me, this seemed like a bit of a mess and it was very uncomfortable. Thankfully, as Ember has matured so have the tools around it. In this post, I’ll explain what the project “structure” looks like in a basic “out of the box” Ember.js application and then explore a few better approaches using build tools.

This is post #2 in a series on Ember.js. You can find the other posts here.

“Out of the box” structure

I use the word “structure” loosely here as there is very little structure imposed by the framework in terms of filenames or folder structure in the application. Essentially, if named and ordered properly, all of your JavaScript code could go in one file and many early samples did just that. Even now, the Ember Starter Kit comes with a structure that looks like this:

The guidance in TODO.txt states “Start writing your app in js/app.js.” and “Describe your application HTML in index.html.” This is fine for a small app, but it sure doesn’t scale well if we’re building ambitious web applications. In fact, you end up with an HTML file that looks like this:

All of these script blocks littered in the index.html file really started to bother me after a while and I had been wondering if there was another way. What I wanted to do was have each template exist in its own file and these would be referenced properly where needed by Ember. Thankfully, there’s a feature of Handlebars that allows for precompilation of templates and this is just what is needed to do what I wanted to do. It gets even better though. There are application workflows for Ember that make this process even easier. I’m going to briefly introduce the two options I have tried and show how they provide structure to the application building process. In future posts I will go into more detail on features offered by these tools.

Ember App Kit

Ember App Kit was created by Stefan Penner of the Ember.js team. It is billed as “A template for ambitious web applications” which, of course, fits quite well with the Ember tagline.

The main features of the Ember App Kit are: Asset compilation (including Handlebars, LESS/SASS, CoffeeScript, and minified JS and CSS), ES6 Module support, testing with QUnit and Karma, and dependency management using Bower.

The Ember App Kit is built around Grunt which is an amazing task runner for JS that was built with Node.js. I will describe the setup of many of the optional Grunt tasks in a future post. What we are mainly concerned at with Ember App Kit for now is the project structure inside of the app folder. Here’s what the top-level of the app folder looks like:

Note that I have expanded the templates folder. Each template inside of this folder is taking the place of one of those stray script blocks we had in the original approach. This is a much more structured approach! The application structure is described in detail in the Ember App Kit Getting Started guide.

Yeoman and the Ember generator

Yeoman is described by it’s maintainers as “modern workflows for modern webapps”. It consists of three separate tools that work together to help jumpstart and develop applications that enable best practices. Much like Ember App Kit, Yeoman uses Grunt as the build tool. It also uses Bower for client dependency management. The extra added pieces for Yeoman are Yo which is a scaffolding tool and one of the many generators maintained by the community. Using the Yo command line tool one can scaffold out an entire application from a generator. In our case, the generator we’ll take a look at is generator-ember.

When you run the Ember generator using Yo, you’ll get asked if you want to install Twitter Bootstrap for Sass. This is a nice touch since many developers are using Bootstrap and many Ember devs are using Sass. I’m much more of a Foundation fan so it would be nice to have a choice, but it’s easy enough to add later so no worries. Yeoman will scaffold out an Ember application and the Grunt tasks are pre-configured for Sass, minification, template precompilation, and LiveReload (which will automatically rebuild files and reload the browser any time you save a file). I’ll discuss the details of generator-ember in a future post.

Again, the most important thing to look at for now is the application structure generator-ember offers. Just like with Ember App Kit, there is an app folder. Inside of this, the structure looks like:

The app/scripts folder is where all of the JavaScript files for the app should go. There are folders for the major categories of files such as models, views, controllers, and routes. Also inside of app/ is a templates folder where you will store your Handlebars templates. Like Ember App Kit, all of these folders are configured to be watched and built by Grunt. Once again, this definitely adds much needed structure to an Ember application. The Ember generator also includes subgenerators for adding models, views, and controllers. You can read about these subgenerators on the generator-ember Github page. I’ll talk about them in more detail in a future post.

Summary

Ember.js does not impose a set structure for the application files in terms of folders and file names within a project. Thankfully, we have some great tools to help establish some best practices. Whether you choose Ember App Kit or generator-ember with Yeoman, I think it is easy to see how both of these approaches help facilitate easier project collaboration and maintenance. Try the different options before deciding on one to use for your project.

Contact

If you want to comment or reach out to me, the best place to do that is on Twitter @brentschooley. I can also be reached via email at bschooley@infragistics.com.