# Using Plugin

TIP

The plugin mechanism of Vapper is its own backbone. In fact, the many capabilities of Vapper itself are also implemented based on the plugin mechanism.

# Intro

Plugins can extend the runtime capabilities of the Vapper application, such as the @vapper/plugin-cookie plugin that injects a ctx.$cookie property into context object for handling cookie. Plugins can also extend the capabilities of the Vapper framework itself, such as the @vapper/plugin-prerender plugin, which adds a new CLI command to the framework to perform prerendering. Plugins can also do a lot of things, such as adding server middleware, hooking into the various sections of Vapper startup, and so on.

# Basic usage

Specify the plugin you want to use via the plugins option in vapper.config.js:

// vapper.config.js
module.exports = {
  plugins: ['vapper-plugin-do-something']
}

The plugins option is an array, 'vapper-plugin-do-something' is the name of the plugin, and Vapper will load the plugin based on that name, so you will need to install it manually.

A plugin can also be a function:

// vapper.config.js
const myPlugin = require('./myPlugin.js')

module.exports = {
  plugins: [myPlugin]
}

If you want to pass parameters to the plugin, you need to use a nested array:

// vapper.config.js
module.exports = {
  plugins: [
    ['vapper-plugin-do-something', { /* options */ }]
  ]
}

If a plugin extends the runtime capabilities of the Vapper application, then it may need to get configuration options at runtime. At this point we need to use the pluginRuntimeOptions object as described in Runtime Options for Plugins. If a plugin extends Vapper at the framework level, such as registering a new command, then do the same as the code above, but these options are not available at runtime.

TIP

A plugin requires a clear documentation describing how it accepts configuration options.

# Official plugin

# @vapper/plugin-prerender

The plugin provides prerendering capabilities, you can specify the route that needs to be prerendered, and the plugin will render the matching route to the corresponding html file. When the request comes in, if the specified route is matched, the pre-rendered html file will be sent to the client as a static resource.

Pre-rendering has many advantages over rendering on-the-fly, which can send content to the client faster, while also reducing the load on the server. But not all pages are suitable for pre-rendering.

# Installation

yarn add @vapper/plugin-prerender

# Usage

// vapper.config.js
module.exports = {
  plugins: [
    [
      '@vapper/plugin-prerender',
      {
        routes: ['/foo']
      }
    ]
  ]
}

Add the npm script:

{
  "scripts": {
    "generate": "vapper generate"
  }
}

This plugin registers the vapper generate command, which is equivalent to "build + generate".

TIP

@vapper/plugin-cookie is internally dependent on jshttp/cookie (opens new window).

The plugin extends the runtime of the Vapper application and adds the $cookie property to the context object for isomorphic manipulation of cookies, which can be used both on the server and on the client.

# Installation

yarn add @vapper/plugin-cookie

# Usage

// vapper.config.js
module.exports = {
  plugins: [
    ['@vapper/plugin-cookie']
  ]
}

The @vapper/plugin-cookie plugin accepts runtime options. To pass options for it, you need to add the pluginRuntimeOptions property to the factory function exported by the entry file:

// Entry file
export default function createApp (ctx) {
  // ......
}

createApp.pluginRuntimeOptions = {
  cookie: { /* options */ }
}

The @vapper/plugin-cookie plugin reads the pluginRuntimeOptions.cookie object as a configuration option.

To access the $cookie object via ctx:

// The Entry file
export default function createApp (ctx) {
  ctx.$cookie.get('foo') // Read cookie named `foo`
  ctx.$cookie.set('foo', 1) // Set cookie named `foo`
}

createApp.pluginRuntimeOptions = {
  cookie: { /* options */ }
}

Access $cookie through this within the component:

export default {
  created() {
    this.$cookie.get('foo') // Read cookie named `foo`
    this.$cookie.set('foo', 1) // Set cookie named `foo`
  }
}

Use the $cookie.get function to read cookie.

Arguments:
- {string} key
Return: {string | object}
Usage:

export default {
  created () {
    const token = this.$cookie.get('token')
  }
}

