mirror of
https://github.com/wassname/talk.git
synced 2026-06-29 20:03:00 +08:00
David Erwin
164 lines
4.5 KiB
Markdown
164 lines
4.5 KiB
Markdown
# 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:
|
|
|
|
```json
|
|
{
|
|
"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:
|
|
|
|
```json
|
|
{
|
|
"server": [
|
|
{"people": "^1.2.0"}
|
|
]
|
|
}
|
|
```
|
|
|
|
### Resolving Plugins
|
|
|
|
External plugins can be _resolved_ by running:
|
|
|
|
```bash
|
|
./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:
|
|
|
|
```bash
|
|
# 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:
|
|
|
|
```bash
|
|
# Watch for changes to client files and rebuild
|
|
yarn build-watch
|
|
```
|
|
|
|
```bash
|
|
# 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:
|
|
|
|
```Dockerfile
|
|
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.
|