Dojo 2 Release Candidate 1 is now available!

Author widgets with @dojo/widget-core

Dojo has always emphasized the creation of widgets, and Dojo 2's @dojo/widget-core package creates an environment providing developers with simple ergonomics allowing them to build robust applications. Leveraging a modern and reactive, uni-directional approach to data binding with a virtual DOM, @dojo/widget-core streamlines the process of creating widgets and apps.

There are many scenarios where it is challenging to preserve a reactive architecture when working with properties of DOM nodes, so @dojo/widget-core provides meta abstractions to help deal with DOM nodes without breaking the flexibility of a reactive architecture.

@dojo/widget-core embraces the future of the web platform with out of the box meta implementations for Intersection Observers, and Web Animations. With plans to add support for more existing and upcoming living standards from WIGC via meta in the future.

The following example renders a list with images. By leveraging the Intersection Observer meta, the image src gets added only when the item is in the viewport, which prevents needlessly downloading images until the user scrolls to them.

import { WidgetBase } from '@dojo/widget-core/WidgetBase';
import { v, w } from '@dojo/widget-core/d';
import { Intersection } from '@dojo/widget-core/meta/Intersection';

interface ImageProperties {
    image: string;
}

class Image extends WidgetBase<ImageProperties> {
    protected render() {
        const { image } = this.properties;
        const { isIntersecting } = this.meta(Intersection).get('root');
        const properties = isIntersecting ? { key: 'root', src: image } : { key: 'root' };

        return v('img', properties);
    }
}

interface ImageListProperties {
    images: string[];
}

export class ImageList extends WidgetBase<ImageListProperties> {
    protected render() {
        const { images } = this.properties;
        return v('div', images.map((image) => {
            return v('ul', { key: image }, [ w(Image, { image } )]);
        }));
    }
}

Css Modules and css-next

Dojo 2 uses css modules, out of the box to provide localized class names as standard. This ensures that your styles do not leak out of your widgets and provides type-ahead capability when importing your css files into your widget.

Css-next enables allows Dojo 2 widgets to use cutting edge css syntax and features immediately, such as calc, css-variables and various color functions. These are all compiled down to browser friendly variants at build time so there's no need for a post processor such as SCSS or Less.

Dojo loves Custom Elements

A top priority for Dojo is interoperability with the web platform, both by utilizing current and emerging standards and providing a mechanism to coexist with other frameworks efficiently. The Custom Elements portion of the Web Components standard is one area to encourage interoperability between UI component libraries and frameworks.

The Custom Elements Everywhere project was released last year to highlight framework support for using custom elements, and Dojo 2 currently has a perfect score.

You can do much more than simply use custom elements within a Dojo 2 project, you can compile your Dojo 2 widgets to custom elements via one of our @dojo/cli commands, making it shareable and easy to distribute Dojo 2 widgets across projects and frameworks. So if you are in an organization where some teams use Angular, some use React, some use Vue, and some use Dojo, we provide a future today where you can write a component once and share it across those teams!

By default, Dojo's custom elements are built for evergreen browsers to reduce overall bundle size, meaning most basic widgets are <20KB (gzipped) including all of the @dojo runtime needed to support the custom element.

The customElement decorator annotates the widget class and instructs the cli-build-widget command to convert it to a custom element:

interface HelloWorldProperties {
    onClick: (event: Event) => void;
    foo: string;
    bar: string;
}

@customElement({
    tag: 'hello-world',
    attributes: [ 'foo', 'bar' ],
    events: [ 'onClick' ]
})
class HelloWorld extends WidgetBase<HelloWorldProperties> {
// ...
}

To compile a Dojo widget into a web component, run the following command:

npx @dojo/cli build widget --elements src/HelloWorld

For ease of use, all @dojo/widgets are compiled to custom elements and published to npm and easily imported into your projects.

Learn more about creating your first Dojo widgets with the first Dojo 2 application tutorial.

The Dojo CLI

CLI tools provide an easy way to work with frameworks, a trend popularized in the JS community by Ember. The Dojo CLI is a collection of packages, providing a CLI architecture enabling a modular approach to create and work with commands.

One of our goals in creating an easy out of the box experience with Dojo is to abstract users away from complex configuration by using intelligent defaults internally.

To install the Dojo CLI, run the following command: npm install -g @dojo/cli

There are currently six officially supported CLI command modules:

$ dojo create app --name my-first-dojo-2-app

State management

No modern framework would be complete without a recommended approach to state management.

Managing state can become difficult to coordinate when an application becomes complicated with multiple views, widgets, components, and models. With each of these attempting to update attributes of state at varying points within the application lifecycle things can get confusing. When state changes are difficult to understand or non-deterministic, it becomes increasingly difficult to identify and reproduce bugs or add new features.

@dojo/stores is a predictable, consistent state container for JavaScript applications with inspiration from Redux and Flux architectures. However, the @dojo/stores package aims to provide more built-in support for common patterns such as asynchronous behaviors, undo support and more!

The @dojo/stores package provides a centralized store, designed to be the single source of truth for an application. It operates using uni-directional data flow, so all application data follows the same lifecycle, ensuring the application logic is predictable and easy to understand.

Key features of @dojo/stores include:

• Application state store designed to work with a reactive component architecture
• Out of the box support for asynchronous commands
• All state operations are recorded per process and undoable via a process callback
• Supports the optimistic pattern with the ability to roll back on a failure
• Fully serializable operations and state

When managing application state with the @dojo/stores package, there are three core but simple concepts - Operations, Commands, and Processes.

• Operations: Granular instructions to manipulate state based on JSON Patch
• Commands: Simple functions ultimately returning operations needed to perform the required state change
• Processes: A function executing a group of commands usually representing a complete application behavior

Dojo 2 also makes it easy to support other patterns such as those popularized by Unstated. Less complex applications can simply lift state up to parent widgets and use local state.

Documentation and examples

To get started, we have a series of Dojo tutorials and reference documentation ranging from the very basic to more complicated topics such as lazy loading, web animations and more. In addition to these resources, all Dojo 2 packages have detailed READMEs.

We've created a variety of examples of Dojo 2 usage:

• TodoMVC - TodoMVC is the canonical example used to demonstrate fundamental web application paradigms
• TodoMVC kitchen sink - Our extension of TodoMVC used to illustrate a selection of Dojo 2 specific capabilities such as theming and internationalization.
• RealWorld - A full web application example with authentication, code splitting, state management, routing and more.
• HNPWA - The spiritual successor to TodoMVC, Hacker News PWA is designed to demonstrate progressive web app capabilities with a focus on providing a fast, reliable experience with rich offline support
• Custom element menus - Demonstrates using Dojo 2 widgets both natively and as a custom element without needing to adapt the authoring pattern.

To learn more about Dojo 2 and get started, check out the Dojo 2 tutorial series.

What's next?

In the release candidate stage, we will fix any critical issues reported and then have another release candidate. After a week with no critical blocking issues, we will announce 2.0.0!

We also hope to have Dojo 2 available on CodeSandbox in time for the 2.0.0 release as well.