Start upgrade

Upgrade preparation

Install Semi 2.0

npm i @douyinfe/semi-ui@2.0.0

Modify code

1. Install the automatic upgrade tool globally:

npm i @ies/semi-codemod-v2@latest -g // bnpm registry

2. Use semi-codemod-v2 to scan the project code and automatically modify breaking changes

semi-codemod-v2 <ProjectPath> [options]

//  options:
//    --dry,        Dry run (no changes are made to files)   
//    --force,      Whether ignore git status;               
//    --verbose=2,  Log level, optional: 0/1/2, default: 0   

// Result output description
Results:
  0 errors       // The number of files in which the conversion rule was executed but an error occurred during the replacement process
  13 unmodified  // The number of files that comply with the matching rule but have not been modified (that is, the component is used, but the related obsolete API is not involved)
  158 skipped    // The number of skipped files that do not meet the matching rule
  4 ok           // A total of 4 files meet the replacement rules, and the cli has been automatically modified
Time elapsed: 5.398seconds

3. For the part that can be recognized but cannot be automatically modified, codemod will prompt on the command line and throw a warning. You need to suggest to modify manually according to the prompts

All warning logs will be output in the semi-codemod-log.log file under ProjectPath, and you can check and modify them one by one according to the log.

4. Update the usage of Css Variable

• Install Semi style-lint package

# set npm registry as bnpm
npm i -D @ies/stylelint-semi@2.0.0-alpha.1

• create or update .stylelintrc.json file

{
  "plugins": ["@ies/stylelint-semi"],
  "rules": {
    "semi/css-token-migrate": [true, { "severity": "warning" }]
  }
}

• CSS Token updated from 1.x to 2.x

# "**/*.scss" or other files and directories. The tool can process files in JSX, TSX, CSS, SCSS, LESS and other formats files
npx stylelint "**/*.scss" --fix    // Upgrade CSS variables in inline style in SCSS
npx stylelint "**/*.tsx" --fix     // Upgrade CSS variables in inline style in tsx
npx stylelint "**/*.jsx" --fix     // Upgrade CSS variables in inline style in jsx

Automatic replacement depends on stylelint, only replaces the color variables in the style file or style attribute (the quoted value will not be replaced), it is recommended to search globally after the replacement, where there is no clean replacement

// replace '--amber-0' to '--semi-amber-0'
const searchReg = /--((amber|black|blue|cyan|green|grey|indigo|light|lime|orange|pink|purple|red|teal|violet|yellow|white|color|shadow|overlay|border|gray)(-[a-z\d]+)*)/;
const replaceReg = /--semi-$1/;

5. Update the theme package

6. Run your project for dev build. Modify the code segment that throws the error

7. Execute git diff review all code changes and return to related pages

What are the incompatible changes in 2.0

🎁 Package name adjustment

🔍 Import path change

Import components

// before
import { Select, Input, Form } from '@ies/semi-ui-react';

// now
import { Select, Input, Form } from '@douyinfe/semi-ui';

Import interface（TypeScript project）

// before
import { SelectProps } from '@ies/semi-ui-react/select' 

// now
import { SelectProps } from '@douyinfe/semi-ui/lib/es/select'

Import locale language packages

// before
import en_GB from '@ies/semi-ui-react/locale/source/en_GB'

// now
import en_GB from '@douyinfe/semi-ui/lib/es/locale/source/en_GB'

🛠 API related adjustments

• Icon related
  • Icon component no longer supports type = xxx using built-in icons
  • Custom svg no longer supports plug-in configuration srcSvgPaths
  • The Button icon and iconType property no longer supports passing built-in icon names through strings
  • Dropdown deletes the iconType attribute and unifies it into the icon attribute
  • Navigation icon no longer support incoming by string, ReactNode needs to be passed in
  • Notification icon are no longer passed in by string, please use ReactNode uniformly
  • Banner icon、closeIcon are no longer passed in by string, please use ReactNode uniformly
  • Typography.Text icon are no longer passed in by string, please use ReactNode uniformly
  • Breadcrumb.Item icon are no longer passed in by string, please use ReactNode uniformly
• AutoComplete officially discards the onChangeWithObject property
• Remove onInputChange from Cascader triggerRender
• Form no longer exports Label components from semi-ui/index.js
• Tree onRightClick renamed onContextMenu
• Upload dragable renamed draggable
• Tooltip no longer supports the disabled attribute, and components that rely on Tooltip (such as Popover, Dropdown, etc.) transparently transmitted to Tooltip disabled will become invalid
• Table
  • API that no longer responds when componentDidUpdate
    • defaultExpandAllRows, please replace with expandAllRows
    • defaultExpandRowKeys, please replace with expandRowKeys
    • defaultExpandAllGroupRows, please replace with expandAllGroupRows

🎨 Style incompatibility

• CSS variable with semi prefix, for example --color-primary = > --semi-color-primary
  • Users who use Semi CSS Variable to implement features such as dark mode need to update the variables in custom CSS uniformly
  • Users who do not use Semi CSS Variable in custom components or pages need not pay attention and are not affected
• In 2.x, the unified set the width and height of the illustration to 200 * 200px. If you want to simulate the width and height of 1.x, you can set style = {{width: 300, height: 150}} to the illustration.
• The common className of the Icon component is changed from semi-icons to semi-icon, aligning component names

Plugin adjustment

• Svg related
  • The iconLazyLoad, svgPaths, srcSvgPaths configurations are no longer supported.
• Dark mode related
  • Local dark mode and bright mode no longer need to configure themeScope attributes in the plug-in, and the default is built-in. The usage method is updated from adding id #semi-ways-xxx to adding class .semi-ways-xxx.

Other adjustments

Icon/Illustration use adjustment

// 1.x default iconLazyload is false
<Icon type="home" />;

// 1.x when iconLazyload is true
import homeSvg from '@ies/semi-icons/semi-icons-home.svg';
<Icon type={homeSvg.id} />;

// 2.x use the following methods uniformly
import { IconHome } from '@douyinfe/semi-icons';
<IconHome />;

// 1.x
import { Empty } from '@ies/semi-ui-react';
import Construction from '@ies/semi-illustrations/construction.svg';
<Empty image={Construction} />

// 2.x
import { Empty } from '@douyinfe/semi-ui';
import { IllustrationConstruction } from '@douyinfe/semi-illustrations';
<Empty image={<IllustrationConstruction />} />

Design Token adjustment

FAQ

Why has the reference path changed?

The project wants to upgrade to 2.0, but the Semi material is used in the project. The material is based on 1.x Semi. Can it be used at the same time?

Why do CSS variables add semi prefixes?

Why is the local dark/bright mode changed from add id to add class?

Why has the size of the illustration changed?

Encounter problems