# 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 thetitle
is'Vssue Demo'
, the actual title of the corresponding issue is'[Vssue]Vssue Demo'
.It will be ignored if the type of
title
isFunction
.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 intoadmins
.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 totrue
, 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 tofalse
, 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 settitle
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
andtitle
. If the issue does not exist, Vssue will try to create a new issue withtitle
,issueContent
andlabels
.In other words,
labels
andtitle
is the identifier of the corresponding issue.So make sure that Vssue on different pages have different
title
s. Vssue with sametitle
will correspond to the same issue, and share the same comments.- If the type is
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
andautoCreateIssue
- Props:
title
ATTENTION
If
issueId
is set, Vssue will use it to determine which issue to use directly, instead of requesting issues according tolabels
andtitle
. 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:
# options
Type:
Object
(Partial<VssueOptions>
)Required:
false
Default:
{}
Details:
The properties in prop
options
will override those set byVue.use()
. Accepts all the properties inVssueOptions
.You can take the options set by
Vue.use()
as global / default options, and take the propoptions
as local options.Reference: Vssue Options