Vssue

# Options Reference

# Vssue Options

Vssue Options (type VssueOptions) is set when calling Vue.use():

import Vue from 'vue';
import Vssue from 'vssue';

Vue.use(Vssue, {
  // Vssue Options
});

# api

  • Type: VssueAPI.Constructor

  • Details:

    The constructor of the VssueAPI class that implements VssueAPI.Instance interface.

    Vssue will use it to create an instance of VssueAPI, and use the VssueAPI instance to send requests to platform.

    The name of VssueAPI packages format as @vssue/api-${platform}-${version}, for different API version of different platforms.

    Check Supported Platforms for available VssueAPI packages.

  • Example:

    import Vue from 'vue';
import Vssue from 'vssue';
import GithubV3 from '@vssue/api-github-v3';

Vue.use(Vssue, {
  api: GithubV3,
  // Other Vssue Options
});

    TIP

    In fact, the platform itself is "opaque" to Vssue. Vssue just loads comments via the API instance, and does not care about what the platform is and what the version of API is. This is how Vssue supports different platforms.

    So it is easy to support new platforms / new version of API by creating new API packages.

# owner

  • Type: string

  • Details:

    The owner's name of repository to store the issues and comments. Could be the name of a user or an organization (Github Organization / Gitlab Group / Bitbucket Team).

    Together with repo, Vssue could locate the repository on the platform.

  • Reference: repo

# repo

  • Type: string

  • Details:

    The name of repository to store the issues and comments.

    Together with owner, Vssue could locate the repository on the platform.

  • Reference: owner

TIP

The common pattern of repository's URL is `${baseURL}/${owner}/${repo}`:

  • Github: https://github.com/${owner}/${repo}
  • Gitlab: https://gitlab.com/${owner}/${repo}
  • Bitbucket: https://bitbucket.org/${owner}/${repo}
  • Gitee: https://gitee.com/${owner}/${repo}
  • Gitea: https://gitea.com/${owner}/${repo}

# clientId

  • Type: string

  • Details:

    The client_id introduced in OAuth2 spec.

    It is the client identifier that issued by the platform. You will get it after you set up OAuth App.

    Vssue will use it to get user's access token.

  • Reference:

# clientSecret

  • Type: string

  • Default: undefined

  • Details:

    The client_secret introduced in OAuth2 spec.

    It is the client secret that generated by the platform. You will get it after you set up OAuth App.

    When work with some of the platforms, Vssue will use it together with clientId to get user's access token.

    TIP

    Some platforms (e.g. Bitbucket and GitLab) support Implicit Grant, so we don't need clientSecret for those platforms.

    However, some platforms (e.g. GitHub, Gitee and Gitea) do not support it now, so clientSecret is required for those platforms.

  • Reference:

# baseURL

  • Type: string

  • Default: undefined (according to the platform)

  • Details:

    This is the base URL of your platform.

    Default values for supported platforms are:

    • 'https://github.com' for Github
    • 'https://gitlab.com' for Gitlab
    • 'https://bitbucket.org' for Bitbucket
    • 'https://gitee.com' for Gitee
    • 'https://gitea.com' for Gitea

    ATTENTION

    Only when you choose to use self-hosted platform should you set this option. (e.g. GitLab Community / Enterprise Edition or GitHub Enterprise Server)

  • Reference:

# state

  • Type: string

  • Default: 'Vssue'

  • Details:

    The state element introduced in OAuth2 spec.

    Vssue will send it with OAuth redirection and check if it is matched in callback.

    It's designed for preventing CSRF, but it's not so useful here as we put everything in a static page. So just ignore it or set it to anything you like.

# labels

  • Type: string

  • Default: ['Vssue']

  • Details:

    To set the labels of issues that Vssue uses.

    Vssue will only request those issues with the labels and ignore others. Together with title, labels will help to identify the corresponding issue of Vssue. If you use multiple labels by setting more strings, only issues with all those labels will be requested by Vssue.

    TIP

    Bitbucket does not support issue labels for now, so this option will be ignored if you are using Bitbucket.

    Github supports emoji in labels' name, e.g. [':heart:Vssue', ':mailbox:Comments'].

  • Reference: title

# prefix

  • Type: string

  • Default: '[Vssue]'

  • Details:

    The title prefix for issues. Used for generating the actual title of the corresponding issue.

    For example, if the prefix is '[Vssue]' and the title is 'Vssue Demo', the actual title of the corresponding issue is '[Vssue]Vssue Demo'.

    It will be ignored if the type of title is Function.

  • Reference: title

# admins

  • Type: Array<string>

  • Default: []

  • Details:

    Array of username that has admin access to Vssue. The owner always has admin access.

    Users with admin access can delete all comments, while other users can only delete their own comments.

    Only admins can auto create corresponding issue if it does not exist.

    TIP

    If you want to auto create the issue when the owner is a organization rather than a user, you can add your username into admins.

  • Reference: owner

