在上一篇文章《基于 @vue/cli3 与 koa 建立 ssr 工程》中,咱们讲解了如何基于 @vue/cli3
建立一个 ssr 工程。javascript
在本篇文章,咱们来建立一个 @vue/cli3
插件,并将第一篇文章中 ssr 工程的服务器端部分整合进插件中。css
首先,咱们来看一个 cli3
插件提供了那些功能:html
@vue/cli-service
提供统一的自定义命令,例如: vue-cli-service ssr:build
除了上述两个功能外,咱们还但愿在插件内部整合服务端逻辑,这样对于多个接入插件的工程项目能实行统一的管理,方便后续统一增长日志、监控等功能。前端
官方对于发布一个 cli3
的插件作了以下限制vue
为了让一个 CLI 插件可以被其它开发者使用,你必须遵循 vue-cli-plugin-<name>
的命名约定将其发布到 npm
上。插件遵循命名约定以后就能够:java
@vue/cli-service
发现;vue add <name>
或 vue invoke <name>
安装下来。所以,咱们新建并初始化一个工程 createPluginExample
,并将工程的 name
命名为 vue-cli-plugin-my_ssr_plugin_demo
node
mkdir createPluginExample && cd createPluginExample && yarn init
复制代码
package.json 的内容为:webpack
{
"name": "vue-cli-plugin-my_ssr_plugin_demo",
"version": "1.0.0",
"main": "index.js",
"license": "MIT"
}
复制代码
官方对于第一个插件功能,引入了一个叫作 Generator
的机制来实现web
Generator
有两种展示形式:generator.js
或 generator/index.js
vue-router
generator.js
或 generator/index.js
的内容导出一个函数,这个函数接收三个参数,分别是:
GeneratorAPI
实例generator
选项preset
的内容关于 preset
,咱们能够将其看做是:将手动建立一个工程项目过程当中,经过会话选择的自定义选项内容保存下来的预设文件
例如:
module.exports = (api, options, rootOptions) => {
// 修改 `package.json` 里的字段
api.extendPackage({
scripts: {
test: 'vue-cli-service test'
}
})
// 复制并用 ejs 渲染 `./template` 内全部的文件
api.render('./template')
if (options.foo) {
// 有条件地生成文件
}
}
复制代码
以及两种安装方式:
preset
中被安装vue invoke
独立调用时被安装Generator
容许在文件夹 generator
中建立一个叫作 template
的文件夹
若是在 generator/index.js
中显式调用了 api.render('./template')
,
那么 generator
将会使用 EJS
渲染 ./template
中的文件,并替换工程中根目录下对应的文件。
由于咱们的 ssr
工程项目须要对默认的 spa
工程中的部分文件作一些改造(详见上一篇文章《基于 @vue/cli3 与 koa 建立 ssr 工程》)
因此在这里咱们选择 generator/index.js
这种展示形式。
并在 generator
中建立文件夹 template
并将第一篇文章中已经改造好的文件放置在 ./template
文件夹中。
此时,咱们的 createPluginExample
工程目录结构以下:
.
├── generator
│ ├── index.js
│ └── template
│ ├── src
│ │ ├── App.vue
│ │ ├── components
│ │ │ └── HelloWorld.vue
│ │ ├── entry-client.js
│ │ ├── entry-server.js
│ │ ├── main.js
│ │ ├── router
│ │ │ ├── index.js
│ │ ├── store
│ │ │ ├── index.js
│ │ │ └── modules
│ │ │ └── book.js
│ │ └── views
│ │ ├── About.vue
│ │ └── Home.vue
│ └── vue.config.js
└── package.json
复制代码
接下来让咱们看 generator/index.js
中的内容
咱们须要在 generator/index.js
作三件事情:
ssr
工程模式自定义工程的 package.json
的内容api.render('./template')
触发 generator
使用 EJS
渲染 generator/template/
中的文件,并替换工程中根目录下对应的文件关于第一件事情
首先咱们须要在建立工程项目后,自动建立好基于 ssr
的一些命令,好比服务器端构建 ssr:build
,开发环境启动 ssr
服务 dev
其次,咱们还须要在建立工程项目后,自动安装好 ssr
依赖的某些第三方工具,例如:concurrently
第二件事件比较简单,咱们这里直接按照官方文档写就能够。
关于第三件事情:
spa
工程会在 src
下生成 router.js
、store.js
这些文件,而插件在安装过程当中不会删除掉这些文件,所以咱们须要在工程安装完毕后,清理这些文件。ssr:build
命令就须要在产品环境下执行了,所以咱们须要将咱们的插件 vue-cli-plugin-my_ssr_plugin_demo
, 以及 @vue/cli-plugin-babel
、@vue/cli-service
, 由 devDependencies
中移动到 dependencies
中。public/index.ejs
么,由于这个文件自己就是 ejs
格式的,因此在插件安装过程当中渲染 generator/template
文件夹中的内容时,会影响到它,因此咱们将其放在 generator/
文件夹下,在安装过程结束后,将其复制到工程的 public
中最终,generator/index.js
的内容以下:
const shell = require('shelljs')
const chalk = require('chalk')
module.exports = (api, options, rootOptions) => {
// 修改 `package.json` 里的字段
api.extendPackage({
scripts: {
'serve': 'vue-cli-service serve',
'ssr:serve': 'NODE_ENV=development TARGET_NODE=node PORT=3000 CLIENT_PORT=8080 node ./app/server.js',
'dev': 'concurrently \'npm run serve\' \'npm run ssr:serve\'',
'build': 'vue-cli-service build && TARGET_NODE=node vue-cli-service build --no-clean --silent',
'start': 'NODE_ENV=production TARGET_NODE=node PORT=3000 node ./node_modules/vue-cli-plugin-my_ssr_plugin_demo/app/server.js'
},
dependencies: {
},
devDependencies: {
'concurrently': '^4.1.0'
}
})
// 复制并用 ejs 渲染 `./template` 内全部的文件
api.render('./template', Object.assign({ BASE_URL: '' }, options))
api.onCreateComplete(() => {
shell.cd(api.resolve('./'))
shell.exec('cp ./node_modules/vue-cli-plugin-my_ssr_plugin_demo/generator/tmp.ejs ./public/index.ejs')
shell.exec('rm ./public/index.html')
shell.exec('rm ./public/favicon.ico')
const routerFile = './src/router.js'
const storeFile = './src/store.js'
console.log(chalk.green('\nremove the old entry file of vue-router and vuex'))
shell.exec(` echo \n\n if [ -f ${routerFile} ];then rm -f ${routerFile} fi if [ -f ${storeFile} ];then rm -f ${storeFile} fi `)
let packageJson = JSON.parse(shell.exec('cat ./package.json', { silent: true }).stdout)
const needToMove = [
'@vue/cli-plugin-babel',
'@vue/cli-service',
'vue-cli-plugin-my_ssr_plugin_demo'
]
needToMove.forEach(name => {
if (!packageJson.devDependencies[name]) return
packageJson.dependencies[name] = packageJson.devDependencies[name]
delete packageJson.devDependencies[name]
})
console.log(chalk.green(`move the ${needToMove.join(',')} from devDependencies to dependencies`))
shell.exec(`echo '${JSON.stringify(packageJson, null, 2)}' > ./package.json`)
})
}
复制代码
接下来咱们来看服务器端部分
在第一篇文章中,咱们将服务器端的逻辑都存放在 app/
文件夹中
app
├── middlewares
│ ├── dev.ssr.js
│ ├── dev.static.js
│ └── prod.ssr.js
└── server.js
复制代码
咱们只须要将此文件夹复制到插件工程的根目录下,而后在根目录下建立一个名为 index.js
的文件。
在 index.js
文件中,咱们会作以下三件事情:
vue.config.js
中的配置整合进插件中,也就是 index.js
中提供的 api.chainWebpack
内部,这样作的好处是安装此插件的工程项目没必要再关心 ssr
相关的 webpack
配置细节ssr
服务的命令: ssr:serve
ssr
服务 bundle 的命令: ssr:build
当调用 vue-cli-service <command> [...args]
时会建立一个叫作 Service
的插件。
Service
插件负责管理内部的 webpack
配置、暴露服务和构建项目的命令等, 它属于插件的一部分。
一个 Service
插件导出一个函数,这个函数接收两个参数:
PluginAPI
实例vue.config.js
内指定的项目本地选项的对象Service
插件针对不一样的环境扩展/修改内部的 webpack
配置,并向 vue-cli-service
注入额外的命令,例如:
module.exports = (api, projectOptions) => {
api.chainWebpack(webpackConfig => {
// 经过 webpack-chain 修改 webpack 配置
})
api.configureWebpack(webpackConfig => {
// 修改 webpack 配置
// 或返回经过 webpack-merge 合并的配置对象
})
api.registerCommand('test', args => {
// 注册 `vue-cli-service test`
})
}
复制代码
在这里,咱们将第一篇中的 vue.config.js
中的内容移到 index.js
中的 api.chainWebpack
里
const get = require('lodash.get')
const VueSSRServerPlugin = require('vue-server-renderer/server-plugin')
const VueSSRClientPlugin = require('vue-server-renderer/client-plugin')
const nodeExternals = require('webpack-node-externals')
const merge = require('lodash.merge')
module.exports = (api, projectOptions) => {
const clientPort = get(projectOptions, 'devServer.port', 8080)
api.chainWebpack(config => {
const TARGET_NODE = process.env.WEBPACK_TARGET === 'node'
const DEV_MODE = process.env.NODE_ENV === 'development'
if (DEV_MODE) {
config.devServer.headers({ 'Access-Control-Allow-Origin': '*' }).port(clientPort)
}
config
.entry('app')
.clear()
.add('./src/entry-client.js')
.end()
// 为了让服务器端和客户端可以共享同一份入口模板文件
// 须要让入口模板文件支持动态模板语法(这里选择了 TJ 的 ejs)
.plugin('html')
.tap(args => {
return [{
template: './public/index.ejs',
minify: {
collapseWhitespace: true
},
templateParameters: {
title: 'spa',
mode: 'client'
}
}]
})
.end()
// Exclude unprocessed HTML templates from being copied to 'dist' folder.
.when(config.plugins.has('copy'), config => {
config.plugin('copy').tap(([[config]]) => [
[
{
...config,
ignore: [...config.ignore, 'index.ejs']
}
]
])
})
.end()
// 默认值: 当 webpack 配置中包含 target: 'node' 且 vue-template-compiler 版本号大于等于 2.4.0 时为 true。
// 开启 Vue 2.4 服务端渲染的编译优化以后,渲染函数将会把返回的 vdom 树的一部分编译为字符串,以提高服务端渲染的性能。
// 在一些状况下,你可能想要明确的将其关掉,由于该渲染函数只能用于服务端渲染,而不能用于客户端渲染或测试环境。
config.module
.rule('vue')
.use('vue-loader')
.tap(options => {
merge(options, {
optimizeSSR: false
})
})
config.plugins
// Delete plugins that are unnecessary/broken in SSR & add Vue SSR plugin
.delete('pwa')
.end()
.plugin('vue-ssr')
.use(TARGET_NODE ? VueSSRServerPlugin : VueSSRClientPlugin)
.end()
if (!TARGET_NODE) return
config
.entry('app')
.clear()
.add('./src/entry-server.js')
.end()
.target('node')
.devtool('source-map')
.externals(nodeExternals({ whitelist: /\.css$/ }))
.output.filename('server-bundle.js')
.libraryTarget('commonjs2')
.end()
.optimization.splitChunks({})
.end()
.plugins.delete('named-chunks')
.delete('hmr')
.delete('workbox')
})
复制代码
接下来让咱们建立开发环境启动 ssr
服务的命令: ssr:serve
const DEFAULT_PORT = 3000
...
api.registerCommand('ssr:serve', {
description: 'start development server',
usage: 'vue-cli-service ssr:serve [options]',
options: {
'--port': `specify port (default: ${DEFAULT_PORT})`
}
}, args => {
process.env.WEBPACK_TARGET = 'node'
const port = args.port || DEFAULT_PORT
console.log(
'[SSR service] will run at:' +
chalk.blue(` http://localhost:${port}/ `)
)
shell.exec(` PORT=${port} \ CLIENT_PORT=${clientPort} \ CLIENT_PUBLIC_PATH=${projectOptions.publicPath} \ node ./node_modules/vue-cli-plugin-my_ssr_plugin_demo/app/server.js \ `)
})
...
module.exports.defaultModes = {
'ssr:serve': 'development' // 为 ssr:serve 指定开发环境模式
}
复制代码
最后,咱们建立产品环境构建 ssr
服务 bundle 的命令: ssr:build
const onCompilationComplete = (err, stats) => {
if (err) {
console.error(err.stack || err)
if (err.details) console.error(err.details)
return
}
if (stats.hasErrors()) {
stats.toJson().errors.forEach(err => console.error(err))
process.exitCode = 1
}
if (stats.hasWarnings()) {
stats.toJson().warnings.forEach(warn => console.warn(warn))
}
}
...
api.registerCommand('ssr:build', args => {
process.env.WEBPACK_TARGET = 'node'
const webpackConfig = api.resolveWebpackConfig()
const compiler = webpack(webpackConfig)
compiler.run(onCompilationComplete)
shell.exec('node ./node_modules/vue-cli-plugin-my_ssr_plugin_demo/bin/initRouter.js')
})
...
module.exports.defaultModes = {
'ssr:build': 'production', // 为 ssr:build 指定产品环境模式
'ssr:serve': 'development'
}
复制代码
最终,完整的 index.js
内容以下:
const webpack = require('webpack')
const get = require('lodash.get')
const VueSSRServerPlugin = require('vue-server-renderer/server-plugin')
const VueSSRClientPlugin = require('vue-server-renderer/client-plugin')
const nodeExternals = require('webpack-node-externals')
const merge = require('lodash.merge')
const shell = require('shelljs')
const chalk = require('chalk')
const DEFAULT_PORT = 3000
const onCompilationComplete = (err, stats) => {
if (err) {
console.error(err.stack || err)
if (err.details) console.error(err.details)
return
}
if (stats.hasErrors()) {
stats.toJson().errors.forEach(err => console.error(err))
process.exitCode = 1
}
if (stats.hasWarnings()) {
stats.toJson().warnings.forEach(warn => console.warn(warn))
}
}
module.exports = (api, projectOptions) => {
const clientPort = get(projectOptions, 'devServer.port', 8080)
api.chainWebpack(config => {
const TARGET_NODE = process.env.WEBPACK_TARGET === 'node'
const DEV_MODE = process.env.NODE_ENV === 'development'
if (DEV_MODE) {
config.devServer.headers({ 'Access-Control-Allow-Origin': '*' }).port(clientPort)
}
config
.entry('app')
.clear()
.add('./src/entry-client.js')
.end()
// 为了让服务器端和客户端可以共享同一份入口模板文件
// 须要让入口模板文件支持动态模板语法(这里选择了 TJ 的 ejs)
.plugin('html')
.tap(args => {
return [{
template: './public/index.ejs',
minify: {
collapseWhitespace: true
},
templateParameters: {
title: 'spa',
mode: 'client'
}
}]
})
.end()
// Exclude unprocessed HTML templates from being copied to 'dist' folder.
.when(config.plugins.has('copy'), config => {
config.plugin('copy').tap(([[config]]) => [
[
{
...config,
ignore: [...config.ignore, 'index.ejs']
}
]
])
})
.end()
// 默认值: 当 webpack 配置中包含 target: 'node' 且 vue-template-compiler 版本号大于等于 2.4.0 时为 true。
// 开启 Vue 2.4 服务端渲染的编译优化以后,渲染函数将会把返回的 vdom 树的一部分编译为字符串,以提高服务端渲染的性能。
// 在一些状况下,你可能想要明确的将其关掉,由于该渲染函数只能用于服务端渲染,而不能用于客户端渲染或测试环境。
config.module
.rule('vue')
.use('vue-loader')
.tap(options => {
merge(options, {
optimizeSSR: false
})
})
config.plugins
// Delete plugins that are unnecessary/broken in SSR & add Vue SSR plugin
.delete('pwa')
.end()
.plugin('vue-ssr')
.use(TARGET_NODE ? VueSSRServerPlugin : VueSSRClientPlugin)
.end()
if (!TARGET_NODE) return
config
.entry('app')
.clear()
.add('./src/entry-server.js')
.end()
.target('node')
.devtool('source-map')
.externals(nodeExternals({ whitelist: /\.css$/ }))
.output.filename('server-bundle.js')
.libraryTarget('commonjs2')
.end()
.optimization.splitChunks({})
.end()
.plugins.delete('named-chunks')
.delete('hmr')
.delete('workbox')
})
api.registerCommand('ssr:build', args => {
process.env.WEBPACK_TARGET = 'node'
const webpackConfig = api.resolveWebpackConfig()
const compiler = webpack(webpackConfig)
compiler.run(onCompilationComplete)
shell.exec('node ./node_modules/vue-cli-plugin-my_ssr_plugin_demo/bin/initRouter.js')
})
api.registerCommand('ssr:serve', {
description: 'start development server',
usage: 'vue-cli-service ssr:serve [options]',
options: {
'--port': `specify port (default: ${DEFAULT_PORT})`
}
}, args => {
process.env.WEBPACK_TARGET = 'node'
const port = args.port || DEFAULT_PORT
console.log(
'[SSR service] will run at:' +
chalk.blue(` http://localhost:${port}/ `)
)
shell.exec(` PORT=${port} \ CLIENT_PORT=${clientPort} \ CLIENT_PUBLIC_PATH=${projectOptions.publicPath} \ node ./node_modules/vue-cli-plugin-my_ssr_plugin_demo/app/server.js \ `)
})
}
module.exports.defaultModes = {
'ssr:build': 'production',
'ssr:serve': 'development'
}
复制代码
完整的 vue-cli-plugin-my_ssr_plugin_demo
目录结构以下:
.
├── app
│ ├── middlewares
│ │ ├── dev.ssr.js
│ │ ├── dev.static.js
│ │ └── prod.ssr.js
│ └── server.js
├── generator
│ ├── index.js
│ └── template
│ ├── src
│ │ ├── App.vue
│ │ ├── components
│ │ │ └── HelloWorld.vue
│ │ ├── entry-client.js
│ │ ├── entry-server.js
│ │ ├── main.js
│ │ ├── router
│ │ │ ├── index.js
│ │ ├── store
│ │ │ ├── index.js
│ │ │ └── modules
│ │ │ └── book.js
│ │ └── views
│ │ ├── About.vue
│ │ └── Home.vue
│ └── vue.config.js
├── index.js
└── package.json
复制代码
至此,咱们的 vue-cli-plugin-my_ssr_plugin_demo
插件就基本完成了
ssr
工程咱们使用脚手架建立一个新的 spa
工程
vue create myproject
复制代码
而后在工程内部安装插件
vue add vue-cli-plugin-my_ssr_plugin_demo
复制代码
安装完毕后,咱们就完成了 ssr
工程的初始化
在下一篇文章中,咱们重点来说如何基于咱们的 vue-cli-plugin-my_ssr_plugin_demo
插件,集成日志系统
水滴前端团队招募伙伴,欢迎投递简历到邮箱:fed@shuidihuzhu.com