# cjet 前端工程构建工具
`cjet` 致力于使用 React 技术栈以系统性、组件化、标准化的过程方法开发和维护企业级应用软件。确保前端开发人员能够快速在 React 生态中将各种基础工具以零配置的方式与企业级业务需求的开发平稳衔接，让研发人员更专注于开发业务逻辑上，同时提供灵活的配置，以适合不同类型和规模的企业级应用。
## 快速开始
##### 1、确保你的项目为以下结构
```bash
project
├── package.json
└── src
├── index.html
└── index.js
```
对于要构建的项目，这些文件必须以确切的文件名存在：
- `src/index.html` 是 index 页面的模版
- `src/index.js` 是 index 页面的 javascript 入口
##### 2、在项目中安装 `cjet`
```bash
yarn add cjet -D # 或者 npm install cjet --save-dev
```
##### 3、添加 script 配置
- package.json 配置
```json
{
"scripts": {
"dev": "cjet dev",
"build": "cjet build"
}
}
```
## 执行命令
```bash
yarn dev #或者 npm run dev
```
在本地构建 Node 开发服务器，脱离 nginx、apache 等后台服务的依赖，实时编译前端的各种资源，并且在开发过程中任何文件的更改，都会自动更新浏览器，实时查看修改效果。你还将在控制台中看到任何 lint 错误。
```bash
yarn build #或者 npm run build
```
将生产应用程序构建到 dist 文件夹。它能将 React 代码智能地打包为生产模式中并优化构建以获得最佳性能。构建文件将被压缩，文件名中将包含哈希。
## 构建多页应用
`cjet` 支持构建多页面应用。如果你开发的项目是多页应用，请在`src/pages`以目录名存放每个页面内容。
```bash
project
├── package.json
└── src
├── pages
│ ├── demo1
│ │ ├── index.html
│ │ └── index.js
│ └── demo2
│ ├── index.html
│ └── index.js
├── index.html
└── index.js
```
## `cjet` 配置文件
在项目根目录新建`cjet.config.js`
```js
module.exports = {
html: {
/**
* 启用 preload
* 构建项目自动加入preload方案
*/
preload: true,
/**
* 启用 prefetch
* 构建项目自动加入prefetch方案
*/
prefetch: true,
},
/**
* -------------------------------
* 样式编译器配置
* -------------------------------
*/
style: {
/**
* css配置
* https://github.com/webpack-contrib/css-loader
*/
cssOptions: {},
/**
* less配置
* https://github.com/webpack-contrib/less-loader
*/
lessOptions: {},
/**
* sass配置
* https://github.com/webpack-contrib/sass-loader
*/
sassOptions: {},
/**
* stylus配置
* https://github.com/shama/stylus-loader
*/
stylusOptions: {},
/**
* style sourceMap
*/
sourceMap: false,
},
/**
* SVG symbol图标方案配置
* 配置参考：https://github.com/kisenka/svg-sprite-loader#configuration
*/
svgSprite: {
options: {
symbolId: "icon-[name]", //symbolId和use使用的名称
},
},
/**
* eslint 配置
*/
eslint: {
available: true, //开启eslint
cache: true, //启用配置缓存，如果新配置不起作用请先设置为false
useEslintrc: false, //使用项目中eslintrc配置
extends: [], //默认使用的eslint规则
},
/**
* -------------------------------
* 路径配置
* -------------------------------
*/
paths: {
appPath: ".",
appSrc: "src", //源码目录，非src目录中的代码不做编译
appBuild: "dist", //生产目录
appPublic: "public", //静态资源目录
appIndexHtml: "src/index.html", //默认首页模板
appIndexJs: "src/index", //默认首页脚本文件
appPages: "src/pages", //多页面存放目录
svgIconPath: "src/icons", //svg 图标存放目录
proxySetup: "src/setupProxy.js", //proxy代理配置文件
appTypeDeclarations: "src/react-app-env.d.ts", //ts环境变量配置文件
},
/**
* PWA的workbox-webpack-plugin配置
* More info see: https://developers.google.com/web/tools/workbox/modules/workbox-webpack-plugin
*/
pwa: {
mode: "GenerateSW", // GenerateSW or InjectManifest
options: {
clientsClaim: true,
exclude: [/\.map$/, /asset-manifest\.json$/],
importWorkboxFrom: "cdn",
navigateFallback: "/index.html",
navigateFallbackBlacklist: [
// Exclude URLs starting with /_, as they're likely an API call
new RegExp("^/_"),
// Exclude any URLs whose last part seems to be a file extension
// as they're likely a resource and not a SPA route.
// URLs containing a "?" character won't be blacklisted as they're likely
// a route with query params (e.g. auth callbacks).
new RegExp("/[^/?]+\\.[^/]+$"),
],
},
},
/**
* typescript配置
*/
tsconfig: {
rewrite: true, //是否使用框架内部最佳实践覆盖项目中的tsconfig.json
},
};
```
## 支持的浏览器和特性
默认情况下，使用 `cjet` 构建的项目支持所有现代浏览器。 如果你的项目想支持 Internet Explorer 9 , 10 和 11 ， 请自行引入[polyfills](https://github.com/facebook/create-react-app/blob/master/packages/react-app-polyfill/README.md)。
`cjet` 支持最新 JavaScript 标准的超集。 除了 ES6 语法功能外，它还支持：
- 指数运算符 (ES2016).
- Async/await (ES2017).
- Object Rest(剩余)/Spread(展开) 属性 (ES2018).
- 动态 import() (stage 3 proposal)
- Class 字段和静态属性 (part of stage 3 proposal).
- JSX, Flow 和 TypeScript.
#### browserslist
在 `cjet` 构建的项目根目录 package.json 文件里的 browserslist 字段 (或一个单独的 .browserslistrc 文件)，指定了项目的目标浏览器的范围。这个值会被 `cjet` 工程工具来确定需要转译的 JavaScript 特性和需要添加的 CSS 浏览器前缀。具体配置可参考：[https://github.com/browserslist/browserslist](https://github.com/browserslist/browserslist);
## 开发环境
- **开发编辑器**
建议安装使用[Visual Studio Code](https://code.visualstudio.com/)编辑器，并安装[Prettier](https://marketplace.visualstudio.com/items?itemName=esbenp.prettier-vscode)和[editorConfig](https://marketplace.visualstudio.com/items?itemName=EditorConfig.EditorConfig) 代码风格及格式化、以及对应的文件代码高亮等插件。
- **编码规范**
`cjet` 默认已集成 eslint 在开发过程中进行代码风格和质量检查，默认使用 React 官方的[eslint-config-react-app](https://github.com/facebook/create-react-app/blob/master/packages/eslint-config-react-app/index.js)代码风格库，你也可以通过 `eslintrc` 手动配置自己团队的代码规范，或者扩展更多第三方的代码规范，如：[eslint-config-airbnb](https://github.com/airbnb/javascript);
- **热重载和实时检测代码错误**
编辑保存文件，页面将重新加载。还将在控制台中看到任何 lint 错误。
```bash
Compiled successfully!
+-------------------------------------------------------+
| |
| 欢迎使用cjet前端React工程构建工具 |
| |
| You can now view chanjet-mobile in the browser. |
| |
| - Local: http://localhost:8080/ |
| - Network: http://10.1.145.16:8080/ |
| |
| Note that the development build is not optimized. |
| To create a production build, use yarn build. |
| |
| More info see:https://github.com/chanjet-fe/cjet |
| |
+-------------------------------------------------------+
```
- **使用 Proxy 代理 API 请求**
对于开发前后端分离的项目，常常需要访问 api 服务器，请在 `package.json` 中添加 proxy 字段
```json
"proxy": "http://xxx.xxx.xxx.xxx:3000",
```
开发中使用 `fetch('/api/todos')` 时，开发服务器将识别出它不是静态资源，并将你的请求代理到`http://xxx.xxx.xxx.xxx:3000/api/todos`。开发服务器将 仅仅 尝试将 `Accept` 头中没有 `text/html` 的请求发送到代理。可以避免开发环境中的 [CORS(跨域)](https://developer.mozilla.org/zh-CN/docs/Web/HTTP/Access_control_CORS) issues 和错误消息，使用 `cjet` 的 `proxy` 选项支持 HTTP ，HTTPS 和 WebSocket 连接。
如果 `package.json` 文件中的 `proxy` 选项对你来说 不够 灵活，你可以直接访问 Express 应用程序实例，并连接你自己的代理中间件。
你可以将此功能与 `package.json` 中的 `proxy` 属性结合使用，但建议你将所有逻辑合并到 `src/setupProxy.js` 中。
首先，使用 npm 或 Yarn 安装 http-proxy-middleware ：
```bash
npm install http-proxy-middleware --save
# 或
yarn add http-proxy-middleware
```
创建 `src/setupProxy.js` 并将以下内容放入该文件中：
```js
//更多配置请参考：https://github.com/chimurai/http-proxy-middleware
const { createProxyMiddleware } = require("http-proxy-middleware");
module.exports = function (app) {
app.use(createProxyMiddleware("/api", { target: "http://localhost:5000/" }));
};
```
**使用 HTTPS**
开发过程中可能需要开发服务器通过 HTTPS 提供页面。 当 `API` 服务器本身为 `HTTPS` 服务时，使用 `proxy`（代理）功能 将请求代理到 `API` 服务器，请将 `HTTPS` 环境变量设置为 `true` ，然后像往常一样使用 `yarn dev` 启动开发服务器：
```bash
# Windows (cmd.exe)
set HTTPS=true&&npm start
# Windows (Powershell)
($env:HTTPS = "true") -and (npm start)
# Linux, macOS (Bash)
HTTPS=true npm start
```
服务器将使用自签名证书，所以 Web 浏览器在访问页面时基本上会显示警告。
## 样式开发
- **使用 CSS**
`cjet` 工程使用 Webpack 处理样式资源，要表明 JavaScript 文件依赖于某个 CSS 文件，你需要 在 JavaScript 文件中导入 CSS
**Button.css**
```css
.Button {
padding: 20px;
}
```
**Button.js**
```js
import React, { Component } from "react";
import "./Button.css"; // 告诉 Webpack Button.js 使用这些样式
class Button extends Component {
render() {
// 你可以将它们用作常规 CSS 样式
return ;
}
}
```
但是这样开发容易造成变量命名的冲突，尤其多人合作开发复杂项目，将会尤为严重。
- **使用 CSSModule**
`cjet` 工程工具支持 `[name].module.css` 文件命名约定支持 [CSS Modules](https://github.com/css-modules/css-modules) 和常规 CSS 。 CSS Modules 允许通过自动创建 `[filename]\_[classname]\_\_[hash]` 格式的唯一 classname 来确定 CSS 的作用域。CSS Modules 允许你在不同的文件中使用相同的 CSS classname，而无需担心命名冲突。 你可以[了解有关 CSS Modules 的更多信息](https://css-tricks.com/css-modules-part-1-need/)。
**Button.module.css**
```css
.error {
background-color: red;
}
```
**another-stylesheet.css**
```css
.error {
color: red;
}
```
**Button.js**
```js
import React, { Component } from "react";
import styles from "./Button.module.css"; // 将 css modules 文件导入为 styles
import "./another-stylesheet.css"; // 导入常规 CSS 文件
class Button extends Component {
render() {
// 作为 js 对象引用
return ;
}
}
```
最终编译结果不会和其他 `.error` 类名冲突
```html