From ee5a8beca14463d35ad445e32003e454a1f155d6 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E5=81=8F=E5=8F=B3?= Date: Thu, 22 Dec 2016 14:24:50 +0800 Subject: [PATCH] Add doc about using antd with create-react-app (#4294) * Add doc about using antd with create-react-app, close #2526 * translate to english * update comment * update --- docs/react/customize-theme.en-US.md | 2 +- docs/react/customize-theme.zh-CN.md | 2 +- docs/react/i18n-solution.en-US.md | 2 +- docs/react/i18n-solution.zh-CN.md | 2 +- docs/react/practical-projects.en-US.md | 2 +- docs/react/use-with-create-react-app.en-US.md | 194 ++++++++++++++++++ docs/react/use-with-create-react-app.zh-CN.md | 194 ++++++++++++++++++ 7 files changed, 393 insertions(+), 5 deletions(-) create mode 100644 docs/react/use-with-create-react-app.en-US.md create mode 100644 docs/react/use-with-create-react-app.zh-CN.md diff --git a/docs/react/customize-theme.en-US.md b/docs/react/customize-theme.en-US.md index b2f6de2ffc..c74f6c6db8 100644 --- a/docs/react/customize-theme.en-US.md +++ b/docs/react/customize-theme.en-US.md @@ -1,5 +1,5 @@ --- -order: 4 +order: 5 title: Customize Theme --- diff --git a/docs/react/customize-theme.zh-CN.md b/docs/react/customize-theme.zh-CN.md index bd38b7fc33..d050f29461 100644 --- a/docs/react/customize-theme.zh-CN.md +++ b/docs/react/customize-theme.zh-CN.md @@ -1,5 +1,5 @@ --- -order: 4 +order: 5 title: 定制主题 --- diff --git a/docs/react/i18n-solution.en-US.md b/docs/react/i18n-solution.en-US.md index 2099ba5bf7..41798c1ebe 100644 --- a/docs/react/i18n-solution.en-US.md +++ b/docs/react/i18n-solution.en-US.md @@ -1,5 +1,5 @@ --- -order: 5 +order: 6 title: i18n Solution link: //github.com/ant-design/intl-example --- diff --git a/docs/react/i18n-solution.zh-CN.md b/docs/react/i18n-solution.zh-CN.md index 4904375c3c..e5fe22c8fc 100644 --- a/docs/react/i18n-solution.zh-CN.md +++ b/docs/react/i18n-solution.zh-CN.md @@ -1,5 +1,5 @@ --- -order: 5 +order: 6 title: i18n 方案 link: //github.com/ant-design/intl-example --- diff --git a/docs/react/practical-projects.en-US.md b/docs/react/practical-projects.en-US.md index 1218453db1..62910fb02b 100644 --- a/docs/react/practical-projects.en-US.md +++ b/docs/react/practical-projects.en-US.md @@ -1,6 +1,6 @@ --- order: 3 -title: Practical Projects +title: Real world Example with dva --- [dva](https://github.com/dvajs/dva) is a React and redux based, lightweight and elm-style framework, which supports side effects, hot module replacement, dynamic on demand, react-native, SSR. And it has been widely used in production environment. diff --git a/docs/react/use-with-create-react-app.en-US.md b/docs/react/use-with-create-react-app.en-US.md new file mode 100644 index 0000000000..3a57138673 --- /dev/null +++ b/docs/react/use-with-create-react-app.en-US.md @@ -0,0 +1,194 @@ +--- +order: 4 +title: Use with create-react-app +--- + +[create-react-app](https://github.com/facebookincubator/create-react-app) is one of best React application development tool, we are going to use `antd` within it and modify the webpack config for some customized needs. + +--- + +## Install and Initialization + +We need to install `create-react-app` first. + +```bash +$ npm install -g create-react-app +``` + +Create a new project named `antd-demo`. + +```bash +$ USE_YARN=no create-react-app antd-demo +``` + +The tool will create and initialize environment and dependencies automaticly, +please try config your proxy setting or use other npm registry if any network errors happen during it. + +Then we go inside `antd-demo` and start it. + +```bash +$ cd antd-demo +$ npm start +``` + +Open browser at http://localhost:3000/, it renders a header saying "Welcome to React" on the page. + +## Import antd + +It is the default directory structure below. + +``` +├── README.md +├── package.json +├── public +│   ├── favicon.ico +│   └── index.html +├── src +│   ├── App.css +│   ├── App.js +│   ├── App.test.js +│   ├── index.css +│   ├── index.js +│   └── logo.svg +└── yarn.lock +``` + +Now we install `antd` from npm. + +```bash +$ npm install antd --save +``` + +Modify `src/App.js`, import Button component from `antd`. + +```jsx +import React, { Component } from 'react'; +import { Button } from 'antd'; +import './App.css'; + +class App extends Component { + render() { + return ( +
+ +
+ ); + } +} + +export default App; +``` + +Add `antd/dist/antd.css` at the top of `src/App.css`. + +```css +@import '~antd/dist/antd.css'; + +.App { + text-align: center; +} + +... +``` + +Ok, you now see a blue primary button displaying in page now, next you can choose any components of `antd` to develop your application. Visit other workflow of `create-react-app` at its [User Guide ](https://github.com/facebookincubator/create-react-app/blob/master/packages/react-scripts/template/README.md). + + +## Advanced Guides + +We are successd to run antd components now, but in the real world, there are still lots of problems about antd-demo. +For instance, we actully import all components in the project which will be a serious network perfermance issue. + +> You will see a warning in your browser console. + +![](https://zos.alipayobjects.com/rmsportal/dBLScZPjiUwunfyQVISX.png) + +So it is necessary to customize the default webpack config. We can achieve that by using `eject` script command. + +```bash +$ npm run eject +``` + +### Import on demand + +After eject all config files to antd-demo, we allowed to install [babel-plugin-import](https://github.com/ant-design/babel-plugin-import) and modify `src/webconfig.dev.js` now. + +```bash +$ npm install babel-plugin-import --save-dev +``` + +```diff +// Process JS with Babel. +{ + test: /\.(js|jsx)$/, + include: paths.appSrc, + loader: 'babel', + query: { ++ plugins: [ ++ ['import', [{ libraryName: "antd", style: 'css' }]], ++ ], + // This is a feature of `babel-loader` for webpack (not Babel itself). + // It enables caching results in ./node_modules/.cache/babel-loader/ + // directory for faster rebuilds. + cacheDirectory: true + } +}, +``` + +Remove the `@import '~antd/dist/antd.css';` statement added before because `babel-plugin-import` will import styles. + +Then reboot `npm start` and visit demo page, you should find that the above warning message would be gone which prove the `import on demand` config is effective now. + +### Customize Theme + +According to [Customize Theme documentation](/docs/react/customize-theme), we need `less` variables modify ability of [less-loader](https://github.com/webpack/less-loader), so we add it. + +```bash +$ npm install less less-loader --save-dev +``` + +```diff +loaders: [ + { + exclude: [ + /\.html$/, + /\.(js|jsx)$/, ++ /\.less$/, + /\.css$/, + /\.json$/, + /\.svg$/ + ], + loader: 'url', + }, + +... + + // Process JS with Babel. + { + test: /\.(js|jsx)$/, + include: paths.appSrc, + loader: 'babel', + query: { + plugins: [ +- ['import', [{ libraryName: "antd", style: 'css' }]], ++ ['import', [{ libraryName: "antd", style: true }]], // import less + ], + }, + +... + ++ // Parse less files and modify variables ++ { ++ test: /\.less$/, ++ loader: 'style!css!postcss!less?{modifyVars:{"@primary-color":"#1DA57A"}}' ++ }, +] +``` + +We use `modifyVars` option of [less-loader](https://github.com/webpack/less-loader#less-options) here, you can see a green button rendered on the page after reboot start server. + +--- + +Finally, we use antd with create-react-app successfully, you can learn these practice for your own webpack workflow too, and find more webpack config in the [atool-build](https://github.com/ant-tool/atool-build/blob/master/src/getWebpackCommonConfig.js). + +Source code about this article：https://github.com/ant-design/create-react-app-antd diff --git a/docs/react/use-with-create-react-app.zh-CN.md b/docs/react/use-with-create-react-app.zh-CN.md new file mode 100644 index 0000000000..1c4f50cd03 --- /dev/null +++ b/docs/react/use-with-create-react-app.zh-CN.md @@ -0,0 +1,194 @@ +--- +order: 4 +title: 在 create-react-app 中使用 +--- + +[create-react-app](https://github.com/facebookincubator/create-react-app) 是业界最优秀的 React 应用开发工具之一，本文会尝试在 create-react-app 创建的工程中使用 antd 组件，并自定义 webpack 的配置以满足各类工程化需求。 + +--- + +## 安装和初始化 + +我们需要在命令行中安装 create-react-app 工具。 + +```bash +$ npm install -g create-react-app +``` + +然后新建一个项目。 + +```bash +$ USE_YARN=no create-react-app antd-demo +``` + +工具会自动初始化一个脚手架并安装 React 项目的各种必要依赖，如果在过程中出现网络问题，请尝试配置代理或使用其他 npm registry。 + +然后我们进入项目并启动。 + +```bash +$ cd antd-demo +$ npm start +``` + +此时浏览器会访问 http://localhost:3000/ ，看到 `Welcome to React` 的界面就算成功了。 + +## 引入 antd + +这是 create-react-app 生成的默认目录结构。 + +``` +├── README.md +├── package.json +├── public +│   ├── favicon.ico +│   └── index.html +├── src +│   ├── App.css +│   ├── App.js +│   ├── App.test.js +│   ├── index.css +│   ├── index.js +│   └── logo.svg +└── yarn.lock +``` + +现在从 npm 安装并引入 antd。 + +```bash +$ npm install antd --save +``` + +修改 `src/App.js`，引入 antd 的按钮组件。 + +```jsx +import React, { Component } from 'react'; +import { Button } from 'antd'; +import './App.css'; + +class App extends Component { + render() { + return ( +
+ +
+ ); + } +} + +export default App; +``` + +修改 `src/App.css`，在文件顶部引入 `antd/dist/antd.css`。 + +```css +@import '~antd/dist/antd.css'; + +.App { + text-align: center; +} + +... +``` + +好了，现在你应该能看到页面上已经有了 antd 的蓝色按钮组件，接下来就可以继续选用其他组件开发应用了。其他开发流程你可以参考 create-react-app 的[官方文档](https://github.com/facebookincubator/create-react-app/blob/master/packages/react-scripts/template/README.md)。 + +## 高级配置 + +我们现在已经把组件成功运行起来了，但是在实际开发过程中还有很多问题，例如上面的例子实际上加载了全部的 antd 组件的代码（对前端性能是个隐患）。 + +> 你会在控制台看到如下警告。 + +![](https://zos.alipayobjects.com/rmsportal/dBLScZPjiUwunfyQVISX.png) + +我们需要对 create-react-app 的默认配置进行自定义。可以使用 `eject` 命令将所有内建的配置暴露出来。 + +```bash +$ npm run eject +``` + +### 按需加载 + +现在可以安装 [babel-plugin-import](https://github.com/ant-design/babel-plugin-import) 并修改 `src/webconfig.dev.js` 文件。 + +```bash +$ npm install babel-plugin-import --save-dev +``` + +```diff +// Process JS with Babel. +{ + test: /\.(js|jsx)$/, + include: paths.appSrc, + loader: 'babel', + query: { ++ plugins: [ ++ ['import', [{ libraryName: "antd", style: 'css' }]], ++ ], + // This is a feature of `babel-loader` for webpack (not Babel itself). + // It enables caching results in ./node_modules/.cache/babel-loader/ + // directory for faster rebuilds. + cacheDirectory: true + } +}, +``` + +然后移除前面在 `src/App.css` 里全量添加的 `@import '~antd/dist/antd.css';` 样式代码，现在 babel-plugin-import 会按需加载样式。 + +最后重启 `npm start` 访问页面，此时上面的警告信息应该没了，antd 组件的 js 和 css 代码都会按需加载。 + +### 自定义主题 + +按照 [配置主题](/docs/react/customize-theme) 的要求，自定义主题需要用到 less 变量覆盖功能，因此首先我们需要引入 [less-loader](https://github.com/webpack/less-loader) 来加载 less 样式，同时修改 `src/webconfig.dev.js` 文件。 + +```bash +$ npm install less less-loader --save-dev +``` + +```diff +loaders: [ + { + exclude: [ + /\.html$/, + /\.(js|jsx)$/, ++ /\.less$/, + /\.css$/, + /\.json$/, + /\.svg$/ + ], + loader: 'url', + }, + +... + + // Process JS with Babel. + { + test: /\.(js|jsx)$/, + include: paths.appSrc, + loader: 'babel', + query: { + plugins: [ +- ['import', [{ libraryName: "antd", style: 'css' }]], ++ ['import', [{ libraryName: "antd", style: true }]], // 加载 less 文件 + ], + }, + +... + ++ // 解析 less 文件，并加入变量覆盖配置 ++ { ++ test: /\.less$/, ++ loader: 'style!css!postcss!less?{modifyVars:{"@primary-color":"#1DA57A"}}' ++ }, +] +``` + +这里利用了 [less-loader](https://github.com/webpack/less-loader#less-options) 的 `modifyVars` 来进行主题配置， +变量和其他配置方式可以参考 [配置主题](/docs/react/customize-theme) 文档。 + +修改后重启 `npm start`，如果看到一个绿色的按钮就说明配置成功了。 + +--- + +以上是在 create-react-app 中使用 antd 的相关实践，你也可以借鉴此文的做法在自己的 webpack 工作流中使用 antd，更多 webpack 配置可参考 [atool-build](https://github.com/ant-tool/atool-build/blob/master/src/getWebpackCommonConfig.js)。 + +本例源码可见：https://github.com/ant-design/create-react-app-antd