Skip to main content

Plugin Definition File

You can check out the parameters set within the definitions.json file. Some notable things you can change here are:

  • The area and type of the plugin
  • The component that is rendered for the plugin
  • The plugin route
  • The settings for your plugin

Extension areas#

The area defines where in Reach your plugin will be rendered.

At the moment we offer the following areas:

  • Global: Will be rendered on all pages. Note that idea here is not to render content, but maybe set some CSS class or something like that which is used everywhere.
  • Page: Will render your plugin as an own page, if you use this area you must also specify a navigation node. See routing for more details.
  • EventEditorFeedbackSection: Will be rendered at the beginning of the feedback section for events.
  • EventDetailViewSection: Will be rendered in the detail view section, after the body, of events.
  • ItemEditor: Will be rendered in the Insert object menu on Pages, News and Events. If you use this area you must also specify an objectButton. See embedded plugins for more details.
  • NewsEditorFeedbackSection: Will be rendered at the beginning of the feedback section for news.
  • NewsOverviewCardSection: Will be rendered above the footer area of a News Card.

Settings#

The settings property defines a set of key-value pairs that can be used to store your plugin's configuration settings. An example for a settings defined inside the definition.json file:

"settings": {
"greetingLabel": "Heya!",
"fontColor": "yellow"
}
info

Settings should not contain any sensitive and security relevant data, since they are exposed to all users of a subscription via the Reach API.

After changing the settings you will be able to consume these values from your plugin using the usePluginSettings hook. In the following example we consume the greetingLabel that was set up in the definition.json file:

const { greetingLabel } = usePluginSettings<{ greetingLabel?: string }>();

Optionally the hook accepts a type argument where we can specify what our settings object looks like. This way we get type definitions for these values. Please keep in mind that any changes done to the settings are not going to be saved permanently because each time we reload the page the settings will be re-read from the definition.json file.

Here is a full example where we render out the greetingLabel:

import { FC } from 'react';
import { PluginProps, useCurrentUser, usePluginSettings } from '@reach/core';
export const WelcomePlugin: FC<PluginProps> = () => {
const { greetingLabel } = usePluginSettings<{ greetingLabel?: string }>();
const user = useCurrentUser();
return (
<Page title="Welcome Plugin">
<h2>
{greetingLabel || 'Welcome,'} {user.displayName}!
</h2>
</Page>
);
};
note

Settings can also be changed directly within Reach on a per subscription basis, once the plugin has been installed and added.

Subscription Id#

Optionally, a default subscriptionId can be set at the root level of your definition file Setting this value will ensure that by default Reach will use the context of your subscription (i.e. navigate to the correct subscription in the browser), if you execute a command (e.g. npm run publish-web). Note that you can still install the plugin in another subscription if you want to. It's just a convenient way of ensuring, that by default a specific subscription is used.

You can find the subscription id on the about page of your Reach subscription.

"subscriptionId": "my-subscription-id",
"settings": {
"greetingLabel": "Heya!",
"fontColor": "yellow"
}

Environments#

Environment based definitions#

Sometimes there is a need to load different definitions for different environments. For example, maybe you have an API url saved in the definition.json which is not correct for all your environments. To solve this we can use a supplementary definition file that will override the base value of any property specified in it. You may have as many supplementary definition files as environments you want.

These supplementary definition files must be named in the format: definition.<environment>.json and they must reside in the same folder as the definition.json.

note

The following environment names are reserved and should not be used unless you know what you're doing, because they point to different Reach URLs.

  • local
  • dev
  • test
  • staging

During a publish or build these files will automatically be merged using the following rules:

  • Any duplicate property (present in the master definition file and in the supplementary environment based definition file) will use the override property from the environment-based file
  • Any missing property from the environment definition file will keep the master definition file's value
  • Any properties not in the master definition file will be expanded and added from the environment based definition file

Let's take the following example where we override the API url.

This is our example definition.json:

{
"subscriptionId": "my-prod-sub-id",
"pluginId": "my-plugin",
"extensions": [
{
"area": "Page",
"componentName": "MyPlugin",
"route": "myPlugin"
}
],
"settings": {
"isProduction": "true",
"apiUrl": "https://my.production.api.url"
}
}

In order to override apiUrl for development we create the following definition file:

{
"subscriptionId": "my-dev-sub-id"
"settings": {
"isDev": "true",
"apiUrl": "http://localhost:5000"
}
}

We are going to name it definition.development.json and place it next to the definition.json.

After that depending on the environment we run our plugin on, we will have the following settings available for us:

  • For development:
    • subscriptionId with a value of my-dev-sub-id
    • isProduction with a value of true
    • isDev with a value of true
    • apiUrl with a value of http://localhost:5000
  • For production:
    • subscriptionId with a value of my-prod-sub-id
    • isProduction with a value of true
    • isDev with a value of undefined (not set)
    • apiUrl with a value of https://my.production.api.url

As we can see, in the development environment both isProduction and isDev are set. This is because we didn't explicitly override isProduction. To fix this we need to make the following change to our development definition file:

{
"settings": {
"isProduction": "false", // <--- add this line
"isDev": "true",
"apiUrl": "http://localhost:5000"
}
}

The next time we use the development environment the value of isProduction will be correctly overridden and set to false.

Environment based development#

Now that we know how we can define different definition files per environment, let's take a look how can use them.

For an environment named development:

  • the definition file has to be named: definition.development.json
  • and you must provide development for the environment parameter (see below)

If you are using the CLI directly the following commands accept the environment:

  • reach-plugin-scripts dev <environment>
  • reach-plugin-scripts generateApiKey <environment>
  • reach-plugin-scripts publishWeb <environment>
  • reach-plugin-scripts publish <environment>
  • reach-plugin-scripts linkToSubscription <environment>

In case you aren't using the CLI directly but instead are using the npm tasks:

  • npm run dev <environment>
  • npm run build <environment>
  • npm run publish <environment>
  • npm run publish-web <environment>
  • npm run link-to-subscription <environment>
  • npm run generate-api-key <environment>