Development Environment

Overview

This tutorial explores setting up your tools and environment for the best possible Dojo development experience. You may use demo code from any of the Dojo tutorials, but this tutorial will reference finished code from the Forms tutorial.

Prerequisites

You can download a fresh install of the demo code to get started.

You should be familiar with the developer tools in your browser of choice. This tutorial will reference the Chrome developer tools, but the instructions should generally apply to any browser.

Command line tools

The local installation tutorial covers the installation of the Dojo CLI and its available commands. Before installing the Dojo CLI, we assume you have an environment with supported versions of node, npm, and git installed.

While git is not strictly necessary to use Dojo, a robust development environment also needs some sort of version control system. All of Dojo uses git as the version control tool and we manage all of our code on GitHub. Many of our READMEs and other documentation may assume that git is being used. If it or another version control tool is not already installed, you can follow the Git installation instructions.

Initialize a git repository

Run git init within the root biz-e-corp directory

The git init command should log Initialized empty Git repository in /path/to/biz-e-corp/.git/ in your console.

Create your first commit

Use git add to begin tracking files, and git commit to create a commit. For more information, refer to Git basics instructions.

Configure your editor

Get an editor that supports TypeScript.

Any code editor will allow you to work on a Dojo project, but an editor that supports TypeScript will give you a richer development experience, as Dojo is built with TypeScript and specifically designed to take advantage of its features. A list of editors with plugins that enable TypeScript support is available to help you find an appropriate editor.

Install TypeScript support

In Atom, for example, this means installing atom-typescript. Visual Studio Code includes TypeScript support out of the box, and for Vim try installing a combination of plugins for language features and syntax highlighting.

Test error highlighting

This tutorial uses VS Code, however you can use any TypeScript compatible editor you wish.

Within the demo app, open src/widgets/WorkerContainer.ts in your code editor of choice. In WorkerContainer, there is code to create an instance of the Worker widget within the render function. Modify it to add a fake property, e.g.:

  1. const workers = workerData.map((worker, i) => w(Worker, {
  2.   key: `worker-${i}`,
  3.   fakeProp: 'foo',
  4.   ...worker
  5. }));

Verify that your editor has highlighted fakeProp as an error:

error message in Atom

Go further: VS Code and tasks

You may skip to the next step if you are not interested in the VS Code editor.

VS Code supports TypeScript by default, is written is TypeScript, and allows you to configure tasks which are then integrated into the IDE.

To configure tasks:

  • Press ⌘ + ⇧ + P / Ctrl + ⇧ + P to open the command list.
  • Type in tasks
  • Select the command Tasks: Configure Task
  • Select ‘Open tasks.json file’
    gif of opening tasks.json

The first tutorial had you run dojo build as the first Dojo CLI command after creating your app, Replace your current tasks.json file with the code below:

  1. {
  2.   "version": "0.1.0",
  3.   "command": "dojo",
  4.   "isShellCommand": true,
  5.   "args": [],
  6.   "showOutput": "always",
  7.   "suppressTaskName": true,
  8.   "tasks": [
  9.     {
  10.       "taskName": "build",
  11.       "args": [ "build" ],
  12.       "isBuildCommand": true,
  13.       "problemMatcher": {
  14.       "owner": "dojo",
  15.       "fileLocation": "relative",
  16.       "pattern": [
  17.         {
  18.           "regexp": "^(\\S+) in (.*)",
  19.           "severity": 1,
  20.           "file": 2
  21.         }, {
  22.           "regexp": "\\((\\d+),(\\d+)\\):(.*)",
  23.           "line": 1,
  24.           "column": 2,
  25.           "message": 3
  26.         }
  27.       ]
  28.       }
  29.     }
  30.   ]
  31. }

Other tasks to consider adding could be test or watch. Once configured, those tasks will be available in the IDE along with build:

dropdown of vs code tasks

To access your tasks:

  • Open the command palette
  • Type in run task
  • Observe the configured tasks display in the command palette

Debugging

If you are developing a Dojo application in TypeScript, your application code must be transpiled from TypeScript into JavaScript. This transpilation can happen through the Dojo CLI tool, or through your own configured build system.

If you are also using dojo build, then your code is also being bundled and minimized. Bundling and minimizing could make it challenging to debug your application in the browser, but we have made efforts to integrate Dojo into modern debugging tools.

Source maps describe a way to map from transformed source code back to its original source. The dojo build command maps the code throughout the process so that both the original TypeScript code and CSS code is available when debugging. This integrated workflow should allow you to set breakpoints and watch expressions on the original code as well as see the original code when there is a run-time error.

Debug the tutorial demo application in Chrome DevTools

Create a breakpoint in WorkerContainer

To demonstrate the source mapping between compiled JavaScript code and the source TypeScript:

  • Open the Sources tab in Chrome DevTools
  • Browse to WorkerContainer.ts
  • Insert a breakpoint on line 21
  • Reload the webpage, you should see the browser pause script execution at the breakpoint
    breakpoint set in Chrome DevTools

Using breakpoints enables the JavaScript engine to pause execution at a line of code and enables inspection of in-scope variables. You can use this to discover the value of a variable at a particular point in time.

Install an accessibility inspector

Dojo widgets are designed to be accessible by default. A good in-browser accessibility inspector helps integrate accessibility into the development process. The Google Accessibility team provides a Accessibility Developer Tools browser extension on the Chrome Web Store, which can be used when inspecting the DOM:

chrome accessibility inspector

The inspector exposes text and semantics visible to a screen reader, providing a page model referred to as the Accessibility Tree.

Chrome Accessibility Developer Tools does not run an audit against your code, or validate it in any way. For easy in-browser a11y validation, aXe has free open-source extensions for Chrome and Firefox.

Summary

Dojo can be used out of the box with any code editor, but good TypeScript support will provide integrated code help and intellisense. Together with robust in-browser debugging, this should set you up with a streamlined process for editing, troubleshooting, and committing code.

Moving forward, you can: