There are many different ways to structure an app built using web technologies, and making organizational decisions can take time. Fortunately, when working with a command line tool such as Ember CLI, the application structure is determined for you. This makes it easy to quickly scaffold new resources or templates and automate repetitive tasks, leaving you with more time to focus on improving your application. This article covers installing Ember CLI and using it to create a basic app skeleton for you to build on top of.
What will we create?
We are going to create a simple MVC app called
world-clock, which will display the local time, update it every second, and allow you to choose additional timezones to display. You can view a demo of the app, and check out the complete source code on Github.
Installing our toolset
To install Ember/Ember CLI, you need to follow the instructions in this section.
Note: You'll be using the command line a lot in this series of articles. If you are not sure how to access a command line, don't worry — this set of instructions explains it. Every operating system has a command line tool by default.
- Handlebars for writing application templates. Ember includes this automatically.
- LocalForage for storing and managing offline data. We'll show how to install this later on.
- Moment Timezone to provide a list of available timezones, and allow us to easily format them in a more readable way. We'll look at how to install this later on as well.
Follow these steps to get started:
- You need to have Git installed to use some of Ember's functionality. Install it now.
- Ember CLI requires Node.js. Go here to download and install Node before continuing to the next steps.
- Open your Terminal or Command Prompt.
Install Ember CLI using the node package manager (NPM):
npm install -g ember-cli
To confirm that your installation is successful, type:
Note: If you get an error about permissions, or EACCESS and are on Linux, Mac OS X, or another flavor of Unix, you may have issues with the ownership of your
.npm directory. One solution is to use the
chown command on your command line, like so, substituting the path to your
sudo chown -R $USER /Users/[YOUR USER NAME]/.npm.
Creating your basic app skeleton
Though we are deferring a fair amount of responsibility to Ember CLI, it is still important to familiarize yourself with the way these projects are set up. Let's get started by creating a new project. We will generate the basic app skeleton and serve it locally to be viewed in the browser.
- The first step is to think up a short, memorable name for your project — in this case we'll use
From your terminal or command line, navigate to a memorable directory on your hard drive where you want to create your app:
Create your new project with the following command:
ember new world-clock
Ember will generate a new directory containing your project in the current directory. This folder contains all the tools and resources needed for a basic Ember application. Though it may seem like a lot to keep track of, you'll find this structure provides great flexibility when you want to add more functionality to your application.
cdinto your project's root directory and have a look around:
cd world-clock ls # use the dir command instead on Windows
Starting your app
As you edit your application files, Ember CLI will automatically compile and concatenate your scripts for you. Ember CLI also provides a development server that allows you to view and debug your changes as you make them. To start your app:
From the root of your project, run the following command:
- If you get the message Run 'bower install' to install missing dependencies, run the command
bower installin your command line/terminal then try
- Another message that can appear is 'ENOGIT git is not installed or not in the PATH' — this means that Git is not available; install Git then try again.
- Open your browser and navigate to http://localhost:4200/. You should see a page with a single heading, "Welcome to Ember.js"
Ember app structure
You'll learn more about the Ember app structure as you work through subsequent sections of this guide, but there are a few important files and folders worth pointing out now.
Have a look at the directory structure again using
dir. (or view it in a file explorer window if you like.)
- You'll notice a
distdirectory in the application structure. Whenever Ember CLI builds your application, it places the final production-ready files of your app in this directory. You should never edit any of these files directly, as they will be overwritten any time Ember CLI builds your files.
- You'll also see an
appdirectory: this is where you make direct changes to your application's code. The contents of this directory are built then copied into
distwhen you run
- There is also a
publicdirectory, where you put raw assets such as fonts and images that don't require any building. This is copied over to the
distdirectory unchanged when you run
- There's a
package.jsonfile in your root directory, which contains configuration information, such as the name of the app, and what dependencies it has.
- In your root directory you'll also find ember-cli-build.js, which contains details of all the 3rd party libraries, assets, etc. that need to be included when your app is built. Ember CLI asset compilation is based on the broccoli asset pipeline tool.
Note: A more detailed explanation of your app structure can be found in the Ember documentation.
We now have a fresh new application running locally that we can begin working with. Next, we'll demonstrate how to add a route to your app that displays content from a corresponding template.