intro-to-ember-cli-node.md

Introduction To Node, NPM and Ember CLI

This guide is for developers who are new Node, NPM, and Ember CLI. This guide is designed to get you started with ember cli development and provide some general background info on what Node is and how it works with Ember CLI.

Overview

• What is Node?
• What is NPM?
• How do I setup my environment if I don't have node js or npm installed?
• I accidently installed something wrong how can I start over?
• How Ember CLI works with node and npm ecosystem
• ES6 and Modules

What is Node?

Node is a runtime environment for JavaScript. It allows you to write applications in JavaScript and still retain the ability to execute these programs in many different environments including:

• hosted server environment
• local development environment or personal computer
• in the web browser or other environments that execute JavaScript

There are currently two major variants and implmentations of the Node runtime.

Node JS and JavaScript I/O

Node JS (nodejs) is a well established implementation based on Google Chrome's V8 JavaScript runtime

JavaScript I/O (iojs) is a newer project that maintains compatibility with the existing Node projects and also strives to have a fast but predictable release cycle. It is also built on V8 but is designed to take advantage of the latest ECMA Script standards and features such as ES6 as soon as they are made available.

Ember CLI runs on both of these implementations.

For the rest of this guide I will use term "Node" to refer interchangeably to either Node JS (nodejs) or JavaScript I/O (iojs). While there are some subtle and important differences they are equivalent for our purposes.

What is NPM?

NPM stands for Node Package Manager. It provides a common system and infrastructure to package and share Node compatible JavaScript programs with others. Users familiar with Ruby and Ruby Gems, can think of npm as serving an analogous function that gems and Bundler serve the Ruby and Rails ecosystem. Only for JavaScript instead of Ruby based programs.

Ember CLI ships with many other third party packages that are distributed via NPM and is provided as an NPM package itslef

How do I setup my environment if I don't have node js or npm installed?

To make the best and most compatible use of Ember CLI it is strongly encouraged to install the latest version of either Node JS or JavaScript I/O. When you have the Node environment installed you will also find that npm will be all be installed on your system. You can then proceed install other dependencies with the npm install command.

npm install some-package-name

When you install a npm package the contents of the package including the executable JavaScript code is typically installed inside a node_modules folder on your computer. The location of this node_modules folder can vary depending on how your Node environement was configured and installed. Packages can be installed either globally for all users of your system or locally for your current user inside your local home directory.

A package is installed globally with the -g flag.

npm install -g some-package-name

Avoid use of sudo or Adminstrator privileges when installing packages

When configuring a Node environment or installing npm packages it is strongly recommended to avoid the use of sudo or root/Adminstrator privileges. Your experience of Ember CLI will work much more smoothly if everything is installed only with your local user permissions. When you use sudo or privileged permissions a lot of subtle conflicts can arise when doing future package installations or upgrades.

If you would like to install multiple versions and or flavors of Node you can use use:

NVM Node Version Manager or n

Once NVM or n is installed it is very convenient to switch versions or quickly install a newer version of Node if needed.

I accidently installed something wrong how can I start over?

Occasionally things can appear to go terribly wrong with your Node environment. Perhaps the environment was set up with the wrong user permissions. Or perhaps a previous version of Node was installed making it difficult or confusing to understand where packages are installed and how to update or upgrade packages.

When you get in this state you have a few choices:

1.) Install a clean environment and virtual machine on your system for doing Node development

2.) Manually patch or fix an existing environment (which may require root or sudo access)

3.) Completely remove Node and start over cleanly.

Below is a short series of steps of how you can remove exisiting Node binaries. Where Node related stuff is installed on a typical UNIX environment is listed below. Use these notes to completely remove every remnant of Node from your system.

cd /usr/local/lib

Delete any node and node_modules directories you find here.

cd /usr/local/include

Delete any node and node_modules directories you find here.

If you used HomeBrew to install Node

brew uninstall node

to remove Node, search your Home directory and local folders, and delete any node or node_modules you find.

cd /usr/local/bin

and delete any node executables you can find.

If you have additional problems you may have to remove other node bits with the following commands:

sudo rm /usr/local/bin/npm
sudo rm /usr/local/share/man/man1/node.1
sudo rm /usr/local/lib/dtrace/node.d
sudo rm -rf ~/.npm
sudo rm -rf ~/.node-gyp
sudo rm /opt/local/bin/node
sudo rm /opt/local/include/node
sudo rm -rf /opt/local/lib/node_modules

After completing the all of the above you should have completely removed node from your system.

You can use the following commands to double check that node is no longer installed

which node

which npm

How Ember CLI works with Node and NPM ecosystem

Ember CLI is designed to efficiently manage Ember JS projects. It can be used to to quickly generate brand new project skeletons and can scale to manage very large, multi-thousand file and complex projects.

Use npm to install Ember CLI

npm install -g ember-cli

This will install the latest version of Ember CLI in a global location. Once installed you can create a new Ember project anywhere on your computer by typing

ember new my-app

When run succesfully Ember CLI will create a bunch of files on your computer in the folder where you executed this command.

my-app
  ├── models
  ├── .bowerrc
  ├── .editorconfig
  ├── .ember-cli
  ├── .git
  ├── .gitignore
  ├── .jshintrc
  ├── .travis.yml
  ├── app
  ├── bower_components
  ├── bower.json
  ├── Brocfile.js
  ├── config
  ├── node_modules
  ├── package.json
  ├── public
  ├── README.md
  ├── testem.json
  ├── tests
  └── vendor

A few highlights

app

This folder contains all you Ember JS project code. It is organized with specific project conventions.

bower_components

Third pary Bower packages are installed here. Bower packages are reusable and sharable bits of project code for frontend development. They can range from CSS and UI toolkits like Bootstrap, Foundation, to external widgets, modules, and JavaScript libraries, or even other JavaScript frameworks and dependencies such as jQuery.

bower.json

A JSON file that declares all your bower and frontend project dependencies. You can completely delete the entire bower_components folder in your project and Ember CLI will be able to use the bower.json file to download all your bower dependencies from the internet.

node_modules

Third party npm dependencies are installed inside this folder. These can range from simple add-ons to various small Javascript utilities and modules that extend the core behaviors and features of Ember CLI.

package.json

A JSON file that declares all your npm and Ember CLI dependencies. You can completely delete the entire node_modules folder in your project and Ember CLI will be able to use the package.json file to download all your npm dependencies from the internet.

Brocfile.js

This file contains the Broccoli JS configuration for your project. Broccoli JS is an asset pipeline for your entire Ember CLI project. Among many other things with Broccoli you can move, rename, delete, merge, replace, minify and automatically manage your project source files. Broccoli uses many sub modules and dependencies to perform all these operations and many more programmatically. Broccoli serves many purposes within a project, including:

• Generating a tmp directory for project output
• Live reloading and updating and writing out the compiled assets whenever you modify a source file in your project
• Output compiled production code to a dist folder when you run a build command
• Concatenate and minify project source code for efficient export of project source
• Many other things...

tests

All project test cases are kept here including unit and integration tests. By default Ember CLI uses QUnit to execute your tests.

vendor

Place any custom libraries and dependencies in this folder. You can configure Broccoli to reference files in this folder which will be merged into your production as part of the build process. Additionally by default Broccoli will concatenate and merge all the dependencies from the bower_components and node_modules folders into the vendor folder when executing the build process.

config

Environmental configuration goes here.

ES6 and Modules

One of the notable features and advantages of Ember CLI is that it allows you to use ES6 and Module syntax while maintaining backwards compatibility with older web browsers. Ember CLI achieves this by using a process called "transpiling" when compiling and building your project from source.

Ember CLI ships with a customized resolver. The resolver is responsible for mapping namespaces and individual modules so to that in independent pieces of code have the correct visibility of other pieces of dependent code. You can use modules to cleanly organize your project along small units of code defined in individual files spread throughout the file system.

For example imagine you have following math functions you want to use throughout your project. You could define these in a special math.js file in your utils folder.

// app/utils/math.js
export function sum(x, y) {
  return x + y;
}
export var pi = 3.141593;

and then elsewhere easily import to other files and code where you want to use them.

import { sum, pi } from 'my-app/utils/math';

var total = sum(2, 2); // => 4