sambiopic

I'm Director of Developer Relations and a Google Developer Expert for Angular and Web Technologies. I believe anyone who wants to learn to code should be able to learn code and I love teaching. When I'm not coding or writing, you'll find me outside hiking or camping in the beautiful Pacific Northwest.

Director of Developer Relations

Sam Julien

Auth0 has a new SDK for securing single page applications with industry best practices.


We are excited to announce the release of our new JavaScript SDK for Single Page Applications (SPAs) called [auth0-spa-js](https://auth0.com/docs/libraries/auth0-spa-js).

## Why a New SDK?
The [`auth0.js`](https://github.com/auth0/auth0.js) library has been our default browser-based SDK for the last few years and has been a key part of our product and success. It has over 100K+ weekly downloads and is used by almost every Auth0 customer in one way or the other.

Over this time, we have developed a large set of capabilities in the core product. As the platform has moved forward, `auth0.js` has grown in size and capabilities. While `auth0.js` is an extremely powerful SDK that can handle a large number of different scenarios, this versatility comes at a price.

We went back to the drawing board and we re-imagined how a web platform SDK should work for the most common scenarios developers will be implementing. This new SDK:

- integrates with [Universal Login](https://auth0.com/docs/universal-login), our flagship login experience
- is much easier to integrate into Single Page Apps and requires less code
- abstracts the developer from standards and protocols
- frees the developer from having to specify the grant or other protocol details, manage token expiration and renewal, or store and cache tokens
- follows industry and service best practices and protects developers from security pitfalls
- weights around 7kb minified and gzipped

We're excited about these changes and hope our customers and [developer community](https://community.auth0.com/) find this new SDK easy to use yet still powerful and secure.

<include src="TweetQuote" quoteText=".@auth0 has a new SDK to keep SPAs secure called auth0-spa-js. Check it out!"/>

## When to Use `auth0-spa-js` (and When Not to)
The new SDK is designed for use in SPAs to keep them secured using industry best practices.

The OAuth2 working group has published a new general [best current practices document](https://tools.ietf.org/html/draft-ietf-oauth-security-topics-11) for using OAuth2 to invoke APIs from Single Page Applications. The recommendation is now to use the authorization code grant with Proof Key for Code Exchange (PKCE), as opposed to using the implicit grant as described in the original OAuth2 spec. You can find more details in [this blog post from our Principal Architect Vittorio Bertocci](https://auth0.com/blog/oauth2-implicit-grant-and-spa/).

This new JavaScript SDK implements the authorization code grant with PKCE for authentication, so by using this new library, you will be following the latest industry best practices when it comes to security in Single Page Applications.

Don't worry, we will not be discontinuing support of `auth0.js`. In fact, if you still use embedded login or need to call the [management API](https://auth0.com/docs/api/info#management-api-v2) or [authentication API](https://auth0.com/docs/api/info#authentication-api), you'll want to stick with `auth0.js`. We encourage you to switch to `auth0-spa-js` if you're using Universal Login in a SPA.

![Auth0's Lightweight Universal Login modal view](https://images.ctfassets.net/23aumh6u8s0i/54lZ5srDBAM0dqWSRkdxXk/f4260dcf2af6e7b5b4a52c62769e0745/lightweight-login)

## How to Use Auth0 SPA JS SDK
So how do you start using the new SDK? Here are some steps for vanilla JavaScript that can then be applied to the framework of your choice.

### Installation
To use the new SDK, first install it from npm:

```bash
npm install @auth0/auth0-spa-js
```

Alternatively, you can include it in your project using our CDN:

    
    <script src="https://cdn.auth0.com/js/auth0-spa-js/1.0/auth0-spa-js.production.js"></script>
     

### Create the client
Once `auth0-spa-js` is added to your project, you'll need to create an instance of the Auth0 client in your application. Ideally, you should have only one instance of the client. Do this before rendering or initializing your application.

You can do this using async/await:

```javascript
//with async/await
const auth0 = await createAuth0Client({
  domain: '<AUTH0_DOMAIN>',
  client_id: '<AUTH0_CLIENT_ID>'
});
```

Or with promises:

```javascript
//with promises
createAuth0Client({
  domain: '<AUTH0_DOMAIN>',
  client_id: '<AUTH0_CLIENT_ID>'
}).then(auth0 => {
  //...
});
```

### Logging in
Adding the ability to log in to your application is easy. Given the following button:

    
    <button id="login">Click to Log In</button>
    

You can add a click handler and then call the [`loginWithRedirect()`](https://auth0.github.io/auth0-spa-js/classes/auth0client.html#loginwithredirect) method:

```javascript
document.getElementById('login').addEventListener('click', () => {
  return auth0.loginWithRedirect();
});
```

Once the user is redirected back to the app after authenticating with Auth0, your app will need to call [`handleRedirectCallback()`](https://auth0.github.io/auth0-spa-js/classes/auth0client.html#handleredirectcallback): 

```javascript
await auth0.handleRedirectCallback();
```

This is what parses the result from Auth0, stores the tokens, and sets up the session. You'll then be able to get the user or token as needed:

```javascript
const user = await auth0.getUser();
const token = await auth0.getTokenSilently();
```

### Calling an API
You can also use the SDK to silently get a token and then use that token in a call to an API.

Given the following button:

    
    <button id="call-api">Call an API</button>
    

You'll add a click handler, call [`getTokenSilently()`](https://auth0.github.io/auth0-spa-js/classes/auth0client.html#gettokensilently), and then use the returned token in your API call.

Here it is with async/await:

```javascript
//with async/await
document.getElementById('call-api').addEventListener('click', async () => {
  const accessToken = await auth0.getTokenSilently();
  const result = await fetch('https://myapi.com', {
    method: 'GET',
    headers: {
      Authorization: `Bearer ${accessToken}`
    }
  });
  const data = await result.json();
  console.log(data);
});
```

And with promises:

```javascript
//with promises
document.getElementById('call-api').addEventListener('click', () => {
  auth0
    .getTokenSilently()
    .then(accessToken =>
      fetch('https://myapi.com', {
        method: 'GET',
        headers: {
          Authorization: `Bearer ${accessToken}`
        }
      })
    )
    .then(result => result.json())
    .then(data => {
      console.log(data);
    });
});
```

If there's a valid token stored, `getTokenSilently` will return it. Otherwise, it opens an iframe with the `/authorize` URL using the parameters provided as arguments and returns the token.

### Logging out
Finally, logging out of your application is a matter of adding an event handler to your log out button and then calling Auth0's [`logout()`](https://auth0.github.io/auth0-spa-js/classes/auth0client.html#logout) method.

Here's the button:

    
    <button id="logout">Log Out</button>
    

And here is the click handler and the call to `logout()`:

```javascript
document.getElementById('logout').addEventListener('click', () => {
  auth0.logout();
});
```

## Behind the Curtain
Since many developers (myself included) are wary of black boxes, let's take a moment to look at the protocols behind the new SDK.

While our intent is to abstract away all the implementation details in this new SDK so you don't need to worry about them, identity geeks will be pleased to know that `auth0-spa-js` is compliant with OAuth 2.0 specifications:

* `loginWithRedirect` uses [authorization code with PKCE](https://tools.ietf.org/html/rfc7636)
* `loginWithPopup` uses authorization code with PKCE + [`web_message`](https://tools.ietf.org/html/draft-sakimura-oauth-wmrm-00)
* `getTokenSilently` uses authorization code with PKCE + `web_message`

Auth0 takes our commitment to security best practices seriously. Luckily, we do all the heavy lifting so you don't have to!

## Where to Go Next
To learn more about using `auth0-spa-js`, check out the Auth0 Single Page Applications [SDK introduction documentation](https://auth0.com/docs/libraries/auth0-spa-js), [repository](https://github.com/auth0/auth0-spa-js), and [the SDK's full documentation](https://auth0.github.io/auth0-spa-js/index.html). There are also [Quickstarts](https://auth0.com/docs/quickstarts) that will walk you through integration step-by-step for popular front-end frameworks like React and Angular. We hope you're as excited about this new SDK as we are, and look forward to hearing feedback from the [developer community](https://community.auth0.com/)!

<include src="asides/AboutAuth0" />



Announcing the General Availability of the Auth0 SPA JS SDK

kapehe-jorgenson

Kapehe is an R&D Content Engineer for Auth0 with a passion for learning and teaching. With her primary focus on ReactJS and JavaScript, she is impressed with what code can create for the web. Technology and web development are constantly evolving and naturally bring that need for continual learning. She enjoys writing tutorials, hosting local meetups, and learning with others to expand coding knowledge.

R&D Content Engineer

Kapehe Jorgenson

Learn how to build and authenticate an EmberJS 3 Single Page Application

Build and Authenticate an EmberJS 3 Application

1097492785caf9ffeebffeb624202d8f?s=200 avatar

1097492785caf9ffeebffeb624202d8f?s=200

Prosper is a great speaker, community leader, open source hacker, technical consultant, and a fervent Developer Advocate. He is a full-stack software engineer who has worked on biometric, health and developer tools. Prosper recently co-founded a startup called Eden that’s focused on improving the quality of lives in Nigeria and currently leads the engineering team. He also co-founded forloop, the largest developer community in Africa.

Former Auth0 Employee

Prosper Otemuyiwa

Learn how to quickly build ambitious apps with EmberJS 2 and add authentication the right way.

EmberJS Authentication Tutorial

001c9ddc5ceb9829b6aaf24f5d28502a

I am software developer with a keen interest in open-source technologies, Linux, and native development. I've worked on many different platforms Android, iOS, Win32, Linux, FreeRTOS, the Web, and others. I've gone through the whole stack and I enjoy learning and using the latest technologies. I now work as a full-stack developer at Auth0.

Senior Engineer

Sebastian Peyrott

You asked? We listened! Benchmark series is back with even more frameworks and metrics!

More Benchmarks: Virtual DOM vs Angular 1 & 2 vs Others

We have updated our latest benchmark article to use array keys and see what happens!

Take a look at competing DOM manipulation libraries and find out which one is faster with a performance benchmark!



<div class="alert alert-info alert-icon">
  <i class="icon-budicon-500"></i>
  <strong>Visit <a href="/blog/build-and-authenticate-an-emberjs-3-application/">Build and Authenticate an EmberJS 3 Application</a> to read our most up-to-date tutorial.</strong>
</div>

In this post we will explore three technologies to build dynamic DOMs. We will also run benchmarks and find out which one is faster. At the end we will share with you why we choose one of them for our projects. Read on!

-----

## Introduction
There are many [Document Object Model (DOM)](https://developer.mozilla.org/en-US/docs/Web/API/Document_Object_Model) manipulation frameworks and libraries. Among these, three have been the center of the attention due to their focus on performance: [React.js](https://facebook.github.io/react/), [Ember.js](http://emberjs.com/) and, more recently, [Incremental DOM](https://github.com/google/incremental-dom). While React and Ember handle much more than just DOM building/update, Incremental DOM focuses only on building DOM trees and allowing dynamic updates. We will now explore these libraries and find out which one is faster.

![DOM tree](https://images.ctfassets.net/23aumh6u8s0i/6oEcAYeaWwsrEMXh7SVwil/6dfc83c50b2ef5a51ea37fd7217dd3c4/domtree)

Before getting into the details, if you are not a web developer, you might be asking yourself what exactly *DOM manipulation* is. Web sites are built as trees of different elements. These elements are defined in the HTML spec. By composing these elements a developer can create arbitrarily complex web sites. The DOM is the abstract representation of a website as a tree of HTML elements. It is defined by a [W3C spec](http://www.w3.org/TR/DOM-Level-2-Core/introduction.html) and implemented by all major browsers.

Besides aiding in binding the data model to the view, these libraries help in doing updates to DOM **efficiently**. A series of updates that would normally be performed by manually issuing a series of DOM API calls can be automatically batched into a single call (or a reduced set of calls). For instance, suppose the logic behind an update to the site requires that you:

1. Remove an element
2. Add a new element
3. Change a property of the added element

Directly issuing DOM API calls for doing changes such as these will result in intermediate repaints and reflows of the content. These are expensive operations. By working on a virtual model these steps can be flattened into one.

### Templates
Templates are a popular way of building DOM trees. With templates a developer can use a specific template syntax that tells a template compiler how to turn that into a DOM tree (or HTML document). Templates can look like an extension of HTML, or be completely different.

Not every library in this post favors the use of templates. For instance, React favors the use of JSX: an extension of Javascript (in the form of a precompiler) that allows easy insertion of HTML-like snippets in Javascript code. Ember, on the other hand, favors the use of [Handlebars](http://guides.emberjs.com/v1.10.0/templates/handlebars-basics/), a template language.

Incremental DOM does not favor any particular template engine. However, being a Google sponsored project, a [Closure templates](https://github.com/google/closure-templates/) backend is being developed. Incremental DOM can also be used with [superviews.js](https://github.com/davidjamesstone/superviews.js), [starplate](https://github.com/littlstar/starplate) and even [JSX](https://github.com/babel-plugins/babel-plugin-incremental-dom).

## React.js' Virtual DOM
*Virtual DOM* is the name React developers gave to their DOM manipulation engine. *Virtual DOM* provides a series of Javascript calls that tell the library how to build an **in-memory DOM tree** and how to update it when data bound to it changes. The central piece of Virtual DOM is its **smart diffing algorithm**: once the differences in the model have been mapped to the in-memory copy of the DOM, the algorithm finds the **minimum number of operations required to update the real DOM**. This results in two copies of the in-memory DOM being present during the diffing process.

![React.js' Virtual DOM](https://images.ctfassets.net/23aumh6u8s0i/oM52qwUuOVavnUKS8fStA/ebb35ef8e24191bbeb4cea8efca1aaad/reactdom)

> Disclaimer: some of the graphics in this post are based on the ones found in this [excellent post explaining DOM manipulation libraries](http://teropa.info/blog/2015/03/02/change-and-its-detection-in-javascript-frameworks.html)

#### Pros
- Fast and efficient "diffing" algorithm
- Multiple frontends (JSX, hyperscript)
- Lightweight enough to run on mobile devices
- Lots of traction and mindshare
- Can be used without React (i.e. as an independent engine)

#### Cons
- Full in-memory copy of the DOM (higher memory use)
- No differentiation between static and dynamic elements \*

\* React has [recently implemented](https://github.com/facebook/react/issues/3226) functionality that detects constants and reduces the number of elements that need to be checked for updates.

## Ember.js' Glimmer
*Glimmer* is the name for Ember.js' latest rendering engine. Glimmer is the result of Ember's developers trying to integrate the benefits of React's Virtual DOM engine into Ember while maintaining API compatibility. Do note that Glimmer is a full rewrite of Ember's rendering engine and in no way shares code with Virtual DOM.

Glimmer differentiates between **static** and **dynamic** components, thus reducing the number of elements that need to be checked when looking for changes. This differentiation can be achieved thanks to the expressiveness of Handlerbar's templates.

Another key difference between Glimmer and other solutions lies in the way nodes are stored and compared. Glimmer stores nodes as simple stream-like objects (that is, simple queues of values) rather than full-fledged DOM-like nodes. To find out whether a real DOM node needs updating, the final value of a Glimmer node is compared to the last known real DOM value. If the value has not changed, no further actions are taken.

![Ember.js' Glimmer](https://images.ctfassets.net/23aumh6u8s0i/7lAoKFzu3mk96HBlvgU9Jb/a77719062e194ee06fbb14d4260fa2a3/emberdom4)

#### Pros
- Fast and efficient diffing algorithm
- Differentiation between static and dynamic elements
- 100% compatible with Ember's API (you get the benefits without major updates to your existing code)
- Lightweight in-memory representation of the DOM

#### Cons
- Meant to be used only in Ember
- Only one frontend available

## Incremental DOM
Incremental DOM tries to bring a simpler approach to the table than the alternatives: rather than keeping a full in-memory representation of the DOM, or keeping a tree of lightweight elements, Incremental DOM uses the **real DOM** to find differences when data changes. You might be asking yourself why, if this is simpler, it hasn't been the solution picked by other libraries all along. Simple: it results in a **tradeoff between speed and memory**. Incremental DOM, by removing the additional copy of the DOM, results in **reduced memory usage**. In practice this also results in **reduced speed** while looking for differences. The reduced memory usage is key for mobile or other memory constrained devices. Read [our article on Incremental DOM](https://auth0.com/blog/2015/10/23/incremental-dom/) for more information on this.

![Incremental DOM](https://images.ctfassets.net/23aumh6u8s0i/10r0ke7cIPEQoAPjxzuVdS/0fb7fe4a20ce7cd1ca7c146b82bf2577/idom)

#### Pros
- Reduced memory usage
- Simple API
- Easily integrates with many frontends and frameworks (meant as a template engine backend from the beginning)

#### Cons
- Not as fast as other libraries (this is arguable, see the benchmarks below)
- Less mindshare and community use

## Benchmarks!
For our benchmarks we have picked the [dbmonster test app](https://github.com/wycats/dbmonster) as [shown in this post](http://blog.nparashuram.com/2015/03/performance-comparison-on-javascript.html). `dbmonster` is a simple application that simulates the load caused by an application updating tons of rows in a table that shows the activity of different simulated database clusters. This application was originally developed to test Ember's performance. We have run this test using the latest versions of React, Ember 1.x and 2.x (both use Glimmer) and Incremental DOM. All tests were run using Chromium 46 on Linux (Core i5-5200U CPU). Five passes were performed for each test and then averaged.

![Major GC time losses](https://images.ctfassets.net/23aumh6u8s0i/2iFPuzIou6JUyGYeztDEJB/6c9ad47c00d5181722b91eb7c972314d/MajorGC)
![Minor GC time losses](https://images.ctfassets.net/23aumh6u8s0i/3bLUVwYmUBOG2hdkjZhFvV/31a19b6ca2ab336b9b30a427b2827c2e/MinorGC)

In these charts the time spent during major and minor GC collections can be seen. As expected, Incremental DOM is much more efficient in this area. React remains a close second for major collections but falls way behind Incremental DOM in minor collections. It is interesting to note how much Ember has progressed from version 1 to version 2 in this area.

![Layout and Paint time losses](https://images.ctfassets.net/23aumh6u8s0i/3JMcJsuB8PCbu65nL0uurq/2973f5ab3d915eb360c77467693d4dce/LayoutAndPaint)

Ember shines in this case: time spent doing layout operations and then performing the actual paint to the screen. Incremental DOM trades memory usage for speed so it is expected in this case to see it behind the alternatives. React stays close to Ember and appears balanced so far.

![Dropped frame counts](https://images.ctfassets.net/23aumh6u8s0i/5H6504nEFMusXwSbnIsNHe/7f30a178d740d49cac78dbcadb4e1c0e/droppedFrameCount)

This charts shows the number of frames that Chrome decided to drop (i.e. to stop drawing) due to long pauses. Dropped frames result in lower framerates and visible pauses. In this case, Incremental DOM shines again. Less time spent in GC pauses means more time is available to draw frames. React, Ember 1 and Ember 2 all remain close behind Incremental DOM.

One important thing that is not shown in the charts: the subjective feeling of the browser when using it. Incremental DOM seemed much more responsive. By taking a look at the collected data, Incremental DOM appears to be making less JavaScript calls than the alternatives. It should be noted that while Incremental DOM is just a library to dynamically update the DOM, both React and Ember handle much more: events, data passing, etc. A proper test of Virtual DOM without React should be interesting.

Take a look at the [full](https://github.com/auth0/blog-dombench/blob/master/article_results/data.json) and [summarized](https://github.com/auth0/blog-dombench/blob/master/article_results/results.csv) results.

[Get the full code](https://github.com/auth0/blog-dombench) for the tests. To run the tests, you will need ChromeDriver and all node.js dependencies for the test driver (json2csv, browser-perf). Once all dependencies are installed, run `node run-benchmarks.js`. Once the tests are done, results can be found in `data.json` (full) and `results.csv` (summarized).

## Aside: React.js use at Auth0
At Auth0 we are constantly evaluating the best technologies for our platform. For the development of our [Passwordless Lock library](https://github.com/auth0/lock-passwordless/) we picked React.js. React is an excellent choice because of its unopinionated integration model and its declarative way of developing components. On other fronts, React remains a well balanced approach between speed, memory usage, ease of integration and good documentation/support.

<a href="https://auth0.com/signup" data-amp-replace="CLIENT_ID" data-amp-addparams="anonId=CLIENT_ID(cid-scope-cookie-fallback-name)">Sign-up</a> and start using our Passwordless Lock library in a minute! Or take a look at the [code](https://github.com/auth0/lock-passwordless/).

## Conclusion
Virtual DOM, Glimmer and Incremental DOM are all excellent options for handling dynamic DOM updates. React's mindshare and ease of integration make it a no brainer for many projects. Increased memory use can be a problem in memory constrained devices for big websites. This problem, however, is getting smaller everyday as mobile devices carry more and more memory. Incremental DOM surprises by remaining fast even when doing less. We look forward to seeing Incremental DOM integrated into Closure and other libraries. React and Ember remain as well balanced approaches each favoring different development methodologies.

<include src="TweetQuote" quoteText="Virtual DOM, Glimmer and Incremental DOM are all excellent options for handling dynamic DOM updates."/>

When picking one of these libraries focus on mindshare and ease of integration unless you are pushing the number of updates per frame to the limit. In that case, study carefully the results from this post and don't forget to run your own specialized benchmarks.


React Virtual DOM vs Incremental DOM vs Ember’s Glimmer: Fight

647b1eea820b3fc8a5aee0383930b888

Pablo Terradillos

Learn how Incremental DOM works and how it compares to Glimmer and Virtual DOM



## Introduction

Hitting the DOM is probably the most expensive operation that most modern web applications must perform, and much effort has gone into providing solutions to solve this problem.

Without a doubt, the one that has gained the most popularity in recent times is the so called _virtual DOM_. Introduced by Facebook's React library, it basically builds an in-memory representation of the DOM. On every update made that is made to the UI, it will create a new representation, diff against it, and only hit those nodes that need to be changed in the _real_ DOM.

Ember's implementation is called _Glimmer_, and it is a substantial improvement to React's. Instead of building a complete representation of the _DOM Tree_, it just takes the elements from a Handlebars template that are dynamic and builds a _tree of streams_, reducing the amount of memory needed to keep them.

Google is working on a different approach with [Incremental DOM](https://github.com/google/incremental-dom) (IDOM). We can say that it has the same base as _virtual DOM_, but with a different approach: **instead of building a representation of the _DOM tree_ in memory, it just uses the real DOM to diff against new trees.**

While React provides JSX as a template engine and Glimmer relies on HTMLBars, **IDOM** is just a simple API for building DOM elements and is not intended to be used directly but as a compilation target for template engines.

In this article, we're going to explore the simple Incremental DOM API by building a library to work with it, along with a functional to-do app.

## Working with Incremental DOM (IDOM)

The IDOM API just consists of four functions for building DOM elements:

* `elementOpen`  - Which corresponds to an opening tag (e.g. `<div>`)
* `elementClose` - Which corresponds to a closing tag (e.g. `</div>`)
* `elementVoid`  - Which corresponds to self-closing tags (e.g. `<input />`)
* `text`         - Which corresponds to text nodes.

So, imagine that we want to produce the following output:

```html
  <div class="foo">
      Hello world!
  </div>
```

The corresponding IDOM function will be:

```js
import ID from 'incremental-dom'

function renderHello() {
  ID.elementOpen('div', null, ['class', 'foo'], null);
  ID.text('Hello world!');
  ID.elementClose('div');
}
```

It should be clarified that `elementOpen` receives three extra parameters besides the tag's name. It also accepts the `key` that will identify the element (we will come back to this later), an array of _dynamic properties_, and another one of _static properties_ (i.e. the ones that are not intended to be changed). Both arrays consists of property-value pairs.

Finally, IDOM provides a `patch` function that will walk our current DOM, diff it against the DOM we want to insert, and finally modify just those elements that need to be modified.

So, if we want to render the previous "DOM declaration" into our app we need to do

```js
patch(document.body, renderHello);
```

And that's it! All you need to know is that `patch` receives an extra parameter that will be passed as an argument of the render function, and you can say to all your coulleages that you know Incremental DOM.

That was a simple example, but the real power comes when we have a DOM structure that constantily needs to be changed. Lets build a _real app_ to see how it works.

## Making IDOM friendlier

The API that IDOM provides makes it really simple to target a custom template engine or any other more expressive API. Lets build something to write our components in a more declarative way.

<include src="TweetQuote" quoteText="The API that IDOM provides makes it simple to target a custom template engine or any other more expressive API."/>

Taking a look at the HTML, we know that each element can contain text or other elements, so lets build a recursive function to allow that using JavaScript. The final result will be an API that allow us to write IDOM components like the following:

```js
ul([
  li('one'),
  li('two'),
  li('three')
], null, ['class', 'foo']).renderTo(document.body);
```

This will render into our body:

```html
  <ul class="foo">
    <li>one</li>
    <li>two</li>
    <li>three</li>
  </ul>
```

Simpler, right?

We want our elements to be capable of receiving one or more elements as children or even simple strings (text nodes) just as in regular HTML. So lets start building a class to represent this structure:

```js
import ID from 'incremental-dom';

class EL {
  constructor(tag, content, key, dynProps, staticProps) {
    // We want to hold local references to element's props
    this.tag = tag;
    this.content = content;

    // We are going to implement a _private_ TEXT class to provide the same interface
    // we have for our elements to Text Nodes.
    // So if we pass a string as an element, we just convert it to this class.
    if ('string' === typeof this.content) {
      this.content = new TEXT(this.content);
    }

    // We allow the users to pass a single element as a child.
    if (!Array.isArray(this.content)) {
      this.content = [this.content];
    }

    this.key = key;
    this.dynProps = dynProps;
    this.staticProps = staticProps;
  }
}
```

In this code, we convert strings to a `TEXT` class so we can have the same interface on Text Nodes as we do in regular elements. Lets implement it:

```js
// ...

class TEXT {
  constructor(content) {
    this.content = content;
  }

  render() {
    ID.text(this.content);
  }
}
```

finally, the render function for our EL class can be written as follows

```js
//...
class EL {
  // ...

  render() {
    // Passing a `null` content, we can assume that we're creating a
    // self closing tag (e.g. `<input />`).
    if (null === this.content) {
      ID.elementVoid(this.tag, this.key, this.props);
      return;
    }

    ID.elementOpen(this.tag, this.key, this.props);

    // Since we have `normalized` our elements to
    // always have the same interface, we can just walk
    // throught them and call it `render` method.
    this.content.forEach((c) => c.render());

    ID.elementClose(this.tag);
}
```

Finally, we need a way to `patch` our element to the DOM:

```js
//...
class EL {
  //...

  renderTo(container) {
    ID.patch(container, this.render.bind(this));
  }
}
```

To make things easier, lets create _builder functions_ so we can just call the elements by its name to construct them (i.e. `div('foobar');`)


```js

// We build helpers function for each DOM tag (reduced to those we're going to need in our up to make it simpler)
let elements = ['div', 'span', 'ul', 'li', 'h1', 'h4'].reduce((prev, tag) => {
  prev[tag] = (elms, key, props) => {
    return new EL(tag, elms, key, props);
  }

  return prev;
}, {});

// we export this elements so we can use them as a module in our project.
export default elements;
```

I have published this as a package called _charata_ that you can find on npm (`npm i charata`). You can take a look at its repository on [Charata's Github repo](https://github.com/auth0/charata).

## Working with DOM

Lets start building our todo app by writing our HTML file:

```html
<!DOCTYPE html>
<html>
<head>
  <meta charset="UTF-8">
  <title>Incremental TO-DO</title>
</head>
<body>
 <form id="add-todo">
  <input type="text" name="new-item" />
 </form>

  <div id="todo">
  </div>

  <script type="text/javascript" src="incremental-todo.js"></script>
</body>
</html>
```

As you can see, I've put a form element with an input inside in "plain" html and left a `#todo` element where we're going to render our _to-do component_. This is just to emphasize the flexibility of working with static html and our recently created library, but you can create a custom component for the `form` as well.

Inside our `incremental-todo.js` file, we're going to create a `class` to represent our todo list. Objects from this `class` should be capable of:

  * Adding a new item to the list.
  * Removing an item from the list.

On every list mutation, we want to re-render our list (which is going to be represented with a component created with our previous helper).

```js
export default class TodoList {
  constructor() {
    this.list = {};
  }

  /**
   * Adds a new item to the list
   *
   * @param {string} text todo-item's text
   */
  addItem(text) {
    var idx = Date.now();
    this.list[idx] = text;
    this.render();
  }

  /**
   * Removes an item from the list.
   *
   * @param {string} idx id of the element to remove
   */
  removeItem(idx) {
    delete this.list[idx];
    this.render();
  }
 }
```

We haven't yet used anything from IDOM or our custom library and the `render` function is called on every mutation of the list. We're going to implement it later, but for now, just note that we have an `id` attribute for each item. This is what we're going to use to identify each individual to-do item and provide it to IDOM (the second parameter of `elementOpen`).

But before the real fun, lets attach an event handler to our form so we can add elements to the list:

```js
let form = document.getElementById('add-todo');

form.addEventListener('submit', (ev) => {
  ev.preventDefault();
  let input = form.elements.namedItem('new-item');
  myList.addItem(input.value);
  input.value = '';
});
```

Great! we're adding elements to our list. To render them to the DOM, we need to implement the `render` function from our `TodoList` class.

```js
 //...
 render() {
   if (this.list.length) {
     ul(Object.keys(this.list).map((idx) => {
       li(this.list[idx], idx, ['data-idx', idx]);
     }), null).renderTo(this.container);
   } else {
     div('Hooray! you are free!', null, ['class', 'center']).renderTo(this.container);
   }
 }
```

Note the `idx` that we've passed to each `li` element. This is what IDOM is going to use to identify elements when we're rendering collections (similar to the `key` property in React).
We're rendering it as a `data-attribute` so we can add an event handler to each of them and identify which is the one we want to delete.

```js
let liElements = document.getElementsByTagName('li');

Array.prototype.forEach.call(liElements, (liEl) => {
  liEl.addEventListener('click', (ev) => {
  ev.preventDefault();
  let idx = LiEl.dataset.idx;
  this.removeItem(idx);
});
```

Feel free to have a look at the [final implementation](http://auth0.github.io/incremental-todo/) of the todo app.

Fire up your inspector and note that even though we're telling our component to re-render itself every time an item is added or deleted, IDOM takes care of re-rendering just the item that changes:

![Incremental DOM in action](https://images.ctfassets.net/23aumh6u8s0i/3p6QirpaLgeZIl0qurNNIn/420bea382bfcca83e3659475c96b484c/incremental-dom)

## Conclusion

The Incremental DOM approach seems to not be as fast as _virtual DOM_ based implementations. However, IDOM uses less memory since it doesn't need to maintain a _live_  representation of the DOM. Rather, it uses the _real DOM_ to walk and compare against the new *state*. This is great for underpowered devices like low-end phones.

IDOM's simple API makes it really powerful for targeting template engines. Google is working on using it as a backend for [Closure Templates](https://developers.google.com/closure/templates/) and there's also an implementation of React's JSX syntax using a [Babel plugin](https://github.com/babel-plugins/babel-plugin-incremental-dom) so we can expect a lot of other template engines to start using it in the short term.

In Auth0 we take performance as a primary goal for each of our products. We are investing a lot of time analyzing view engines. We recently released [Lock Passwordless](https://github.com/auth0/lock-passwordless) which uses React and we're exploring integrate Incremental DOM on some of our current products.
We also have an SDK to use [Auth0 with React](https://github.com/auth0/auth0-react)

To learn more about it, you can take a look at the [Incremental DOM repo](https://github.com/google/incremental-dom).

## Aside: Authentication is Easy with Auth0

Auth0 issues [JSON Web Tokens](http://jwt.io) on every login for your users. This means that you can have a solid [identity infrastructure](https://auth0.com/docs/identityproviders), including [single sign-on](https://auth0.com/docs/sso/single-sign-on), user management, support for social (Facebook, Github, Twitter, etc.), enterprise (Active Directory, LDAP, SAML, etc.) and your own database of users with just a few lines of code.


Incremental DOM 101: What is it and why I should care?

diegopoza

System Engineer, geek, foodie, technology lover, speaker.

Sr Manager, Developer Advocacy

Diego Poza

Learn how to create your first Ember 2.0 app using ES6, ember-cli, ember-simple-auth and much more! We'll implement everything from Authentication to calling an API.

<div class="alert alert-danger alert-icon">
  <i class="icon-budicon-487"></i>
  <strong>This post is out of date.</strong> The EmberJS framework has been through many deprecations and changes since the publication of this article. Please check out our new <a href="https://auth0.com/blog/emberjs-authentication-tutorial/">EmberJS Authentication Tutorial</a> to learn how to quickly build ambitious apps with EmberJS 2 and add authentication the right way.
</div>

> This is a guest post by [Diego Poza](https://twitter.com/diegopoza). He is a systems engineer who is passionate about technology. He works as a developer lead and specializes in emerging technologies, architecture, and technical writing. You can follow him on his [blog](http://southworks.com/blog/author/dpoza/)

The purpose of this post is to show a very simple Ember 2.0 application that uses JSON Web Tokens (JWT) to authenticate to a protected API. **You can get the sample app from [this GitHub repository](https://github.com/diegopoza/ember-jwt).**

## What is Ember 2.0?

Ember is an MVC flavored framework, but in its 2.0 version this has changed to a components oriented approach, as you can see in the following image.

![ember evolution](https://cdn.auth0.com/blog/ember-2.0/ember paradigm.PNG)

_Ember evolution: from 1.x to 2.0_

Ember 2.0 does not introduce any new features, as those features (Glimmer rendering engine, new computed syntax, HTML-style component invocation, and more) were already published in previous versions of Ember. In fact the dev team states that Ember's latest stable release, v1.13, is Ember 2.0 in disguise. You have to also take into account that the features deprecated in v1.x versions will be removed from 2.0.

This means that if you manage to create a v1.13 application with no deprecation warnings, then migrating to 2.0 will be straightforward, as there will not be breaking changes.

### Using 2.0 with Ember-cli

As you may know **ember-cli** is a command line utility for developing Ember apps that was adopted by the dev team. However, the current release only supports Ember v1.13. Therefore, to use Ember 2.0 and take advantage of **ember-cli**, we have to tweak the application it has generated.

Once you have created your Ember application with **ember-cli**, edit the _bower.json_ file, look for the Ember version, and replace it with _'**2.0.0-beta.3**'_. After that, delete the _bower_components/ember_ folder and run:

_bower install_ to fetch the 2.0 beta version. You may be prompted to manually choose the Ember version, as it cannot be resolved automatically. If this happens, just choose **Ember 2.0.0 beta 3** to continue.

> **Note:** Take into account that this workaround is only needed because v2.0 is not the stable release, and it is highly likely that ember-cli will support 2.0 when it becomes stable.

## Creating a simple app that uses JWT

Our simple app will consist of a login form, and a page that shows a random quote obtained by calling the protected API. The server that will authenticate us and provide the secured API is Auth0's  [**NodeJS JWT Authentication Sample**](https://github.com/auth0/nodejs-jwt-authentication-sample).

The app will have two routes: one for the login form, and one for showing the quotes, as you can see in the following code.



```js
// router.js
Router.map(function() {
  this.route('login');
  this.route('protected');
});

```

To work with JWT we will use a plugin called **Ember Simple Auth** that can be downloaded from [here](http://ember-simple-auth.com/)

(http://ember-simple-auth.com/). Follow the _"how to use it"_ instructions in the site to install it. This plugin will help us protect the routes as well as creating code to authenticate us and authorize requests.

On the application route, we will use the **ApplicationRouteMixin**, which will create an application session and provide actions for authenticating and invalidating the session. You can see the application route code below, which only has the **invalidate** action.

```js
// app/routes/application.js
import Ember from 'ember';
import ApplicationRouteMixin from 'simple-auth/mixins/application-route-mixin';
export default Ember.Route.extend(ApplicationRouteMixin, {
    actions: {
        invalidateSession: function() {
            this.get('session').invalidate();
        }
    }
});
```

We will take advantage of the aforementioned methods to display login/logout buttons depending on the session's authentication state. This is done in the application template, as shown below.



```HTML
  
  {{ "{{#if session.isAuthenticated" }}}}
    <p><a {{ " action 'invalidateSession' " }}>Logout</a></p>}}
  {{ "{{else" }}}}
    <p><a {{ " action 'sessionRequiresAuthentication' " }}>Login</a></p>}}
  {{ "{{/if" }}}}
```

Ember Simple Auth also provides the **AuthenticatedRouteMixin** mixin, to secure the routes that should be only available when the user is authenticated. In our case, this is the _protected_ route, as you can see below. If not authenticated it will trigger a redirection to the login route.



```js
// app/routes/protected.js
import Ember from 'ember';
import AuthenticatedRouteMixin from 'simple-auth/mixins/authenticated-route-mixin';
export default Ember.Route.extend(AuthenticatedRouteMixin, {  
});
```

Last, there is the **LoginControllerMixin**, which allows you to specify the controller that will perform the login process.



```js
// app/controllers/login.js
import Ember from 'ember';
import LoginControllerMixin from 'simple-auth/mixins/login-controller-mixin';
export default Ember.Controller.extend(LoginControllerMixin, {
});

```

From here two new concepts arise: **Authenticators** & **Authorizers**.

Authenticators implement the logic necessary to authenticate the session. You will have one authenticator for every _authentication mechanism_ / _provider_ you use. Authorizers, on the other hand, use the secret information acquired by the authenticator to authorize subsequent requests.

You can see our custom implementations below:

```js
// app/authenticators/custom.js
import Ember from 'ember';
import Base from 'simple-auth/authenticators/base';
export default Base.extend({
    tokenEndpoint: 'http://localhost:3001/sessions/create',
    restore: function(data) {
        return new Ember.RSVP.Promise(function(resolve, reject) {
            if (!Ember.isEmpty(data.token)) {
                resolve(data);
            } else {
                reject();
            }
        });
    },

    authenticate: function(options) {
        return new Ember.RSVP.Promise((resolve, reject) => {
            Ember.$.ajax({
                url: this.tokenEndpoint,
                type: 'POST',
                data: JSON.stringify({
                    username: options.identification,
                    password: options.password
                }),
                contentType: 'application/json;charset=utf-8',
                dataType: 'json'
            }).then(function(response) {
                Ember.run(function() {
                    resolve({
                        token: response.id_token
                    });
                });
            }, function(xhr, status, error) {
                var response = xhr.responseText;
                Ember.run(function() {
                    reject(response);
                });
            });
        });
    },

    invalidate: function() {
        console.log('invalidate...');
        return Ember.RSVP.resolve();
    }
});
```

> **Note**:  In the **authenticate** function, inside the function of the first **then** statement, we are saving the token that comes in the **id_token** property of the response of the server, only when the promise is resolved successfully. The token is then saved in the **token** property and can be obtained later in the path _**session.content.secure.token**_, as shown in the custom authorizer below.

```js
// app/authorizers/custom.js
import Ember from 'ember';
import Base from 'simple-auth/authorizers/base';
export default Base.extend({
    authorize: function(jqXHR, requestOptions) {
        var accessToken = this.get('session.content.secure.token');
        if (this.get('session.isAuthenticated') && !Ember.isEmpty(accessToken)) {
            jqXHR.setRequestHeader('Authorization', 'Bearer ' + accessToken);
        }
    }
});
```

You can see that the **Authenticator** calls the token endpoint with the user credentials and returns the token. It also has methods to invalidate the session and to restore it. On the other hand, the **Authorizer** gets the saved token and adds the Authorization header in each Ajax call.

The last important thing you have to take into account about the plugin is how to configure it correctly. To do this, set the desired configuration properties in the _environment.js_ file. The most relevant properties are the following:

- **Store**: This specifies where the session state will persist so it survives page reload. In this case it is set to use the _local storage_.

- **Authorizer**: This property specifies the authorizer that will be used. In our case this is the **custom** authorizer.

- **CrossOriginWhitelist**: This is a very important property for our scenario. By default the Ember simple auth plugin will not authorize requests going to a different origin than the one the Ember.js application was loaded from. Therefore we have to explicitly enable authorization for additional origins, such as the origin of the _NodeJS JWT Authentication Sample_.

- **RouteAfterAuthentication**: This property defines the route that the app will redirect to after successful authentication. In our example, that will be the _protected_ route.

You can see the _environment.js_ file for our sample below.

```js
// config/environment.js
...
ENV['simple-auth'] = {
    store: 'simple-auth-session-store:local-storage',
    authorizer: 'authorizer:custom',
    crossOriginWhitelist: ['http://localhost:3001/'],
    routeAfterAuthentication: '/protected'
};
...
```

###Components

As we mentioned at the start of the post, the Ember 2.0 approach for creating applications has changed to be component driven. Therefore, we created components for our login form view (_login-form_) and for the protected view (_get-quotes_).

Ember components are based on the [W3C Web Components specification](http://www.w3.org/TR/components-intro), which are views that are completely isolated. Properties accessed in its templates go to the view object and actions are targeted at the view object. There is no access to the surrounding context or outer controller; all contextual information must be passed in. Components should have a well-defined interface to the outside world and can broadcast events. A component must have a dash in its name to avoid conflicts with built-in controls that wrap HTML elements. You can see a component definition in the following image.

<include src="TweetQuote" quoteText="Components should have a well-defined interface to the outside world and can broadcast events."/>


![Component Definition](https://images.ctfassets.net/23aumh6u8s0i/tj7XvGz6vyRxQCQFwF2Vh/57c22c21ef04afea7a067aa19008cfc0/component-definition)

_Component definition_

Let's see how the **login-form** component is defined. You can see that the view is defined in the _templates/components/login-form.hbs_ file, and its content is exactly the same as a regular view.

```HTML
  
  <form {{ "{{action 'authenticate' on='submit'" }}}}>
    <div class="form-group">
      <label for="identification">Login</label>
      {{ "{{input value=identification placeholder='Enter Login' class='form-control'" }}}}
    </div>
    <div class="form-group">
      <label for="password">Password</label>
      {{ "{{input value=password placeholder='Enter Password' class='form-control' type='password'" }}}}
    </div>
    <button type="submit" class="btn btn-default">Login</button>
  </form>
  {{ "{{#if errorMessage" }}}}
    <div class="alert alert-danger">
      <strong>Login failed:</strong> {{ "{{errorMessage" }}}}
    </div>
  {{ "{{/if" }}}}
```

Notice the **identification** and **password** values will be passed to the **authenticate** action, which is defined in the component logic, as seen in the following code.

```js
// app/components/login-form.js
import Ember from 'ember';
export default Ember.Component.extend({
    authenticator: 'authenticator:custom',
    actions: {
        authenticate: function() {
            var credentials = this.getProperties('identification', 'password');
            this.get('session').authenticate('authenticator:custom', credentials).catch((message) => {
                this.set('errorMessage', message);
            });
        }
    }
});
```

Notice that the component logic is practically the same as what you would put in a controller, with the exception that you are extending an **Ember.Component** instead of an **Ember.Controller**.

> **Note**: In the future Ember 2.1, the dev team is planning to add [**Routable components**](https://github.com/emberjs/rfcs/blob/master/text/0015-the-road-to-ember-2-0.md#routeable-components), which will simplify the way in which a route can simple redirect to a component instead of a view.

## Aside: Using Ember 2.0 with Auth0

[Auth0](https://auth0.com) issues **JSON Web Tokens** on every login for your users. That means that you can have a solid identity infrastructure, including Single Sign On, User Management, support for Social (Facebook, Github, Twitter, etc.), Enterprise (Active Directory, LDAP, SAML, etc.) and your own database of users with just a few lines of code. You can use our [EmberSDK](https://auth0.com/docs/client-platforms/emberjs) which uses _ember-simple-auth_ to integrate [Auth0](https://auth0.com) with Ember 2.0 to avoid having to deal with Authentication again!

<img src="https://images.ctfassets.net/23aumh6u8s0i/63b5DYF182Fnz8f5xO8h7X/23e8434a340de4562db5b155331d0311/pub_w_1219_amp_h_559" style="border: 1px solid #ccc;padding: 10px;"/>


### Summarizing

The following image summarizes the application flow:

![application flow](https://cdn.auth0.com/blog/ember-2.0/application flow.PNG)

_Application flow_

When successfully logging in, the session is created and the Authenticator stores the JWT in local storage. Whenever generating an AJAX request to the app or to any whitelisted origin, such as the JWT server, the authentication header with the JWT will be appended by the authorizer, validating all subsequent requests to the the Authentication Sample server.

![Application demo](https://images.ctfassets.net/23aumh6u8s0i/50eAssp7IPfpXQSqOvfkjB/bb417c061a34058d2ea8be2be6c9da57/appdemo)

_Getting random quotes from the protected API_

As a final note, take into account that you may receive deprecation warnings due to the way that the **Ember Simple Auth** plugin uses Ember's container. You can just ignore these warnings for the time being, as we expect that the plugin will be updated when Ember 2.0 is released.

Hope this post has been useful to you.

Create your first Ember 2.0 app: From authentication to calling an API

42e2ec6a72627f8c15115e279a5f7d8e

Guest Author

Ben Schwarz

Introducing an official 'ember simple auth' add-on



<div class="alert alert-info alert-icon">
  <i class="icon-budicon-500"></i>
  <strong>Visit <a href="/blog/build-and-authenticate-an-emberjs-3-application/">Build and Authenticate an EmberJS 3 Application</a> to read our most up-to-date tutorial.</strong>
</div>

<div class="alert alert-danger alert-icon">
  <i class="icon-budicon-487"></i>
  <strong>This tutorial has been deprecated.</strong>
</div>

__TLDR;__ Install the add-on using ember-cli `ember install auth0-ember-simple-auth`, or checkout the generated [example application](https://github.com/auth0/auth0-ember-simple-auth/tree/master/examples/simple) to get started.

-------

At Auth0, we’re huge fans of [Ember](http://emberjs.com), the Javascript framework made famous for writing ambitious single page applications (also known as SPA).

Unfortunately, up until now our support and resources for Ember have not equalled our enthusiasm for it. Thankfully, starting today, we have some great news —

![Auth0 + Ember logos](https://images.ctfassets.net/23aumh6u8s0i/1OmRtzhY0B2pQjr7zmQvDF/042e08bfa6bceb14b1216c9b2af0594a/auth0-ember)

# Introducing an official 'ember simple auth' add-on

For those familiar with Ember, it might go without saying that “[ember-simple-auth](http://ember-simple-auth.com)” is the most popular authentication helper library around. It implements a strategy based plugin system that allows users to write their own custom authentication strategies.

That is exactly what one of our customers, [Aram Zadikian](https://github.com/brancusi) did, and thanks to his generosity, we’re able to share his fantastic work with you today!

We'll be maintaining `auth0-ember-simple-auth` on an ongoing basis, so you can rely on it to build your ember applications.

## What does it do?

`auth0-ember-simple-auth` is an Ember-cli add-on that uses [Lock](https://auth0.com/lock), and, after some simple configuration will allow you to sign up/in and out — protecting whichever pages you've specified in your router.

```
// app/routes/application.js

import Ember from 'ember';
import ApplicationRouteMixin from 'simple-auth/mixins/application-route-mixin';

export default Ember.Route.extend(ApplicationRouteMixin, {
  actions: {
    sessionRequiresAuthentication: function(){
      // Check out the docs for all the options:
      // https://auth0.com/docs/libraries/lock/customization

      // These options will request a refresh token and launch lock.js in popup mode
      var lockOptions = {authParams:{scope: 'openid'}};

      // This tells simple-lock to use our `auth0-ember-simple-auth` add-on
      this.get('session').authenticate('simple-auth-authenticator:lock', lockOptions);
    }
  }
});

```

Now that you have enabled your simple-auth strategy, its just a matter of importing the `AuthenticatedRouteMixin` from `ember-simple-auth` to lock down routes that need to be protected.

```
// app/routes/my-protected-route.js

import Ember from 'ember';
import AuthenticatedRouteMixin from 'simple-auth/mixins/authenticated-route-mixin';

export default Ember.Route.extend(AuthenticatedRouteMixin);
```

Now you've already got a secure single page application. Time to focus on writing your app!

![A sample application in use — Running through an authentication flow](https://images.ctfassets.net/23aumh6u8s0i/5QVfIyB3z912z95cgeJ8aw/31297f25190488606cf5508938904367/ember-simple-auth)

You can install & run the `auth0-ember-simple-lock` add-on, or, to fast forward to a fully working ember application (shown above), you can download the seed project from [your application dashboard](https://manage.auth0.com/#/applications).

We can't wait to see what you do with ember, make sure you [reach out on Twitter](https://twitter.com/auth0) with what you create.

✌️ Happy hacking!


"ember"