npm VS Yarn
在本項目我們使用Yarn管理項目三方依賴,不過放心,Yarn和NPM不衝突,也不是要替代NPM,使用方式基本一致,只需要簡單瞭解以下幾點。
三方庫版本管理
npm 和 Yarn 都使用 package.json
來跟蹤項目的依賴,版本號並非一直準確,因爲你可以定義版本號範圍,npm的不同更新範圍,可能導致在擁有相同 package.json
文件的機器上安裝不同版本包,這可能導致一些差異的異常和衝突。
那npm有解決方式嘛?npm中可以使用 npm shrinkwrap
生成一個版本鎖文件npm-shrinkwrap.json
,在 npm install
時會在讀取 package.json
前先讀取這個文件,但是當更新包版本時,版本鎖文件並不會自動更新,我們得手動再次執行npm shrinkwrap
命令更新它。
那麼Yarn有什麼優勢呢?每次添加或更新安裝庫包時,Yarn 都會創建(或更新)yarn.lock
文件,這樣可以確保所有機器安裝相同版本包,同時支持 package.json
中定義的允許版本範圍,和npm的區別在於Yarn總會自動更新 yarn.lock
,而npm需要手動更新。
併發安裝
npm通常是按順序一個一個安裝依賴,而Yarn支持並行加載安裝多個三方庫包,所有其速度和效率都更快。
離線緩存
使用Yarn管理包時,三方庫包存放在本地磁盤,下次安裝將直接使用本地文件而不是再次下載,這也從另一方面使其安裝速度優於npm。
簡而言之就是,Yarn和npm使用方式幾乎一樣,但是其版本管理更方便,安裝速度更快,更有優勢,但是實際上它的所有三方庫包加載地址和npm都是統一的。
Webpack
我們使用Webpack打包工具作爲項目的自動化構建工具,將JavaScript,CSS,圖片等資源都當作JavaScript模塊(使用Webpack loader處理轉換)進行統一管理,關於Webpack博主之前總結過兩篇文章,可以參考:
有了前文的鋪墊,本文就不打算展開介紹Webpack的工作原理和具體配置,而計劃從項目實踐開發和測試,打包層面思考如何更好的組織Webpack,如何使用Webpack提告項目開發,打包效率。
Webpack配置文件
首先我們在根目錄下創建webpack.config.js
配置文件:
module.exports = function () {
let env
let _DEV_ = true // 開發環境
let _PROD_ = false // 生產環境
switch (process.env.NODE_ENV) {
case 'dev':
env = 'dev'
_DEV_ = true
_PROD_ = false
break
case 'production':
env = 'prod'
_DEV_ = false
_PROD_ = true
break
default:
env = 'dev'
_DEV_ = true
_PROD_ = false
}
// 根據環境參數動態決定引入對應配置文件
return require(`./webpack/${env}.conf.js`)({
ROOTPATH: __dirname,
_DEV_,
_PROD_
})
}
根據process.env.NODE_ENV
環境參數動態決定加載對應配置文件:
dev
:加載webpack/env.conf.js
配置文件;prod
:加載webpack/prod.conf.js
配置文件;
我們在項目根目錄下創建了webpack
目錄,其內創建了三個配置文件:
base.conf.js
:基礎配置文件,在開發,生產環境都需要的配置;dev.conf.js
:開發環境配置文件;prod.conf.js
:生產環境打包配置文件;
開發環境配置
開發環境配置文件中定義了一些開發使用的構建配置,然後引入基礎配置文件,使用webpack-merge
三方庫,將開發環境配置合併至基礎配置對象,然後返回開發環境打包構建配置對象,作爲Webpack打包構建的參數:
const webpackMerge = require('webpack-merge')
const PUBLICPATH = '/assets/'
const PORT = '9090'
let options = { /* ... */ }
module.exports = function (args) {
options.ROOTPATH = args.ROOTPATH
options.env = args.env
return webpackMerge(require('./base.conf')(options), {
devtool: 'source-map',
devServer: {
contentBase: path.join(args.ROOTPATH, './src'),
historyApiFallback: true,
inline: true,
hot: true,
port: PORT,
proxy: {
'*': `http://localhost:${PORT}/${PUBLICPATH}/`
}
},
plugins: []
})
}
生產環境配置
生產環境配置文件中定義了的是生產環境使用的構建配置,然後也是引入基礎配置文件,使用webpack-merge
三方庫,將生產環境配置合併至基礎配置,然後返回配置對象,作爲Webpack打包構建的參數:
let options = { /* ... */}
module.exports = function (args) {
options.ROOTPATH = args.ROOTPATH
options.env = args.env
return webpackMerge(require('./base.conf')(options), {
plugins: [
new webpack.DefinePlugin({
'process.env': 'production'
}),
// 生成獨立css文件
new ExtractTextPlugin({
filename: 'css/[name].css'
}),
new webpack.optimize.UglifyJsPlugin({
compress: {
warnings: false
}
})
]
})
}
指令
然後就是爲不同環境配置可執行指令,我們使用npm scripts
方式,在package.json
文件中配置執行指令:
{
"scripts": {
"start": "cross-env NODE_ENV=dev webpack-dev-server",
"build": "cross-env NODE_ENV=production webpack"
}
}
start
:開發環境運行指令,使用cross-env
三方庫設置process.env.NODE_ENV
爲dev
,並在本地開啓webpack開放服務器,方便開放;build
:生產環境運行指令,使用cross-env
三方庫設置process.env.NODE_ENV
爲production
,將打包輸出代碼和資源文件;
最後分別執行yarn start
和yarn build
指令即可分別執行開發和生產構建打包了。
Babel
可自定義配置型的通用編譯器,需要明確指定期望babel做什麼,通過安裝**插件(plugins)或預設(presets,也就是一組插件)**來指示 Babel 去做什麼事情。
配置文件
首先需要創建一個配置文件,即在項目的根路徑下創建 .babelrc
文件。然後輸入以下內容作爲開始:
{
"presets": [],
"plugins": []
}
之後就可以拓展這個配置文件以指定此項目中 Babel 的功能。
babel-preset-es2015
我們期望在項目中能使用更新潮的ES6版本語法,但由於目前還有許多JavaScript環境不能很好兼容ES6,所以需要Babel將ES6代碼編譯成ES5語法代碼,保證應用的使用範圍。
執行如下命令,安裝 "es2015" Babel 預設:
yarn add --dev babel-preset-es2015
修改.babelrc
配置文件:
{
"presets": [
"es2015"
],
"plugins": []
}
babel-preset-stage-num
另外,JavaScript還有一些提案,正在推進,不久的將來也可能成爲標準的一部分,所以目前將這些草案提出,內容更新直至最終成爲標準,添加進標準庫的過程劃分爲 5(0-4)個階段。 根據提案的狀態和內容,將其在各個階段更新(階段0至階段3),最終在階段 4表明該提案被標準正式採納,當然不被採納的提案不會進入階段4。
以下是4個不同階段的打包預設:
babel-preset-stage-0
babel-preset-stage-1
babel-preset-stage-2
babel-preset-stage-3
注: stage-4 預設不存在,它其實就是上文介紹的 es2015
預設。
以上每種預設都包含緊隨的後期階段預設,同時還可能包含其他額外特性。例如,babel-preset-stage-0
包含 babel-preset-stage-1
, babel-preset-stage-2
,babel-preset-stage-3
,而 babel-preset-stage-1
則包含 babel-preset-stage-2
,babel-preset-stage-3
依次後推。
我們次選擇支持特性最全面的預設:
yarn add --dev babel-preset-stage-0
在.babelrc
配置文件內添加:
{
"presets": [
"es2015",
"stage-0"
],
"plugins": []
}
babel-preset-react
我們的項目期望使用React開發,所以需要拓展支持React/JSX語法,安裝預設:
yarn add --dev babel-preset-react
.babelrc
配置文件內添加:
{
"presets": [
"es2015",
"stage-0",
"react"
],
"plugins": []
}
babel-polyfill
至此,使用Babel,我們的·項目幾乎可以支持所有的ES6及ES7語法,但是對於新增的JavaScript API是無能爲力的,如Symbol
這種新API,並不是通過語法轉換能實現的,所以我們需要另外的方式解決。
業內提出了Polyfill(填充),以添加額外代碼的方式使得當前運行環境支持不存在的原生Api ,拓展了尚處在推進階段的API的使用範圍。
yarn add babel-polyfill
此處不需要添加--dev
參數。
然後在文件入口引入即可:
import "babel-polyfill";
babel-runtime
前面提到的Babel通過轉換語法以支持我們以ES6等更新的語法方式開發代碼,這時Babel會在每一個處理的文件頭部注入輔助代碼,會產生很多冗餘,重複性的內容,導致代碼量暴增,所以我們需要將這些輔助代碼抽取至一個統一環境,Babel提供的就是運行時(runtime)環境。
要實現Babel運行時環境,需要安裝 babel-plugin-transform-runtime
和 babel-runtime
:
yarn add --dev babel-plugin-transform-runtime babel-runtime
然後更新 .babelrc
:
{
"plugins": [
"transform-runtime",
]
}
按需加載(babel-plugin-import)
很多時候,我們開發業務並不需要自制UI,會選擇一些開源組件庫以快速開發實現產品,如antd,weui,material-ui等,我們可以選擇直接提前加載三方庫所有模塊,但是很多時候我們希望能實現按需加載,減少初始代碼包的體積,這時,我們可以在babel配置文件中聲明按需加載該第三方庫,當然首先得安裝插件babel-plugin-import
:
yarn add --dev babel-plugin-import
然後在配置文件.babelrc
中添加配置:
{
"plugins": [
"import",
{
"style": "../styles", // 加載樣式解析方式,(值爲true時,可能是less/Sass),此處值設爲相對libraryName具體模塊請求路徑值
"libraryDirectory": "", // 加載包的目錄,(默認是lib,即node_modules/lib/)
"libraryName": "material-ui" // 加載三方組件庫名,當然另外需要安裝該三方庫
}
]
}
此時,webapck loader處理css時不能添加exclude: /node_modules/
。
其他插件
我們還可以根據項目實際需求和愛好自定義安裝插件,更多信息查看官方插件文檔。
在這裏推薦一款babel-pliugin-transform-s2015-classes
插件拓展以實現JavaScript內置class對象的extends
繼承特性,參考文檔ES2015 classes transform。
yarn add --dev babel-plugin-transform-es2015-classes
在.babelrc
文件內添加plugins內容:
{
"plugins": [
"transform-runtime",
"transform-es2015-classes",
[
"import",
{
"style": "css",
"libraryDirectory": "",
"libraryName": "material-ui"
}
]
]
}
語法檢測(Eslint)
爲了保證代碼質量,統一代碼風格是很重要的,而只靠團隊口頭約定明顯是不能盡如人意,所以通常需要在自動化構建層面進行代碼語法檢測,有很多語法檢測工具如jslint,eslint,目前使用率最高的要數eslint了,所以我們的項目也引入eslint,首先安裝依賴:
yarn add --dev eslint
更多細節參考配置文檔,下文簡要介紹主要。
配置文件
然後在項目根目錄下建立eslint配置文件.eslintrc
,內容是一個對象:
{}
解析器(parser)
另外,ESLint 默認使用Espree作爲其解析器,你可以在配置文件中指定一個不同的解析器,如babel-eslint,esprima等,我們項目使用babel-eslint:
yarn add --dev babel-eslint
在配置文件內添加parser
屬性:
{
"parser": "babel-eslint"
}
eslint-plugin-babel
eslint還支持可選安裝插件,拓展eslint,如eslint-plugin-babel
,該插件與babel-eslint
協作,使得eslint可以更好的與babel同時工作,更多請查看參考文檔。
yarn add --dev eslint-plugin-babel
在配置文件添加聲明:
{
"plugins": [
"babel"
],
}
aslant-plugin-react
eslint默認是檢測JavaScript語言語法的,而對於React/JSX這類包含其自定義語法和語法糖的框架而言,需要另外拓展安裝插件才能和eslint結合使用,所以使用eslint檢測React特定語法需要安裝eslint-plugin-react
插件:
yarn add --dev eslint-plugin-react
添加配置文件:
{
"plugins": [
"babel",
"react"
]
}
拓展(extends)
除了自定義語法檢查規則外,我們可以使用Eslint提供的集成拓展包,使用共享的語法檢測配置對象,如eslint-config-standard
和eslint-config-standard-react
:
yarn add --dev eslint-config-standard eslint-config-standard-react eslint-plugin-standard eslint-plugin-promise eslint-plugin-import eslint-plugin-node eslint-plugin-react
注:這裏包含了上一小節提到的eslint-plugin-react是爲了支持eslint-config-standard-react配置包。
然後在.eslintrc
配置文件中添加拓展:
{
"extends": [
"standard",
"standard-react"
]
}
若不想使用這類集成語法檢測規則,可以移除配置文件中內容並移除依賴:
yarn remove eslint-config-standard eslint-config-standard-react eslint-plugin-standard eslint-plugin-promise eslint-plugin-import eslint-plugin-node eslint-plugin-react
語法規則(rules)
要添加語法規則,只需要聲明在rules
屬性對象中,如:
{
"rules": {
"strict": 0,
"semi": 2, // 強制語句末尾添加符號,否則報錯
"quotes": [
1,
"single"
],
}
}
規則結構
當聲明語法檢測規則時,需要設置規則 ID爲以下值之一:
"off"
或0
- 關閉規則"warn"
或1
- 開啓規則,使用警告級別的錯誤:warn
(不會導致程序退出)"error"
或2
- 開啓規則,使用錯誤級別的錯誤:error
(當被觸發的時候,程序會退出)
{
"rules": {
eqeqeq: 0, // or "off"
curly: 2 // or "error"
}
}
某些規則還可能有額外的配置選項,可以使用數組指定,如:
{
"rules": {
"eqeqeq": "off",
"curly": "error",
"quotes": ["warn", "single"] // 開啓使用單引號,若使用雙引號將發出警告
}
}
指令
要執行語法檢測,只需要執行./node_modules/.bin/eslint src
(項目本地安裝eslint,而非全局安裝,則需要指定執令腳本路徑),將會遍歷檢查src
目錄下的所有源碼文件語法並輸出結果,當然我們最終需要將指令根據npm scripts
規範插入package.json
文件:
{
"scripts": {
"lint": "eslint --cache --fix src"
}
}
使用npm scripts執行指令時,無論項目本地安裝還是全局安裝,都可以省略指令腳本路徑,因爲npm將自動匹配可用路徑。
文檔
一個優秀的項目當然少不了文檔,文檔可以幫助其他開發者快速瞭解整個項目內容及進度,也有助於bug修復時查找內容,追蹤溯源,所以文檔是有必要的,於是通過調研發現了JSdoc和documentation.js幫助自動化產出API文檔。
documentation
和JSdoc一樣,documentation也是根據代碼註釋自動構建出項目文檔,前提是我們的代碼註釋必須按照其規範指南,詳情參考JSdoc文檔。
我們首先安裝documentation.js:
yarn add --dev documentation
指令
然後可以執行指令:
./node_modules/.bin/documentation build src/app.js -f md > API.md
會發現在根目錄輸出了API.md文件。
我們在package.json文件中配置npm scripts
執行腳本:
"scripts": {
"doc": "./node_modules/.bin/documentation build src/app.js -f md > API.md"
}
項目本地安裝documentation時,直接在命令行終端執行指令時需要指定./node_modules/.bin/documentation
路徑,若全局安裝則只可直接使用documentation
指令。而執行package.json中的腳步,可以直接簡寫,npm將爲我們自動匹配。