v6.0.0

TL;DR: InstUI 6. New CLI tool makes upgrading easy. Codemods are even better. Goodbye React 0.14. Shake your trees and use named imports.

InstUI 6 is here, and it has a few fun surprises.

InstUI 6 should be the easiest upgrade in the history of InstUI. We documented all of the breaking changes in components that would occur; most changes are simply the removal of deprecated code. If you’ve fixed all of your console warnings, upgrading to InstUI 6 should be smooth sailing.

💲 instui-cli

Smoother sailing than ever, in fact, thanks to the new INSTUI CLI TOOL:


With npx

$ cd your-repository

$ npx @instructure/instui-cli upgrade --version 6


Globally installing with yarn or npm

$ npm install -g @instructure/instui-cli

  # or
  yarn global add @instructure/instui-cli

$ cd your-repository

$ instui upgrade --version 6

Every InstUI package in your repository is updated to 6.0, and all of the codemods necessary to remove deprecated props and packages are run effortlessly.

With future releases, you can use instui upgrade for all of your InstUI upgrading needs, even for minor and patch versions. If you’re in a hurry and want to skip running codemods, instui upgrade-packages is also available, but we encourage you to just use instui upgrade every time to help you catch deprecations earlier.

The instui CLI is going to continue to grow and improve. We’d love to hear your ideas for what we can do with it.

🔀 Codemods are Cooler

Speaking of codemods, we’ve made a number of improvements to how they work.

• The patterns that codemods use are now stored in a separate package — instui-config — improving versioning and testing the changes we’re making to your code.

• Deprecations now reference the version at which we’re going to remove the deprecated code. That way, if you see a deprecation, you know how long you can still rely on that feature.

• Our Babel transpile will now output full paths to cross-package imports for CommonJS output and named (member) exports/imports for ES module output. See “Transforming Imports with ui-babel-preset” below to learn more about this change.


🛠 The Stuff We Know You’ll Have to Fix

Try as we might, there are a few places the codemods just won’t fix. If you aren’t seeing deprecation warnings about these in the console before the upgrade, you’re all set. If you upgrade without fixing these, you’ll get warnings and who knows what else might happen.

• Icons using the deprecated width and height props are going to break if you don’t switch to the size prop. We can’t change that one because the width/height props accepted magic numbers like 10px, but size only accepts named sizes like large.

• Alert and Img have props that changed in both name and type. If you’ve used a literal value for those props, our updated codemods will catch them. However, if you’ve used a variable or an invoked function, you’ll have to fix it yourself. For example, the codemod will change <Img cover={true} /> to <Img constrain="cover" />, but <Img cover={variable} /> would result in <Img constrain={variable} />. In the latter case only the prop name would be updated, not the variable value. The tables below outline the 6.0 equivalents for deprecated props if they need to be updated manually.


<Alert/>

Deprecated	6.0 Equivalent
transitionType="fade"	transition={true}
transitionType="none"	transition={false}

<Img/>

Deprecated	6.0 Equivalent
cover={true}	constrain="cover"
cover={false}	constrain={undefined}

Also, as we announced back in January, the variants of a Tooltip have changed. Though you won’t see any errors, there may be aesthetic contrast issues to resolve.

👋 So Long, React 0.14

InstUI 6 drops support for React 0.14. No one at Instructure is using it, so it was a safe choice. (InstUI 7 will drop support for React 15, but that’s another blog post.)

🌳 Tree Shaking and Webpack 4

All instructure-ui modules now provide a named export, and cross-package dependencies no longer reference the full /lib path. This means if you are using Webpack 4, you can convert default imports to named member imports and leverage tree shaking for smaller bundle sizes.

The default exports still exist for each component; however, we will likely remove the default exports in a future release to encourage usage of named member imports. With named member imports everyone gets the benefits of tree shaking as well as better IDE code refactoring and IntelliSense functionality.

🧙‍♂️ Transforming Imports with ui-babel-preset

If you are using @instructure/ui-babel-preset, it will now transform import paths by default, and you will need to opt-out of the transform. ⚠️ We do not recommend opting out unless you can be sure that all of your instructure-ui imports are consistent across your codebase—otherwise you will risk pulling in duplicates of instructure-ui modules.


// babel.config.js
module.exports = {
  presets: [[
    require(‘@instructure/ui-babel-preset’),
    {
      transformImports: true
      // ...
    }
  ]]
}

This will convert any non-default imports that are referencing the package only to reference the full path to the module instead. For example:

// a named member import:

import { Text } from '@instructure/ui-elements'

would be converted to

// a named import using the full module path:

import { Text } from '@instructure/ui-elements/lib/Text'

Note that any default imports you are currently using will not be transformed:


Import Text from '@instructure/ui-elements/lib/Text'

Why is this useful?


For Webpack 4 users

While you were previously able to use both import styles, mixing them in a single application can cause duplication of imported modules along with other potentially erroneous results. A single import style should be used. The babel transform standardizes import paths to ensure consistency and smaller bundle sizes.

For Webpack 3 users

The transform will save you some keystrokes by allowing you to do a named member import from the instructure-ui packages without having to specify the full module path, and you can start getting set up to do tree shaking when you are able to upgrade webpack, without increasing your JS bundle size. For example, you can do:

// a named member import:

import { Avatar } from '@instructure/ui-elements'

instead of:

// a named import with the full module path:

import { Avatar } from '@instructure/ui-elements/lib/Avatar'

or:

// a default import with the full module path:

import Avatar from '@instructure/ui-elements/lib/Avatar'

…and babel will make all of the paths consistent when your bundle is generated.