Nuxt.js 模块
模块是Nuxt.js扩展,可以扩展其核心功能并添加无限的集成。
介绍
在使用Nuxt开发应用程序时,您很快就会发现框架的核心功能还不够。 Nuxt可以使用配置选项和插件进行扩展,但是在多个项目中维护这些自定义是繁琐、重复和耗时的。 另一方面,开箱即用支持每个项目的需求将使Nuxt非常复杂且难以使用。
这就是Nuxt提供更高阶模块系统的原因,可以轻松扩展核心。 模块只是在引导Nuxt时按顺序调用的函数。 框架在加载之前等待每个模块完成。 如此,模块几乎可以自定义Nuxt的任何地方。 我们可以使用功能强大的 Hookable Nuxt.js系统来完成特定事件的任务。
最重要的是, Nuxt模块可以合并到npm包中。 这使得它们易于跨项目开发重用并与Nuxt社区共享, 我们可以创建一个高质量的Nuxt附加组件生态系统。
如果你:
- 是优秀团队的成员,需要快速引导新项目。
- 厌倦了为集成Google Analytics等常见任务重新造轮子。
- 是一个优秀的开源爱好者,希望轻松与社区分享您的工作。
- 是一家重视质量和可重用性的企业公司的成员。
- 通常是在短期限内完成,没有时间深入了解每个新库或集成的细节。
- 厌倦了处理对低级接口的重大改变,并且需要能够正常工作的东西。
Nuxt.js 模块列表
Nuxt.js 团队提供 官方 模块:
- @nuxt/http: 基于ky-universal的轻量级和通用的HTTP请求
- @nuxtjs/axios: 安全和使用简单Axios与Nuxt.js集成用来请求HTTP
- @nuxtjs/pwa: 使用经过严格测试,更新且稳定的PWA解决方案来增强Nuxt
- @nuxtjs/auth: Nuxt.js的身份验证模块,提供不同的方案和验证策略
Nuxt.js社区制作的模块列表可在 https://github.com/topics/nuxt-module 中查询
基本模块
如上所述,模块只是简单的功能。它们可以打包为npm模块或直接包含在项目源代码中。
modules/simple.js
export default function SimpleModule (moduleOptions) {
// Write your code here
}
// REQUIRED if publishing as an npm package
// module.exports.meta = require('./package.json')
moduleOptions
这是用户使用modules数组传递对象,我们可以使用它来定制它的行为。
this.options
您可以使用此属性直接访问Nuxt选项。这是nuxt.config.js,其中包含所有默认选项,可用于模块之间的共享选项。
this.nuxt
这是对当前Nuxt实例的引用。 请参考 Nuxt class docs for available methods.
this
modules中的context, 请参考 ModuleContainer 来查看可用的方法。
module.exports.meta
如果要将模块发布为npm包,则需要配置此选项。Nuxt内部使用meta来更好地处理您的包。
nuxt.config.js
export default {
modules: [
// Simple usage
'~/modules/simple'
// Passing options
['~/modules/simple', { token: '123' }]
]
}
然后,我们告诉Nuxt为项目加载一些特定模块,并将可选参数作为选项。 请参考 模块配置 文档来查看更多!
异步模块
并非所有模块都会同步完成所有操作,例如:您可能希望开发一个需要获取某些API或执行异步IO的模块。为此,Nuxt支持在异步模块中返回Promise或调用回调。
使用 async/await
请注意,仅在Node.js > 7.2中支持使用async / await。 因此,如果您是模块开发人员,至少要警告用户使用它们时Node.js版本不能低于7.2。 对于大量异步模块或更好的传统支持,您可以使用bundler将其转换为兼容较旧的Node.js版本或Promise方法。
import fse from 'fs-extra'
export default async function asyncModule () {
// You can do async works here using `async`/`await`
const pages = await fse.readJson('./pages.json')
}
返回 Promise
import axios from 'axios'
export default function asyncModule () {
return axios.get('https://jsonplaceholder.typicode.com/users')
.then(res => res.data.map(user => '/users/' + user.username))
.then((routes) => {
// Do something by extending Nuxt routes
})
}
使用回调
import axios from 'axios'
export default function asyncModule (callback) {
axios.get('https://jsonplaceholder.typicode.com/users')
.then(res => res.data.map(user => '/users/' + user.username))
.then((routes) => {
callback()
})
}
常见模块
优先级最高选项
有时在nuxt.config.js中注册模块时可以使用顶级选项更方便,这允许我们组合多个选项源。
nuxt.config.js
export default {
modules: [
['@nuxtjs/axios', { anotherOption: true }]
],
// axios module is aware of this by using `this.options.axios`
axios: {
option1,
option2
}
}
module.js
export default function (moduleOptions) {
const options = Object.assign({}, this.options.axios, moduleOptions)
// ...
}
提供插件
通常,模块在添加时需提供一个或多个插件。 例如:bootstrap-vue 模块需要将自己注册到Vue中。 为此我们可以使用 this.addPlugin 方法。
plugin.js
import Vue from 'vue'
import BootstrapVue from 'bootstrap-vue/dist/bootstrap-vue.esm'
Vue.use(BootstrapVue)
module.js
import path from 'path'
export default function nuxtBootstrapVue (moduleOptions) {
// Register `plugin.js` template
this.addPlugin(path.resolve(__dirname, 'plugin.js'))
}
模板插件
已注册的模板和插件可以利用lodash templates模板有条件地更改已注册插件的输出。
plugin.js
// Set Google Analytics UA
ga('create', '<%= options.ua %>', 'auto')
<% if (options.debug) { %>
// Dev only code
<% } %>
module.js
import path from 'path'
export default function nuxtBootstrapVue (moduleOptions) {
// Register `plugin.js` template
this.addPlugin({
src: path.resolve(__dirname, 'plugin.js'),
options: {
// Nuxt will replace `options.ua` with `123` when copying plugin to project
ua: 123,
// conditional parts with dev will be stripped from plugin code on production builds
debug: this.options.dev
}
})
}
添加CSS库
考虑是否存在CSS库以避免重复,并添加一个选项来禁用模块中的CSS库。请参见下面的示例。
module.js
export default function (moduleOptions) {
if (moduleOptions.fontAwesome !== false) {
// Add Font Awesome
this.options.css.push('font-awesome/css/font-awesome.css')
}
}
Emit assets
我们可以注册webpack插件用来在构建期间发出资源。
module.js
export default function (moduleOptions) {
const info = 'Built by awesome module - 1.3 alpha on ' + Date.now()
this.options.build.plugins.push({
apply (compiler) {
compiler.plugin('emit', (compilation, cb) => {
// This will generate `.nuxt/dist/info.txt' with contents of info variable.
// Source can be buffer too
compilation.assets['info.txt'] = { source: () => info, size: () => info.length }
cb()
})
}
})
}
注册自定义 loaders
我们可以使用this.extendBuild在nuxt.config.js中执行与build.extend相同的操作。
module.js
export default function (moduleOptions) {
this.extendBuild((config, { isClient, isServer }) => {
// `.foo` Loader
config.module.rules.push({
test: /\.foo$/,
use: [...]
})
// Customize existing loaders
// Refer to source code for Nuxt internals:
// https://github.com/nuxt/nuxt.js/tree/dev/packages/builder/src/webpack/base.js
const barLoader = config.module.rules.find(rule => rule.loader === 'bar-loader')
})
}
在指定钩子上运行任务
您的模块可能只需要在特定条件下执行操作,而不仅仅是在Nuxt初始化期间。我们可以使用强大的Tapable插件来执行特定事件的任务。Nuxt将等待钩子返回Promise或被定义为async(异步)。
export default function () {
// Add hook for modules
this.nuxt.hook('module', (moduleContainer) => {
// This will be called when all modules finished loading
})
// Add hook for renderer
this.nuxt.hook('renderer', (renderer) => {
// This will be called when renderer was created
})
// Add hook for build
this.nuxt.hook('build', async (builder) => {
// This will be called once when builder created
// We can even register internal hooks here
builder.hook('compile', ({ compiler }) => {
// This will be run just before webpack compiler starts
})
})
// Add hook for generate
this.nuxt.hook('generate', async (generator) => {
// This will be called when a Nuxt generate starts
})
}
Module package commands
实验性的
从v2.4.0 开始,您可以通过Nuxt模块的包(package)添加自定义nuxt命令。为此,您必须NuxtCommand在定义命令时遵循API规则。假设放置的一个简单示例my-module/bin/command.js如下所示:
#!/usr/bin/env node
const consola = require('consola')
const { NuxtCommand } = require('@nuxt/cli')
NuxtCommand.run({
name: 'command',
description: 'My Module Command',
usage: 'command <foobar>',
options: {
foobar: {
alias: 'fb',
type: 'string',
description: 'Simple test string'
}
},
run (cmd) {
consola.info(cmd.argv)
}
})
这里有一些值得注意的事情。首先,注意调用/usr/bin/env来检索Node可执行文件。另请注意,ES模块语法不能用于命令,除非您手动合并esm到代码中。
接下来,您将注意到如何使用NuxtCommand.run()指定命令的设置和行为。定义选项options,通过解析minimist。解析参数后,run()``将使用NuxtCommand`实例作为第一个参数自动调用。
在上面的示例中,cmd.argv用于检索解析的命令行参数。有更多的方法和属性NuxtCommand --将提供有关它们的文档,因为此功能将进一步测试和改进。
要使您的命令可以通过Nuxt CLI识别bin,请使用nuxt-module约定将其列在package.json的部分下,该约定module与您的包名称相关。使用此二进制文件,您可以根据argv需要进一步解析更多subcommands命令。
{
"bin": {
"nuxt-foobar": "./bin/command.js"
}
}
一旦安装了软件包(通过NPM或Yarn),您就可以nuxt foobar ...在命令行上执行。
modules有许多钩子和可能性。请参考 Nuxt Internals 了解有关Nuxt内部API的更多信息。