Dash 1.0.0 Series - Proposed Set of *Breaking Changes*

[chriddyp]

##Roadmap Items

React 16 support

• dash 1.0.0 alpha release / React 16
• dash-renderer 1.0.0 alpha release / React 16
• dash-html-components 1.0.0 alpha release / React 16
• dash-core-components 1.0.0 alpha release / React 16
• dash-table mixed React 15 and 16 support
• dash-docs working under React 16
• dash-dangerously-set-inner-html mixed React 15 and 16 support

New features and changes

• serve files locally by default
• hide undo/redo buttons by default
• dcc react-date update
• dcc react-markdown update
• dcc react-syntax-highlighter update REMOVED SyntaxHighlighter component entirely
• Version lock Dash repos

Sign-off as Release Candidate

• validation against real world applications

Deferred

• CDN resource integrity - can be added without breaking, anyway serve_locally=True by default now so this is somewhat less important.
• dcc rc-slider update - this too can be done without breaking

This is the "Proposed Breaking Changes" issue as per the "Breaking Changes" process outlined in #458.
The version 1.0.0 of dash, dash-renderer, dash-core-components, and dash-html-components will be compatible with each other and will contain at least one breaking change across the libraries.
We will publish the breaking changes no earlier than 2 weeks after we have publicly committed to the proposal in this issue.

Proposed list of breaking changes

1. Upgrade React.js and react-dom from v15.6.2 to v16.6.1
2. Set serve_locally = True by default
3. Resource integrity checks for CDN resources
4. Hide the undo/redo buttons by default
5. Update how the initialization callbacks work if properties aren't supplied

Breaking Change 1. Upgrade React.js (react) and react-dom from v15.6.2 to v16.6.1

Technical Background
Dash's front-end is built on top of React.js. This includes:

• dash-renderer: The package that renders components, makes API calls to Dash's backend, and manages updates
• The component libraries, notably dash-core-components and dash-html-components, are React components, rendered by dash-renderer.

dash-renderer provides the React libraries (as script tags) - individual component libraries do not have React.js bundled in their libraries (React is an "implicit" dependency). So, to update React, we only need to update the React and react-dom libraries provided in dash-renderer. The component authors are responsible for ensuring that their components will work in this new version of React.

Pull Requests that make these changes

• Dash 1.0 - Update version to 1.0.0a1 dash-renderer#97

• Update dependencies to their latest dash-core-components#373

• Dash 1.0 - Update version to 1.0.0a1 dash-html-components#81

• Dash 1.0 - Update version to 1.0.0a1 #457

• Community PR for React 16 transition Update requirements to support React 16 dash-core-components#165

Reason for Upgrade

• React 15 is over 1 year old and React 17 is already on its way.
• Many components in the React community stay up to date with the latest version of React. If Dash doesn't keep up with React's latest versions, these component libraries may become incompatible with Dash.
• Many components in dash-core-components are simply wrappers around 3rd party components in the React community. Without upgrading React, we can't upgrade our components to the latest versions of the React components, missing out on bug fixes and features.
• A few features in dash-renderer can only be implemented with features available in React 16. In particular, our Dash Dev Tools project that propagates error messages from the browser console and the backend to the app's UI.

Implications for the Dash Developer

• The Dash Developers will not need to make any changes to their code.
• If the Dash Developer is using a custom Dash component and if that custom component isn't React 16 compatible, then the Dash Developer will not be able to use the new versions of dash, dash-renderer, dash-core-components, or dash-html-components.
• Most developers are not using custom components and therefore will not be affected by this change.

Implications for the Dash Component Author

• Component authors will need to upgrade their JavaScript components to be compatible with React 16.
• The most common change is to change the PropTypes import.
  In React 15, this usually looks like:

  import React, {PropTypes} from 'react';

  In React 16, this is a separate package:

  import React from 'react';
  import PropTypes from 'prop-types';

• If the component author is using a 3rd party package, they may need to upgrade the underlying component.
• To test whether their component is React 16 compatible, the component author can try out React 16 in dash-renderer by setting:

import dash_renderer
dash_renderer._set_react_version('16.2.0')

We should update dash-renderer with an option to try out React 16.6.1.

Implications for Documentation

Our plugin documentation and the dash-component-boilerplate will need to be updated to highlight this change.

Implications for Community Forum

The following threads mention React and will need to be updated:

• https://community.plot.ly/t/migrating-to-react-16/7874

I searched "React 16" and "React 15" in the community forum to find these threads.

Will this break or change in the future? If so, how can we prepare?

Yes. React 17 will come out next year with its own set of breaking changes. Component authors will need to upgrade our components to be React 17 compatible and we will need to update dash-renderer with the new version of React.

For this to be a smooth transition, we should:

• Allow component authors to switch to React 17 in dash-renderer with dash_renderer._set_react_version('17')
• Wait a few months after React 17 is released, to allow the 3rd party, community maintained components to become compatible

Can this be done in a backwards compatible way instead?

No. There is only one React version that is included in Dash and that version needs to be upgraded.

Are there any other risks to consider?

Some Dash component authors in the community may not upgrade their components to be React 16 incompatible (because they didn't get the notifications, they don't have the time, they don't have the expertise, etc).

If certain popular components aren't updated, then the Dash dev team (or other community members) could make a (temporary) fork of the components that is compatible.

We will rely on users to report these issues via the Dash Community Forum.

Beyond the communication policy outlined in #458, are there any other ways that we can inform our users about this change?

• React.js may provide JavaScript error messages if a component is using an outdated method. If so, then the user may become aware of this by inspecting their console or, with [Dash Dev Tools], by viewing the error notification in their app.
• Through GitHub search and through the Dash Community Forum, we can find open source community-authored Dash components. We can open issues in those repositories to inform the authors of the change.

Can we automate the upgrade process for our users?

Not really. We could make PRs into the open source libraries for certain simple, common fixes (like the proptypes import).

Is there anything to consider with respect to compatibility between components?

Yes. The "1.0" series of dash-renderer will only be compatible with the "1.0" series of the main component libraries (dash-core-components, dash-html-components). Technically, dash will not be affected and the "1.0" series of dash may be compatible with the "0" series of the other libraries and vice versa. However, this will not be guaranteed. We will gaurentee the compatibility of these packages within a major version series.

If something breaks, can we inform users through an error message in any way?

I don't think so. We will be relying on React to provide helpful error messages if a component is incompatible. Perhaps we could test this out and create community forum posts with the error messages in advance of this change.

Are there any open items?

• dash-renderer needs to be updated with a way for users to try out React 16.6.1 (here: https://github.com/plotly/dash-renderer/blob/5e4d5629eb03a68bdbefd650d2f64a4ba9c48529/dash_renderer/__init__.py#L16-L38)
• Dash User Guide PRs need to be made
• Dash Component Boilerplate PRs need to be made
• Dash
• I'd like for us to investigate what the common JS error messages are and determine:
  • Are the error messages helpful? Will the user know that their app is broken because they are using a custom component that is incompatible with React 15?
  • If not, is there anything we can do to intercept these error messages?

Breaking Change 2 - Set serve_locally = True by default

Pull Requests that make these changes

#722

Reason for Upgrade

By default, the JavaScript and CSS for Dash's component suites are served from the unpkg CDN (the same CDN that the React.js recommends). The user can serve these packages locally, from their Python site-packages folder (the folder that contains the installed packages for a given Python installation) by setting:

app.scripts.config.serve_locally = True
app.css.config.serve_locally = True

Serving the assets from the CDN may be faster than serving the assets from Flask (although this has not been rigorously tested). However, there are several issues:

1. Offline Environments. Many Dash apps run in completely offline environments: airgapped corporate or offsite networks, airplanes, conferences, cafes. Unless the user sets serve_locally = True, the app will silently fail to load.
2. It's hard to debug when it doesn't work. If the app doesn't have internet access and the app doesn't load, it's hard to know why. You have to open up the browser console and inspect the network requests. Dash is supposed to abstract away these complexities.
3. The CDN is untrusted. Dash doesn't own the unpkg CDN and so unpkg could be hacked and could serve malicious JavaScript instead of the Dash component libraries. In Generate integrity hash for scripts/link tags on the index. #442, we're adding resource integrity checks so that if unpkg serves a different JavaScript or CSS bundle than what we originally provided, the browser will reject the request. However, these resource integrity checks are not supported in IE and only partially supported in Edge.
4. It doesn't work if the component libraries aren't published to NPM. The unpkg CDN serves files that are published to NPM. If a Dash app uses a package that hasn't been published to NPM, then the user needs to set serve_locally = True. While dash-core-components, dash-html-components, and dash-table will all be published to NPM, not all packages will be. For example, packages that are built by organizations and kept private or packages that are in development (via dash-component-boilerplate).

Implications for the Dash Developer

• This should not break any Dash apps.
• Anywhere where serve_locally=False is used (implicitly set as the default or explicitly set), serve_locally=True should work as well.
• If the user has customized the path of Dash's HTTP requests (via url_base_pathname, requests_pathname_prefix, and/or routes_pathname_prefix), then the Dash JavaScript and CSS bundles will be routed through that prefix as well. This is already supported and handled automatically by Dash.
• Apps that are tested with the Percy screenshot service may fail. For locally provided CSS, Percy needs a reference to the static folder. In Dash, the "static folder" for CSS is actually several site-packages folders. Users using Percy can fix this by explicitly setting serve_locally=False. This will affect a small number of users.
• There is a risk that, in some environments, flask is unable to serve the large JavaScript bundles ("error: connection reset"). This has been reported a few times by users on Windows, see Serving large files locally (JS bundles) on windows machines in flask sometimes doesn't work #56 for more. Since serve_locally = False has been the default, we aren't fully aware of how many users will have this issue.

Implications for the Dash Component Author

Less frustration! serve_locally=True needs to be set when developing a component locally (since it isn't published to NPM while developing) and it's easy to forget this.

With serve_locally=True, Dash Component authors that publish public packages may forget to test their packages with serve_locally=False. If they follow the instructions from the boilerplate, then it "should work" but they may forget or misconfigure the necessary references to extra CSS files.

Implications for Documentation

• https://dash.plot.ly/external-resources will need to be updated.

Implications for Community Forum

• There are many threads that refer to this serve_locally setting. We should update the most popular threads to inform users that they don't need to set this anymore:
  • https://community.plot.ly/t/serve-locally-option-with-additional-scripts-and-style-sheets/6974/23
  • https://community.plot.ly/t/how-do-i-use-dash-to-add-local-css/4914/34

Will this break or change in the future? If so, how can we prepare?

No. Once serve_locally = True should be the default for here on out.

Can this be done in a backwards compatible way instead?

No.

Are there any other risks to consider?

There is a risk that serving the JS and CSS files from site-packages doesn't work in some environments due to unknown reasons. As always, we will have to rely on user's bug reports in the community forum and GitHub.

Beyond the communication policy outlined in #458, are there any other ways
that we can inform our users about this change?

No.

Can we automate the upgrade process for our users?

No.

Is there anything to consider with respect to compatibility between
components?

No. All component libraries should work with serve_locally = False.

If something breaks, can we inform users through an error message in any
way?

Perhaps.

• If a flask route fails, then we could log it in the terminal. In dash==0.30.0, we silenced flask's route logging for 200 level requests, do we still log 4xx or 5xx errors in the terminal? Should we?
• We could try to help folks out in a "debugging tips" section of the user guide: https://github.com/plotly/dash-docs/issues/202#issuecomment-441775091

Are there any open items?

• Need a PR in dash serve_locally by default #722
• Need a PR in dash-docs https://github.com/plotly/dash-docs/pull/500

Breaking Change 3 - Resource integrity checks for CDN resources

Deferred until a later release and less important since serve_locally is True by default

Pull Requests that make these changes

#442

Reason for Upgrade

Currently, when serve_locally = False (the current default but soon it won't be, see above), Dash loads component's CSS and JavaScript from the unpkg CDN which is untrusted. This change would add a resource integrity check to the script tags, allowing the browser to reject the resource if it was modified in any way.

This is a breaking change as it is uncompatible with older versions of dash-core-components. In our "1.0 Series" of Dash, we will ensure the compatibility of versions across our Dash libraries.
No longer a breaking change since we version-lock the dash core packages.

Implications for the Dash Developer

serve_locally = False will be more secure as long as you are on a browser that supports subresource integrity checks (not supported in IE and Edge).

Implications for the Dash Component Author

Component authors will have to ensure that the files that they are uploading to NPM are unmodified before or after they publish to PyPI as the resource integrity check is computed from the local file.

Implications for Documentation

We will need to document this in our plugin guide: https://github.com/plotly/dash-component-boilerplate

Implications for Community Forum

None.

Will this break or change in the future? If so, how can we prepare?

I don't think so.

Can this be done in a backwards compatible way instead?

No. Currently, this change breaks old versions of dash-core-components (which had files that were modified in between the NPM and PyPI publish sets) but we can't modify packages that are already published.
Version locking has rendered this obsolete.

Are there any other risks to consider?

I don't think so.

Beyond the communication policy outlined in #458, are there any other ways
that we can inform our users about this change?

I don't think so.

Can we automate the upgrade process for our users?

Perhaps the publish script in dash-component-boilerplate could ensure that the bundles aren't rebuilt between publishing to NPM and PyPI?

Is there anything to consider with respect to compatibility between
components?

No

If something breaks, can we inform users through an error message in any
way?

If the resource integrity check fails, the user will see an error in their browser console. Perhaps we could include this in our "Dash Debugging Guide", in particular the section about network requests.

Are there any open items?

• We will need to document this in our plugin guide: https://github.com/plotly/dash-
• Investigate: Can the publish script in dash-component-boilerplate ensure that the bundles aren't rebuilt between publishing to NPM and PyPI?
• Update dash debugging guide with a section about integrity network checks?

Breaking Change 4 - Hide the undo/redo buttons by default

Pull Requests that make these changes

NA

Reason for Upgrade

Historically, the undo/redo buttons were a 'feature' that I included during the initial development of Dash. I wanted to ensure that the Dash architecture was amenable to an undo/redo functionality, similar to what's available in other BI solutions. Including them by default in Dash was for my own development sanity: is dash capable of performing undo/redo?

It's a neat feature and it demonstrated how powerful Dash's state-driven architecture was. However, it was never thoughtfully designed and in many cases, it isn't that useful for end-users. In fact, "is it possible to hide the floating toolbar" is one of the most visited community forum topics.

While it's possible to remove the buttons through CSS, it requires some googling to learn how and an extra CSS file. Dash is productive: the default behaviour shouldn't require users to create more than a single file in their project.

So, I propose that we remove them by default and we add an extra config flag to allow users to turn them back on: app = dash.Dash(__name__, show_undo_redo=True).

Implications for the Dash Developer

If users really liked this feature, then they'll have to explicitly turn it back on.

Implications for the Dash Component Author

None.

Implications for Documentation

• We'll include this setting in the dash.Dash() constructor, so it should be visible in the users IDE via the docstring
• We don't have a central place in our documentation for the dash.Dash settings. We've grouped these settings across different pages corresponding to their feature (e.g. dev tools settings would be in a debugging chapter, hot reloading settings are in the CSS chapter). Perhaps its time to create a central dash.Dash API reference page.

Implications for Community Forum

• We should update "is it possible to hide the floating toolbar" with the new default setting and instructions on how to turn it back on.

Will this break or change in the future? If so, how can we prepare?

I don't think so. In the future, I could imagine that these buttons could be more configurable so that users could include them in a more thoughtful position in their app (e.g. in a centralized header or footer). Perhaps they would be dcc.Undo and dcc.Redo components. Setting show_undo_redo = False should not affect this.

Can this be done in a backwards compatible way instead?

No.

Are there any other risks to consider?

I don't think so.

Beyond the communication policy outlined in #458, are there any other ways
that we can inform our users about this change?

We should create a new community forum topic outlining the change and specifying how turn this back on.

Can we automate the upgrade process for our users?

No.

Is there anything to consider with respect to compatibility between
components?

No.

If something breaks, can we inform users through an error message in any
way?

No.

Are there any open items?

• PRs that make this change: add show_undo_redo config option, default false #724

Breaking Change 5 - Update how the initialization callbacks work if properties aren't supplied

This has been deferred until later

For more details, see #468

A few technical issues need to be resolved in #468 before we can consider folding this into the 1.0.0 release. If these issues can't be resolved in a timely matter, then we will likely push this fix to the 2.0.0 series.

---

Thanks for reading ❤️ As always, we welcome your feedback in this issue or privately via a message on the dash community forum: https://community.plot.ly/u/chriddyp/

[T4rk1n]

Breaking Change 3 - Resource integrity checks for CDN resources

I found the implementation I made in #442 to be a little too dangerous, requires too much attention especially considering third parties components libraries. I'd like instead to add an option in the new cli #451 to generate the hashes and include them as a field in the dist. If the component doesn't have the field we just not include it in the tag formatting. That wouldn't be breaking change.

[T4rk1n]

It doesn't work if the component libraries aren't published to NPM.

Just remove the external_url from the dist and it will serve it locally even if it's not set. There is a flag (publish_on_npm) in the boilerplate to include it or not. Default is True.

Also, when debug=True and dev_tools_serve_dev_bundles=True dash will serve locally by default.

dash/dash/dash.py

Lines 1170 to 1172 in dcd0f41

	if debug and self._dev_tools.serve_dev_bundles:
	# Dev bundles only works locally.
	self.scripts.config.serve_locally = True

[T4rk1n]

If a flask route fails, then we could log it in the terminal. In dash==0.30.0, we silenced flask's route logging for 200 level requests, do we still log 4xx or 5xx errors in the terminal? Should we?

500 errors are mostly caused by users exception in routes, the stacktrace/error will still be displayed because the logging level is ERROR.

Something we could do instead of silencing the whole logging is to add a handler/filter and only emit the logs we want.

[chriddyp]

I think we should also consider removing animate=True from dcc.Graph in favor of the new transitions API - https://community.plot.ly/t/exploring-a-transitions-api-for-dcc-graph/15468

[rmarren1]

Perhaps we can remove events here as well?

[rmarren1]

dash/dash/dash.py

Lines 619 to 624 in 5ba0bc2

	# pylint: disable=unused-argument, no-self-use
	def react(self, *args, **kwargs):
	raise exceptions.DashException(
	'Yo! `react` is no longer used. \n'
	'Use `callback` instead. `callback` has a new syntax too, '
	'so make sure to call `help(app.callback)` to learn more.')

Maybe we can delete this too.

[ned2]

With the Dash assets machinery now in place, we could also drop the static_folder kwarg from the Dash __init__ method. It's now redundant, and if someone really needs it, they can pass in their own Flask instance configured accordingly.