talk/docs-tmp/plugins

Plugins

The talk platform ships with a plugin architecture featuring that allows developers to:

• extend or replace server side graph, rest and auth functionality
• inject functionality into front end embeds and the admin application
• create new front end build targets for embedding
• build plugins from local folders or published via npm/yarn
• deploy plugins throughout the application lifecycle

Basic Concepts

All plugin code lives in the /plugin directory.

Each plugin is provided in a single folder named after the plugin.

Naming a Plugin

Each plugin has a name which must be globally unique. Plugins with name collisions will not be able to be run together in an instance of Talk.

If you are creating a plugin for the open source community, we recommend the following naming convention:

coral-talk-plugin-[name]

If you are creating a variant of a plugin for an organization, we recommend adding the organization's name:

coral-talk-plugin-[name]-[organization]

Plugin Registration

In order for a Plugin to be active it must be registered.

The parsing order for the plugin registration is as follows:

• TALK_PLUGINS_JSON environment variable
• plugins.json file
• plugins.default.json file

If you need to "disable all plugins", you can simply provide {} as the contents of process.env.TALK_PLUGINS_JSON or the plugins.json.

Local Plugins

The format for plugins.json looks like this:

{
  "server": [
    "coral-plugin-respect",
    "coral-plugin-facebook-auth"
  ],
  "client": [
    "coral-plugin-respect"
  ]
}

The server array specifies which plugins will be loaded when the server starts. The client array specifies which plugins will be built into the front end bundles.

Where we have a server key with an array of plugins that match the folder name in the plugins/ folder. For example, the above config would require a plugin from plugins/coral-plugin-respect and plugins/coral-plugin-facebook-auth.

Published Plugins

If the package is external (available on NPM) you can specify the string for the version by using an object instead, for example:

{
  "server": [
    {"people": "^1.2.0"}
  ]
}

Resolving Plugins

External plugins can be resolved by running:

./bin/cli plugins reconcile

This achieves two things:

1. It will traverse into local plugin folders and install their dependencies. Note that if the plugin is already installed and available in the node_modules folder, it will not be fetched again unless there is a version mismatch. This will result in the project package.json and yarn.lock files to be modified, this is normal as this ensures that repeated deployments (with the same config) will have the same config, these changes should not be committed to source control.
2. It will seek out dependencies that are listed in the object notation and try to install them from npm.

Plugin Dependencies

You may also include additional external dependencies in your local packages by specifying a package.json at your plugin root which will result in a node_modules folder being generated at the plugin root with your specific dependencies.

Deployment Solutions

Plugins can be deployed with a production instance of Talk.

Source

Source deployments can just modify the plugins.json file and include any local plugins into the plugins/ directory. After including the config, you need to reconcile the plugins and build the static assets:

# get plugin dependancies and remote plugins
./bin/cli plugins reconcile

# build staic assets (including enabled client side plugins)
yarn build

Then the application can be started as is.

If you are working on a plugin, our changes to the plugins will be picked up naturally by our development scripts:

# Watch for changes to client files and rebuild
yarn build-watch

# Watch for changes to server files and restart
yarn dev-start

Docker

If you deploy using Docker, you can extend from the *-onbuild image, an example Dockerfile for your project could be:

FROM coralproject/talk:latest-onbuild

Where the directory for your instance would contain a plugins.json file describing the plugin requirements and a plugins directory containing any other local plugins that should be included.

Onbuild triggers will execute when the image is building with your custom configuration and will ensure that the image is ready to use by building all assets inside the image as well.