Build Gopeed JavaScript extensions, debug them locally, and understand the extension manifest and runtime.
Gopeed supports extension development using JavaScript. Extensions can enhance Gopeed's functionality, such as downloading videos or music from a website. You can quickly learn more about it through the official examples.
Gopeed extensions are based on git to achieve decentralized extension management. As long as the extension source code is hosted in a remote git repository, it can be installed and updated through Gopeed. Therefore, whether it is github, gitee, gitlab, or other git hosting platforms, they can all be used as extension repositories.
Gopeed provides a scaffolding to help you quickly create an extension development project template:
npx create-gopeed-ext@latest
In the creation process, you will see the following prompts:
√ Project name (gopeed-extension-demo) ...√ Choose a template » WebpackSuccess! Created gopeed-extension-demo at D:\code\study\js\gopeed-extension-demoInside that directory, you can run several commands: git init Initialize git repository npm install Install dependencies npm run dev Compiles and hot-reloads for development. npm run build Compiles and minifies for production.We suggest that you begin by typing: cd gopeed-extension-demoHappy coding!
After the project is built, you need to do local debugging. You can install the local extension project into Gopeed for debugging. The specific steps are as follows:
Enable the Gopeed developer mode, click the install button 5 times in a row on the extension page to enable the developer mode.
Click the button to select the extension directory in the directory selector to install.
If you use the webpack mode in the scaffolding, you can start automatic compilation through npm run dev.
Create a task to see the extension take effect.
It can be seen that the example extension created through the scaffolding can parse an example/index.html file when creating a task using the https://github.com/hello link.
Note: Developer mode is only valid on the desktop platform.
In the previous section, we were able to create a basic extension and debug it locally, but what is happening under the hood?
First, let's take a look at the manifest.json file, which is the manifest file of the extension. It describes the information of the extension. Each extension project must contain a manifest.json file in the root directory. The sample file in this section is as follows:
Next, let's introduce the meaning of each field one by one:
name and author: Gopeed will use <author>@<name> as the ID of the extension. After filling in the author, it can ensure that it is not easy to be overwritten and installed with other extensions, so it is strongly recommended to fill in the author field.
title and description: The title and description of the extension.
icon: Extension icon, fill in the relative path, for example: icon.png.
version: Extension version, using semver specification, when the extension is updated, it is compared based on this field, so please make sure that the version number is in compliance with the specification.
homepage: Extension homepage, for example: https://gopeed.com.
repository: The git repository address to which the extension belongs. Gopeed extensions rely on git to achieve decentralized extension management. Therefore, if your extension needs to be installed and updated by users, you must host the extension source code in a remote git repository and configure this field.
In Gopeed installation, you need to use # to separate, e.g. https://github.com/GopeedLab/gopeed-extension-samples#github-contributor-avatars-sample.
scripts: Pay attention! This is the configuration of the Gopeed extension activation event.
The onResolve event configured in the sample project will be triggered when parsing tasks. The match.urls field is used to match the URL created by the task. If the match is successful, the script file specified in the entry field will be executed.
The matching rules are consistent with the matching rules of Chrome extensions, which can be referred to here
settings: Extension settings, through the configuration declaration, the corresponding settings page can be generated in Gopeed to provide user-defined settings, such as custom Cookie, custom User-Agent, etc., for example:
Gopeed extension script engine is implemented by goja which is a JavaScript interpreter written in pure Go. However, since goja is only a pure js runtime, the APIs of browser and node.js are not supported. Currently, Gopeed implements XMLHttpRequest and fetch APIs, which means you can use these two APIs or third-party libraries based on them to implement network requests, such as axios, superagent, etc.
Another thing to note is that goja natively supports most of the es6+ syntax, but a few syntaxes are not supported, such as async generator, but it doesn't matter, the project created by the scaffolding has been configured with babel, you can use the latest es syntax happily, and the script will eventually be compiled into es5 syntax.
gopeed.events.onResolve: This registers the onResolve event handler, where the extension logic lives.
ctx: The event context, containing information about the current event. In the onResolve event, ctx contains:
req: Request information, including the resource URL, headers, etc.
res: Response information, the script needs to assign the parsed file list to ctx.res, and Gopeed will download according to the file list returned.
In short, in the onResolve callback function, you need to parse the file list to download based on the request information in ctx.req and assign it to ctx.res.
Gopeed provides a storage API to support persistent extension data, such as login tokens. Example:
gopeed.events.onResolve((ctx) => { // Get the token; if it does not exist, then log in const token = gopeed.storage.get("token"); if (!token) { const token = await login(); gopeed.storage.set("token", token); } // Then do something with the token // ...});
Note: For detailed API information, please refer to the documentation.
Log files are stored in the logs directory under the Gopeed installation path, with the file name extension.log. You can use tail -f extension.log to watch logs in real time.
Note: debug level logs only take effect for extensions installed in developer mode.
After extension development is complete, if it was created with the scaffolding webpack project, you need to build it first:
npm run build
Then create a remote repository. For example, if you create a repository named https://github.com/xxx/gopeed-extension-demo on github, update the repository field in manifest.json accordingly:
Correctly configuring repository enables remote updates for the extension. If the extension is a subdirectory under a git repository, you can use the directory attribute to specify the subdirectory, for example:
Remember to set the extension's author and name fields properly to reduce the risk of name collisions with other extensions.
Then push the project to the remote repository to complete the release. To make it easier for users to find Gopeed extensions on github, it is recommended to use the gopeed-extension- prefix for project names, such as gopeed-extension-demo, and to tag the project with gopeed-extension on github.
After publishing to a remote repository, you can install it in Gopeed. Open the extension page, enter the extension's git clone address using the HTTP protocol (you can omit the trailing .git), and click the Install button.
Note: If the extension lives in a subdirectory, append # to the address followed by the subdirectory name, for example https://github.com/xxx/gopeed-extension-demo#path.
This extension depends on node.js and is suitable for complex development needs. It uses the cheerio library to parse page DOM and collect the files to download.
This extension is a pure JS project with no dependencies. It is suitable for simple development needs and uses fetch to make network requests and collect the files to download.