Example project to showcase Hubs plugin development with Webpack and evaluate the plugin API.
This API is experimental and will change
Please give us feedback on the API in the #extensibility channel on our Discord server.
Run the following commands:
git clone https://github.com/MozillaReality/hubs-plugin-api.git
cd hubs-plugin-api
npm install
npm startModify pages/index.js to modify the landing page.
You can also run npm run build to see what a production build of your plugin would look like.
At this time there is no way to use the plugin with your Hubs Cloud instance, this project is only intended for evaluation of the API.
When you run your own Hubs Cloud instance the Hubs client and the rest of the stack will receive automatic updates with the latest features of Hubs. In order to maintain the ability to automatically update your Hubs client we have designed a plugin system which loads plugin scripts at runtime. The APIs exposed to you will be versioned and maintained in a way that will avoid breakage when your Hubs Cloud packages are updated.
Plugins are exposed as ES2015 javascript modules that are dynamically loaded at predefined places in the Hubs client. Modules are broken up based on the page/feature they are intended to be used with. This keeps the amount of javascript loaded to a minimum and improves page load time. You may use the registerPlugin function to expose React Components and more to the Hubs client.
import Hubs from "@hubs/core";
import React from "react";
function HomePage() {
return <div>Hello World!</div>;
}
Hubs.registerPlugin("home-page", HomePage);Plugins are defined in the Hubs APP_CONFIG global object that is included in the <head> tag of each page.
window.APP_CONFIG = {
plugins: {
"home-page": [
{
type: "js",
url: "/index.plugin.js",
dependencies: ["react", "prop-types", "@hubs/core", "@hubs/home-page"]
}
]
}
};Currently this configuration is injected into each page by the HubsDevServer, in production the Hubs backend server (Reticulum) injects the APP_CONFIG into the page.
You register plugins in the hubs.config.js file. This is consumed in the HubsDevServer to generate the APP_CONFIG and in webpack to generate the entry points.
module.exports = {
name: "my-plugin",
version: "0.0.1",
hooks: {
"home-page": ["./pages/index.js"]
}
};The current Hubs SDK is focused on extending the home page so it is extremely limited in scope. At this point we are looking to hear from developers on what components they need from us to build their home page experience.
The Hubs SDK is exposed as a global variable when your plugin is loaded into the page.
window.Hubs.coreOur webpack config also lets you use ES2015 imports, these will be swapped out with references to global variables at build time.
import Hubs from "@hubs/core";The Hubs SDK is broken into packages that
- Hubs.core / @hubs/core - Core API methods
- Hubs.react / @hubs/react - Common React components and styles.
- Hubs.homePage / @hubs/home-page - Components and Hooks used on the home page.
- Hubs.mediaBrowser / @hubs/media-browser - Components and styles for the media browser.
Returns true if the user has an authentication token stored in local storage.
Hub.core.isAuthenticated() === trueReturn the authentication token for the user. Returns undefined if the user is not logged in.
Hubs.core.getAuthToken() === "super-secret-token"Make a POST request with a json body to Reticulum. options are the same options passed to the fetch API. Returns the json parsed response.
const response = await Hubs.core.postJSON("/api/v1/hubs", {
hub: {
name: "My Room"
}
});Make an authenticated POST request with a json body to Reticulum. options are the same options passed to the fetch API. Returns the json parsed response. Throws an error if the user is not currently logged in.
const response = await Hubs.core.postJSONAuthenticated("/api/v1/hubs", {
hub: {
name: "My Room"
}
});Create a room for the current user. If the user is not logged in the room will be created anonymously.
{
name?: string
description?: string
scene_id?: string
room_size?: number
user_data?: {}
} {
creator_assignment_token: string
embed_token: string
hub_id: string
status: string
url: string
} const response = await Hubs.core.createRoom({
name: "My Room",
scene_id: "123abc"
});Check if a feature is enabled by the current app config. Features are defined in the Hubs schema.toml file and correspond to configuration in the admin panel.
Hubs.core.config.feature("disable_room_creation") === falseGet an image url from the current app config. Images are defined in the Hubs schema.toml file and correspond to configuration in the admin panel.
Hubs.config.image("logo") === "https://my-hubs-cloud.com/logo.png";
// cssUrl = true
Hubs.config.image("logo", true) === "url(https://my-hubs-cloud.com/logo.png)";Get a url from the current app config. Links are defined in the Hubs schema.toml file and correspond to configuration in the admin panel.
Hubs.config.link("docs", "https://hubs.mozilla.com/docs") === "https://hubs.mozilla.com/docs";To Do
To Do
To Do
You can load a plugin in a local Hubs dev server by passing the --env.pluginManifest=<plugin-manifest-url> option.
Start the plugin dev server on a port other than 8080.
cd hubs-plugin-api
npm start -- --port 8081
Start the Hubs dev server with the plugin manifest url.
cd hubs
npm run dev -- --env.pluginManifest="https://localhost:8081/plugin-manifest.json"