代码改变世界

05.ElementUI源码学习:项目发布配置(github pages&npm package)

2021-04-27 22:39  Anduril  阅读(717)  评论(0编辑  收藏  举报

0x00.前言

书接上文。项目第一个组件已经封装好,说明文档也已编写好。下面需要将说明文档发布到外网上,以此来展示和推广项目,使用 Github Pages功能实现。同时将组件发布之 npm 上,方便直接在项目中安装使用。

0x01.Github Pages发布

进入项目的 Github repo,点击右上角的 Settings 选项。

微信截图_20210426160639.png

点击左侧菜单的 Pages 选项,右侧显示项目 Github Pages 初始配置。source 配置项值为 None 说明此功能尚未开启。

微信截图_20210426161236.png

点击 source 配置项下拉菜单,只有 master (主分支/默认分支)、None(关闭功能) 两个选项。

微信截图_20210426161933.png

root 路径

选择 master 分支后,可以指定发布文件源的路径,默认项目根路径/(root),还可以指定根路径下的docs文件夹;然后点击 Save 按钮保存,就会提示项目的发布地址 https://andurils.github.io/code-examples/

微信截图_20210426165638.png

打开网址若未成功解析,需要等待1-2分钟,再次刷新页面即可(当前根目录下只有readme.md文件,页面呈现内容为此文件)。

Animation12.gif

README.md 文件内容:

# 代码示例

## ElementUI 源码学习:从零开始搭建 Vue 组件库汇总

1. [0x01.项目初始化和 webpack 配置](https://juejin.cn/post/6950905030635421710)
2. [0x02.babel 配置](https://juejin.cn/post/6951215878928678948)
3. [03.ElementUI 源码学习:代码风格检查和格式化配置(ESlint & Prettier)](https://juejin.cn/post/6951808773354684447)
4. [04.ElementUI 源码学习:组件封装、说明文档的编写](https://juejin.cn/post/6953614014546968589)

docs 路径

作为一个开发分支根路径下放置发布文件,管理起来就比较混乱了,若不想维护新的分支用作静态网站发布,可以使用当前分支的 docs 路径,在配置里更改如下。
微信截图_20210427090129.png

创建 build\webpack.docs.js 文件,复制 build\webpack.config.js文件内容,修改 output/path属性值由 distdocs

module.exports = {
  ...
  output: {
    path: path.resolve(process.cwd(), 'docs'),
    ...
  },
  ...
}

package.json 文件中的 npm scripts添加新的编译命令,将组件说明文档打包至 docs 路径下。

...
"scripts": { 
    ...
    "build:docs": "cross-env NODE_ENV=development webpack --config  build/webpack.docs.js", 
    ...
},
...

至此将 docs 下的文件上传至 Github 即可。由于本项目路径为/learning-element2/step03,所以需要手动将 docs 内容复制至 Github 根目录下。Github Repo 最新目录结构如下:

├─docs
├─learning-element2
├─LICENSE 
├─README.md 

浏览器输入地址,打开页面效果如下:

Animation12.gif

gh-pages 分支

gh-pages 分支大家应该不陌生,按照早期的约定静态网站发布需要创建该分支,才能使用 Github Pages功能。接下将介绍如何快速的使用 gh-pages 进行项目发布。

先安装 gh-pages 插件, 在 npm scripts添加部署命令。

// 安装插件
npm install -D  gh-pages 

// package.json 添加部署命令
"scripts": {  
    "deploy": "gh-pages -d dist" 
}

然后编译打包项目 npm run build:dist, 最后运行部署命令npm run deploy 进行项目文档发布,发布成功控制台显示 Published
"deploy": "gh-pages -d dist"

微信截图_20210426133107.png

打开 Github Pages配置,此时选项里出现了 gh-pages ,选择该分支即可。

微信截图_20210427090211.png

gh-pages -d dist等同于创建了一个gh-pages分支并将 dist 文件内容提交至该分支。
同理可以在Git Repo 创建任何分支现在,直接通过配置可以指定具体的分支/路径(可以使用 mastergh-pages之外的任何分支)。

0x02.npm 发布组件包

webpack配置

安装编译进度条插件

npm i -D progress-bar-webpack-plugin

创建 build\webpack.common.js,采用 commonjs2 规范构建一个全量的包。

const path = require('path');
const ProgressBarPlugin = require('progress-bar-webpack-plugin');
const VueLoaderPlugin = require('vue-loader/lib/plugin');

const config = require('./config');

module.exports = {
  mode: 'production',
  entry: {
    app: ['./src/index.js'], // Entry descriptor  传入一个对象 ./src/index.js
  },
  output: {
    path: path.resolve(process.cwd(), './lib'), // 绝对路径
    publicPath: '/dist/', // 相对于服务(server-relative)
    filename: 'me-vue-ui.common.js',
    chunkFilename: '[id].js',
    library: { 
      type: 'commonjs2', //配置将库暴露的方式
      export: 'default', // 指定哪一个导出应该被暴露为一个库
    },
  },
  resolve: {
    extensions: ['.js', '.vue', '.json'],
    alias: config.alias,
    modules: ['node_modules'],
  },
  // externals: config.externals, //外部扩展
  performance: {
    // 控制 webpack 如何通知「资源(asset)和入口起点超过指定文件限制」
    hints: false, // 不展示警告或错误提示
  },
  // 可以在统计输出里指定你想看到的信息
  stats: {
    children: false, // 是否添加关于子模块的信息
  },
  optimization: {
    //告知 webpack 使用 TerserPlugin 或其它在 optimization.minimizer 定义的插件压缩 bundle
    minimize: false,
  },
  module: {
    rules: [
      {
        test: /\.(jsx?|babel|es6)$/,
        include: process.cwd(),
        exclude: config.jsexclude,
        loader: 'babel-loader',
      },
      {
        test: /\.vue$/,
        loader: 'vue-loader',
        options: {
          compilerOptions: {
            preserveWhitespace: false,
          },
        },
      },
      {
        test: /\.css$/,
        use: ['style-loader', 'css-loader'],
      },
      {
        test: /\.(svg|otf|ttf|woff2?|eot|gif|png|jpe?g)(\?\S*)?$/,
        loader: 'url-loader',
        options: {
          limit: 10000, 
          name: path.posix.join('static', '[name].[hash:7].[ext]'),
        },
      },
    ],
  },
  plugins: [new ProgressBarPlugin(), new VueLoaderPlugin()],
};

npm scripts添加组件打包命令,生成至 lib 目录下。

...
"scripts": { 
    ...
    "dist": "webpack --config build/webpack.common.js ",
    ...
},
...

输入命令 npm run dist 生成组件打包文件 lib\me-vue-ui.common.js

page11.gif

examples\main.js 文件中的组件引用 由 '../src/index' 替换成 '../lib/me-vue-ui.common'

// examples\main.js

// import MeUI from  '../src/index';
import MeUI from '../lib/me-vue-ui.common';

输入命令 npm run dev 运行项目,项目正常启动无错误,则组件打包成功。

npm 配置

配置 package.json 文件中属性值用于npm 发布。

  • name: 包名,该名字是唯一的。需要去npm registry查看名字是否已被使用。
  • version: 包版本号,版本号规则参考《语义化版本 2.0.0》。每次发布至 npm 需要修改版本号,不能和历史版本号相同。
  • description: 包的描述,描述这个包的主要功能以及用途。
  • main: 入口文件,该字段需指向项目编译后的包文件。
  • keyword:关键字,数组、字符串。
  • author:包的作者。
  • private:是否私有,需要修改为 false 才能发布到 npm
  • license: 开源协议。
  • repository:包的Git Repo信息,包括type和URL。
  • homepage:项目官网的url。

更新 package.json 文件内容。

{
  "name": "me-vue-ui",
  "version": "0.1.2",
  "description": "A Vue.js 2.X UI Toolkit for Web",
  "main": "lib/me-vue-ui.common.js",
  "keyword": [
    "me-vue",
    "vuejs",
    "components",
    "ui-kit"
  ], 
  "repository": {
    "type": "git",
    "url": "git+https://github.com/andurils/code-examples.git"
  },
  "author": "anduril",
  "license": "MIT",
  "homepage": "https://andurils.github.io/code-examples"
}

添加 .npmignore 文件,设置忽略发布文件。发布到 npm 中文件,只保留有的 lib 目录、package.json、README.md。

# 忽略目录
build/
dist/
examples/
packages/
public/
src/
test/
docs/

# 忽略指定文件 
.eslintignore
.prettierignore        
.eslintrc.js
.prettierrc.js 
babel.config.json   

更新README.md内容,会作为npm包的 Readme Tab选项内容发布。

微信截图_20210427210907.png

npm 发布

首先 npmjs.com 上注册一个账号,确保 npm 使用的是原镜像。

npm config set registry http://registry.npmjs.org 

然后在命令行窗口跳转至项目路径下, 运行 npm login 登录授权。

微信截图_20210427205726.png

执行 npm publish 命令发布组件包。

微信截图_20210427171347.png

发布成功后,进入组件包信息页面 https://www.npmjs.com/package/me-vue-ui, 可以看到上面的项目配置信息 。

微信截图_20210427211808.png

npm install 测试

使用vue cli 创建一个项目,引用刚发布的组件包。全局注册组件,页面引入组件,刷新页面即可看到发布的组件。

npm install me-vue-ui -S

操作效果如下:
page111111.gif

0x03.总结

从项目初始化到组件编写发布用了5篇文章的篇幅,耐心读完,你会发现很简单,没有想象中那么神秘高不可攀。由于前端技术的快速发展,版本的更迭,很多插件的配置让人头大。网络上的方案要不是玄学能用就行,为什么不知道;要么就是使用方法已经废弃。所以文章花了不少篇幅进行了知识梳理,也算是自我的一种回顾。也希望你有所收获!

接下来将对 element-ui 架构更进一步的拆解学习,一步步引入(copy)其工程化、组件、文档。

0x04.示例代码

Github Repo
npm demo

0x05.参考

Github Pages 发布配置
语义化版本 2.0.0
webpack配置