# perPage

  • Type: number

  • Default: 10

  • Details:

    The default value of how many comments to show per page.

# locale

  • Type: string

  • Default: undefined

  • Details:

    The locale language.

    If not set, Vssue will use one of window.navigator.languages, or fallback to 'en'.

    TIP

    Vssue uses vue-i18n for i18n, but it will not affect other parts of your Vue App. And if you already have vue-i18n in your project, it will not affect Vssue.

    Language packages locate in src/i18n/langs directory. Currently we have supported:

    • 'en' ('en-US')
    • 'zh' ('zh-CN', 'zh-TW')
    • 'pt' ('pt-BR')
    • 'ja' ('ja-JP')
    • 'he' ('he-IL')
    • 'ko' ('ko-KR')
    • 'fr' ('fr-FR')

    Contributions welcome for more languages support.

# proxy

  • Type: string | ((url: string) => string)

  • Default: url => `https://cors-anywhere.azm.workers.dev/${url}`

  • Details:

    Some platforms (e.g. GitHub, Gitee and Gitea) do not support Implicit Grant, so we have to request the API of the platform to get the access token.

    However, the access token API of the platforms do not support CORS (see related issue of GitHub). As Vssue is a pure front-end plugin, we have to use a proxy to request access token.

    By default, we use an open source CORS proxy service cors-anywhere for that.

    If you want to use your own proxy, you need to set this option.

    If the platform you use does not require clientSecret, this option will be ignored.

  • Example:

    proxy: url => `https://your.cors.porxy?target=${url}`;

  • Reference:

# issueContent

  • Type: ((param: { options: Vssue.Options, url: string }) => string | Promise<string>)

  • Default: ({ url }) => url

  • Details:

    The content of issue that auto created by Vssue.

    Vssue will use the return value of the function as the content.

    The parameter includes two properties:

    • options is the options of Vssue.
    • url is the URL of current page, which is the default content.

  • Example:

    issueContent: ({ url }) =>
  `This issue is auto created by Vssue to store comments of this page: ${url}`;

    TIP

    The issueContent option is only used to auto create the corresponding issue when it does not exist.

    If the issue already exists, Vssue will not try to update the content.

# autoCreateIssue

  • Type: boolean

  • Default: false

  • Details:

    If autoCreateIssue is set to true, Vssue will try to create an issue automatically when the corresponding issue does not exist. Notice that if you have not logged-in, Vssue will redirect to the authorization page automatically.

    If autoCreateIssue is set to false, you need to create the issue manually.

# Component Props

Vssue component props are set when using <Vssue /> component:

<!-- use title -->
<Vssue title="Hello, Vssue!" :options="{ locale: 'en' }" />

<!-- OR: use issueId -->
<Vssue :issue-id="1" :options="{ locale: 'en' }" />

# title

  • Type: string | ((options: VssueOptions) => string)

  • Required: false

  • Default: options => `${options.prefix}${document.title}`

  • Details:

    The title of issue that used by this Vssue component.

    • If the type is string, the actual title of issue is `${prefix}${title}`.
    • If the type is Function, the actual title of issue is the return value of the function. Notice that the first parameter of the function is the options of Vssue, and you can use them to generate the actual title.

    TIP

    Although title has its default value, it's suggested to always set title explicitly in SPA, or Vue.js may always use the same Vssue component instance when navigating between different SPA pages. Alternatively, you can add key to help Vue.js identify the components.

    ATTENTION

    When trying to load comments, Vssue will request the corresponding issue according to labels and title. If the issue does not exist, Vssue will try to create a new issue with title, issueContent and labels.

    In other words, labels and title is the identifier of the corresponding issue.

    So make sure that Vssue on different pages have different titles. Vssue with same title will correspond to the same issue, and share the same comments.

  • Reference:

# issueId

  • Type: string | number

  • Required: false

  • Default: null

  • Details:

    The id of issue that used by this Vssue component.

    If issueId is set, these parameters will be ignored:

    • Options: labels, prefix, issueContent and autoCreateIssue
    • Props: title

    ATTENTION

    If issueId is set, Vssue will use it to determine which issue to use directly, instead of requesting issues according to labels and title. This will make the initialization process faster.

    In this case, however, you have to create issues manually. If the corresponding issue is not found, Vssue will not try to create a new issue for you.

# options

  • Type: Object (Partial<VssueOptions>)

  • Required: false

  • Default: {}

  • Details:

    The properties in prop options will override those set by Vue.use(). Accepts all the properties in VssueOptions.

    You can take the options set by Vue.use() as global / default options, and take the prop options as local options.

  • Reference: Vssue Options