When abandoning the argument for the $cookie.get function, it returns an object containing all the cookies:

export default {
  created () {
    const cookies = this.$cookie.get()
    // cookies = { token: 'xxx', uid: 'xxx', .... }
  }
}

Use the $cookie.set function to set one or a set of cookies.

Arguments:
- {string | array} key
- {string} value
- {object} options
Usage:

Set a single cookie:

export default {
  created () {
    this.$cookie.set('token', 'token value', { path: '/' })
  }
}

Set multiple cookies:

export default {
  created () {
    this.$cookie.set([
      {
        name: 'token',
        value: 'token value'
      },
      {
        name: 'foo',
        value: 1,
        options: { path: '/foo' }
      }
    ])
  }
}

All available options can be viewed at: jshttp/cookie#options (opens new window)

Use the $coookie.delete function to remove single or all cookies.

Arguments:
- {string} key
- {object} options
Usage:

Delete a single cookie：

export default {
  created () {
    this.$cookie.delete('token')
  }
}

When abandoning the argument for the $cookie.delete function, it will delete all cookies.

export default {
  created () {
    this.$cookie.delete()
  }
}

Where options is: jshttp/cookie#options (opens new window)

# Plugin options:

# fromRes

Type: boolean
Default: false

This option is only valid on the server side and is used to indicate whether the cookie in the response object(res) is read when the cookie.get function is used to read cookie.

# @vapper/plugin-platform

This plugin is used for platform(or User-Agent) assertion. In the browser, the UA information is obtained through window.navigator.userAgent, but in the server, it will obtained from the request object req.headers['user-agent'].

# Installation

yarn add @vapper/plugin-platform

# Usage

// vapper.config.js
module.exports = {
  plugins: [
    [
      '@vapper/plugin-platform',
      {/* options */}
    ]
  ]
}

The plugin injects the $browser object on the Context object and component instances, which contains information about the user agent, such as:

// Home.vue
export default {
  created() {
    console.log(this.$browser.name) // Chrome
    console.log(this.$browser.version) // '80.0.3987.122'
  }
}

# Custom detection rules

Sometimes you may need to customize UA detection rules. You can do this through the browsers plugin option:

// vapper.config.js
module.exports = {
  plugins: [
    [
      '@vapper/plugin-platform',
      {
        browsers: [
          // Custom detection rules
          {
            test: [/chrome/],
            describe (ua) {
              const browser = {
                name: 'SupperChrome'
              }
        
              return browser
            }
          }
        ]
      }
    ]
  ]
}

browsers option is an array, so multiple rules can be defined. As shown in the highlighted code above, each custom rule is an object containing the test property and the describe property, where the test property is an array specifying a set of matching rules that will be used forUAString. Once the rules match, the describe function will be executed. In fact, the return value of the describe function can be accessed through this.$Browser.

In addition, the describe(ua) function receives a UA string as a argument, and you can do the corresponding processing as needed.

# Custom checker function

// vapper.config.js
module.exports = {
  plugins: [
    [
      '@vapper/plugin-platform',
      {
        browsers: [
          // Custom detection rules
          {
            test: [/chrome/],
            describe (ua) {
              const browser = {
                name: 'SupperChrome'
              }
        
              return browser
            }
          }
        ],
        checkers: {
          isChrome() {
            // The `this` is equivalent to the `this.$Browser` object
            return this.name === 'SupperChrome'
          }
        }
      }
    ]
  ]
}

As shown in the highlighted code above, the checkers option is an object, and you can customize shortcut functions. With the above configuration, we can use it in the component as follows:

export default {
  created() {
    this.$browser.isChrome() // true or false
  }
}

# Community plugin

← Caching Vapper Injection →

# Using Plugin

# Intro

# Basic usage

# Official plugin

# @vapper/plugin-prerender

# Installation

# Usage

# @vapper/plugin-cookie

# Installation

# Usage

# Read cookie

# Set cookie

# Delete cookie

# Plugin options:

# fromRes

# @vapper/plugin-platform

# Installation

# Usage

# Custom detection rules

# Custom checker function

# Community plugin