V5-Migration-Guide.md

Version 5.0.0 Migration Guide

Dojo 5.0.0 includes a few breaking changes that will need to some changes in your applications code base. As with previous releases, we have updated the @dojo/cli-upgrade-app CLI command to help you through the upgrade process and automate as much as possible. Where it is not possible to automate the upgrade, you should receive helpful information in the output that indicates what needs to get manually upgraded and in which module.

To install the upgrade command, run the following from the project root:

npm install @dojo/cli-upgrade-app --no-save

To perform the migration, run the following command from the project root. The migrations tool should automatically detect the necessary migration from your package.json.

dojo upgrade app

If you are upgrading from a version before 4.0.0, please see the previous migration guides for more details first.

• The @dojo/cli should be updated to version 5.0.0, along with all the commands used by the project.
• If your project is using @dojo/widgets and @dojo/interop, these packages also require upgrading to version 5.0.0.

Note: The migration tool may create line lengths that violate your projects linting rules, be sure to run your linter and manually fix any linting rule violations.

Breaking Changes:

has module consolidation

Building on the cleanup started with the 3.0 consolidation of packages into @dojo/framework, this release of Dojo moves all has related modules in a single has module, @dojo/framework/has/has. If you run the dojo/cli-upgrade-app command all references to removed has modules should be automatically updated.

classes property with the Themed mixin

A new API that supports passing classes keyed by a widgets theme key is now available for all widgets that use the @dojo/framework/widget-core/meta/Themed mixin.

This is not a traditional breaking change as it will only affect themed widgets that have a classes property specified on its API.

Support for before middleware in stores

Middleware in stores has always support running after a process completion or error, Dojo 5.0.0 introduces support for middleware that runs before a process is started. To support this the API has changed. More information can be found on the stores readme.

v4.x

// A single process middleware

const myProcess = createProcess('process', [myCommand], (error, result) => {
	// middleware logic
});

// Composite middleware

const myMiddlewareOne = createCallbackDecorator((error, result) => {
	// middleware logic
});

const myMiddlewareTwo = createCallbackDecorator((error, result) => {
	// middleware logic
});

const myProcess = createProcess('process', [myCommand], myMiddlewareOne(myMiddlewareTwo()));

v5.x

// A single process middleware

const myProcess = createProcess('process', [myCommand], () => ({
	after: (error, result) => {
		// middleware logic
	}
}));

// Composite middleware

const myMiddlewareOne = () => ({
	after: (error, result) => {
		// middleware logic
	}
});

const myMiddlewareTwo = () => ({
	after: (error, result) => {
		// middleware logic
	}
});

const myProcess = createProcess('process', [myCommand], [myMiddlewareOne, myMiddlewareTwo]);

Note: If your application is using the createCallbackDecorator factory from @dojo/framework/stores/process these processes will be forwards compatible as the factory has been re-purposed to convert the 4.0.0 API to the 5.0.0 API. However we recommend updating these as time permits and using the createCallbackDecorator factory will log out a warning to the console when running a dev build.

A new base class for meta

A new base interface is used by the meta method on WidgetBase. It is unlikely that this change will impact most application code bases.

However, when upgrading to Dojo 5, if you experience compilation errors related to WidgetMetaBase you will likely need to switch this interface with the new base, MetaBase, from @dojo/framework/interfaces.