Local plugins

    Create a development project

    1. Create a new project cd .. && strapi new myDevelopmentProject.
    2. cd myDevelopmentProject && strapi develop To start the Strapi project

    Plugin development Setup

    In a new terminal window:

    Generate a new plugin: cd /path/to/myDevelopmentProject && strapi generate:plugin my-plugin

    NOTE

    After you have successfully generated a plugin, you need to run strapi build which adds the new plugin to the admin panel.

    Plugin Folders and Files Architecture

    The logic of a plugin is located at its root directory ./plugins/**. The admin panel related parts of each plugin are contained in the /admin folder. The folders and files structure are the following:

    This section explains how the ‘back-end part’ of your plugin works.

    Routes

    The plugin API routes are defined in the ./plugins/**/config/routes.json file.

    TIP

    Please refer to for information.

    Route prefix

    Each route of a plugin is prefixed by the name of the plugin (eg: /my-plugin/my-plugin-route). Using the prefix key you can change this option to something custom. You can disable the prefix, by setting the config.prefix key to an empty string.

    1. {
    2.   "method": "GET",
    3.   "path": "/my-plugin-route",
    4.   "handler": "MyPlugin.action",
    5.   "config": {
    6.     "policies": [],
    7.     "prefix": "my-custom-prefix"
    8.   }
    9. }

    CLI

    The CLI can be used to generate files in the plugins folders.

    Please refer to the for more information.

    Controllers contain functions executed according to the requested route.

    Please refer to the Controllers documentation for more information.

    Models

    A plugin can have its own models.

    Table/Collection naming

    Sometimes it happens that the plugins inject models that have the same name as yours. Let’s take a quick example.

    You already have User model defining in your ./api/user/models/User.settings.json API. And you decide to install the Users & Permissions plugin. This plugin also contains a User model. To avoid the conflicts, the plugins’ models are not globally exposed which means you cannot access to the plugin’s model like this:

    1. module.exports = {
    2.   findUser: async function(params) {
    3.     // This `User` global variable will always make a reference the User model defining in your `./api/xxx/models/User.settings.json`.
    4.     return await User.find();
    5.   },
    6. };

    Also, the table/collection name won’t be users because you already have a User model. That’s why, the framework will automatically prefix the table/collection name for this model with the name of the plugin. Which means in our example, the table/collection name of the User model of our plugin Users & Permissions will be users-permissions_users. If you want to force the table/collection name of the plugin’s model, you can add the collectionName attribute in your model.

    Please refer to the for more information.

    Policies

    Global policies

    A plugin can also use a globally exposed policy in the current Strapi project.

    1. {
    2.   "routes": [
    3.     {
    4.       "method": "GET",
    5.       "path": "/",
    6.       "handler": "MyPlugin.index",
    7.       "config": {
    8.         "policies": ["global::isAuthenticated"]
    9.       }
    10.     }
    11.   ]
    12. }

    Plugin policies

    A plugin can have its own policies, such as adding security rules. For instance, if the plugin includes a policy named isAuthenticated, the syntax to use this policy would be:

    1. {
    2.   "routes": [
    3.     {
    4.       "method": "GET",
    5.       "path": "/",
    6.       "handler": "MyPlugin.index",
    7.       "config": {
    8.         "policies": ["plugins::myplugin.isAuthenticated"]
    9.       }
    10.     }
    11.   ]
    12. }

    Please refer to the for more information.

    Front-end Development

    Strapi’s admin panel and plugins system aim to be an easy and powerful way to create new features.

    The admin panel is a application which can embed other React applications. These other React applications are the admin parts of each Strapi’s plugins.

    Environment setup

    To enable local plugin development, you need to start your application with the front-end development mode activated:

    1. $ cd my-app
    2. $ yarn develop --watch-admin
    1. $ cd my-app
    2. $ npm run develop -- --watch-admin

    Strapi global variable

    The administration exposes a global variable that is accessible for all the plugins.

    strapi.backendURL

    Retrieve the back-end URL. (e.g. http://localhost:1337).

    strapi.currentLanguage

    Retrieve the administration panel default language (e.g. en-US)

    strapi.languages

    Array of the administration panel’s supported languages. (e.g. ['ar', 'en', 'fr', ...]).

    strapi.lockApp()
    strapi.unlockApp()

    Remove the loader so the user can interact with the application

    strapi.notification

    Use this command anywhere in your code.

    1. strapi.notification.toggle(config);

    The properties of the config object are as follows:

    The previous notification API is still working but will display a warning message in the console

    strapi.remoteURL

    The administration url (e.g. http://localhost:4000/admin).

    Main plugin object

    Each plugin exports all its configurations in an object. This object is located in my-plugin/admin/src/index.js

    Here are its properties:

    Displaying the plugin’s link in the main menu

    To display a plugin link into the main menu the plugin needs to export a menu object.

    Path — plugins/my-plugin/admin/src/index.js.

    1. import pluginPkg from '../../package.json';
    2. import pluginLogo from './assets/images/logo.svg';
    3. import App from './containers/App';
    4. import lifecycles from './lifecycles';
    5. import trads from './translations';
    6. import pluginId from './pluginId';
    8. export default strapi => {
    9.   const pluginDescription = pluginPkg.strapi.description || pluginPkg.description;
    10.   const icon = pluginPkg.strapi.icon;
    11.   const name = pluginPkg.strapi.name;
    12.   const plugin = {
    13.     blockerComponent: null,
    14.     blockerComponentProps: {},
    15.     description: pluginDescription,
    16.     icon,
    17.     id: pluginId,
    18.     initializer: null,
    19.     isRequired: pluginPkg.strapi.required || false,
    20.     layout: null,
    21.     lifecycles,
    22.     mainComponent: App,
    23.     name,
    24.     pluginLogo,
    25.     preventComponentRendering: false,
    26.     trads,
    27.     menu: {
    28.       // Set a link into the PLUGINS section
    29.       pluginsSectionLinks: [
    30.         {
    31.           destination: `/plugins/${pluginId}`, // Endpoint of the link
    32.           icon,
    33.           label: {
    34.             id: `${pluginId}.plugin.name`, // Refers to a i18n
    35.             defaultMessage: 'My PLUGIN',
    36.           },
    37.           name,
    38.           // If the plugin has some permissions on whether or not it should be accessible
    39.           // depending on the logged in user's role you can set them here.
    40.           // Each permission object performs an OR comparison so if one matches the user's ones
    41.           // the link will be displayed
    42.           permissions: [{ action: 'plugins::content-type-builder.read', subject: null }],
    43.         },
    44.       ],
    45.     },
    46.   };
    48.   return strapi.registerPlugin(plugin);
    49. };

    Initializer

    The component is generated by default when you create a new plugin. Use this component to execute some logic when the app is loading. When the logic has been executed this component should emit the isReady event so the user can interact with the application.

    NOTE

    Below is the Initializer component of the content-type-builder plugin.

    It checks whether or not the auto-reload feature is enabled and depending on this value changes the mainComponent of the plugin.

    1. /**
    2.  *
    3.  * Initializer
    4.  *
    5.  */
    7. import React from 'react';
    8. import PropTypes from 'prop-types';
    10. import pluginId from '../../pluginId';
    12. class Initializer extends React.PureComponent {
    13.   // eslint-disable-line react/prefer-stateless-function
    14.   componentDidMount() {
    15.     const {
    16.       admin: { autoReload, currentEnvironment },
    17.     } = this.props;
    19.     let preventComponentRendering;
    20.     let blockerComponentProps;
    22.     if (currentEnvironment === 'production') {
    23.       preventComponentRendering = true;
    24.       blockerComponentProps = {
    25.         blockerComponentTitle: 'components.ProductionBlocker.header',
    26.         blockerComponentDescription: 'components.ProductionBlocker.description',
    27.         blockerComponentIcon: 'fa-ban',
    28.         blockerComponentContent: 'renderButton',
    29.       };
    30.     } else {
    31.       // Don't render the plugin if the server autoReload is disabled
    32.       preventComponentRendering = !autoReload;
    33.       blockerComponentProps = {
    34.         blockerComponentTitle: 'components.AutoReloadBlocker.header',
    35.         blockerComponentDescription: 'components.AutoReloadBlocker.description',
    36.         blockerComponentIcon: 'fa-refresh',
    37.         blockerComponentContent: 'renderIde',
    38.       };
    39.     }
    41.     // Prevent the plugin from being rendered if currentEnvironment === PRODUCTION
    42.     this.props.updatePlugin(pluginId, 'preventComponentRendering', preventComponentRendering);
    43.     this.props.updatePlugin(pluginId, 'blockerComponentProps', blockerComponentProps);
    44.     // Emit the event plugin ready
    45.     this.props.updatePlugin(pluginId, 'isReady', true);
    46.   }
    48.   render() {
    49.     return null;
    50.   }
    51. }
    52. Initializer.propTypes = {
    53.   admin: PropTypes.object.isRequired,
    54.   updatePlugin: PropTypes.func.isRequired,
    55. };
    57. export default Initializer;

    Injected Components

    (Coming soon)

    Routing

    The routing is based on the React Router V5Local plugins - 图3 (opens new window), due to it’s implementation each route is declared in the containers/App/index.js file.

    TIP

    Each route defined in a plugin must be prefixed by the plugin’s id.

    Route declaration :

    Let’s say that you want to create a route /user with params /:id associated with the container UserPage.

    The declaration would be as follows :

    Path — plugins/my-plugin/admin/src/containers/App/index.js.

    1. import React from 'react';
    2. import pluginId from '../../pluginId';
    4. import UserPage from '../UserPage';
    6. // ...
    8. class App extends React.Component {
    9.   // ...
    11.   render() {
    12.     return (
    13.       <div>
    14.         <Switch>
    15.           <Route exact path={`/plugins/${pluginId}/user/:id`} component={UserPage} />
    16.         </Switch>
    17.       </div>
    18.     );
    19.   }
    20. }
    22. // ...

    Styling

    The administration panel uses styled-components (opens new window) for writing css.

    i18n

    React IntlLocal plugins - 图5 (opens new window) provides React components and an API to format dates, numbers, and strings, including pluralization and handling translations.

    Usage

    We recommend to set all your components text inside the translations folder.

    The example below shows how to use i18n inside your plugin.

    Define all your ids with the associated message:

    Path — ./plugins/my-plugin/admin/src/translations/en.json.

    1. {
    2.   "notification.error.message": "An error occurred"
    3. }

    Path — ./plugins/my-plugin/admin/src/translations/fr.json

    1. {
    2.   "notification.error.message": "Une erreur est survenue"
    3. }

    Usage inside a component

    Path — ./plugins/my-plugin/admin/src/components/Foo/index.js.

    1. import { FormattedMessage } from 'react-intl';
    2. import SomeOtherComponent from 'components/SomeOtherComponent';
    4. const Foo = props => (
    5.   <div className={styles.foo}>
    6.     <FormattedMessage id="my-plugin.notification.error.message" />
    7.     <SomeOtherComponent {...props} />
    8.   </div>
    9. );
    11. export default Foo;

    Global context

    All plugins are wrapped inside the GlobalContextProvider, in this object you will have access to all plugins object as well as other utilities.

    Usage:

    Inside a functional component:

    1. import React from 'react';
    2. import { useGlobalContext } from 'strapi-helper-plugin';
    4. const Foo = () => {
    5.   const globalContext = useGlobalContext();
    7.   console.log(globalContext);
    9.   return <div>Foo</div>;
    10. };

    Inside a class component:

    As plugins developer you may need to add custom fields in your application. To do so, a Field API is available in order for a plugin to register a field which will be available for all plugins.

    NOTE

    Currently, only the content manager uses this API to extend its current fields.

    Registering a new field

    Registering a field can be made in two different ways:

    1. During the load phase of a plugin
    2. Using the provided react-hook in a component.

    Registering a field during the load of a plugin

    Registering a field during the load phase of a plugin can be done as follows:

    1. Create a new Field type (in this example a media field type):

    Path — plugins/my-plugin/admin/src/components/InputMedia/index.js.

    1. import React from 'react';
    2. const InputMedia = props => {
    3.   // Check out the provided props
    4.   console.log(props);
    6.   return <div>InputMedia</div>;
    7. };
    9. export default InputMedia;
    1. Register the field into the application:

    Path — plugins/my-plugin/admin/src/index.js.

    1. import pluginPkg from '../../package.json';
    2. import InputMedia from './components/InputMedia';
    3. import pluginId from './pluginId';
    5. export default strapi => {
    6.   const pluginDescription = pluginPkg.strapi.description || pluginPkg.description;
    8.   const plugin = {
    9.     blockerComponent: null,
    10.     blockerComponentProps: {},
    11.     description: pluginDescription,
    12.     icon: pluginPkg.strapi.icon,
    13.     id: pluginId,
    14.     initializer: () => null,
    15.     injectedComponents: [],
    16.     isReady: true,
    17.     mainComponent: null,
    18.     name: pluginPkg.strapi.name,
    19.     preventComponentRendering: false,
    20.     trads: {},
    21.   };
    23.   strapi.registerField({ type: 'media', Component: InputMedia });
    25.   return strapi.registerPlugin(plugin);
    26. };

    By doing so, all the plugins from your project will be able to use the newly registered Field type.

    Registering a field inside a React Component

    The other way to register a Field is to use the provided react-hook: useStrapi it can be done in the Initializer Component so it is accessible directly when the user is logged in, if you decide to register your plugin in another component than the Initializer the Field will only be registered in the administration panel once the component is mounted (the user has navigated to the view where the Field is registered).

    1. Register the Field in the Initializer Component:

    Path — plugins/my-plugin/admin/src/containers/Initializer/index.js.

    1. /**
    2.  *
    3.  * Initializer
    4.  *
    5.  */
    7. import { useEffect, useRef } from 'react';
    8. import PropTypes from 'prop-types';
    9. import { useStrapi } from 'strapi-helper-plugin';
    10. import pluginId from '../../pluginId';
    11. import InputMedia from './components/InputMedia';
    13. const Initializer = ({ updatePlugin }) => {
    14.   const {
    15.     strapi: { fieldApi },
    16.   } = useStrapi();
    17.   const ref = useRef();
    18.   ref.current = updatePlugin;
    20.   useEffect(() => {
    21.     // Register the new field
    22.     fieldApi.registerField({ type: 'media', Component: InputMedia });
    24.     ref.current(pluginId, 'isReady', true);
    25.   }, []);
    27.   return null;
    28. };
    30. Initializer.propTypes = {
    31.   updatePlugin: PropTypes.func.isRequired,
    32. };
    34. export default Initializer;
    1. Add the Initializer component to your plugin so it is mounted in the administration panel once the user is logged in:
    1. import pluginPkg from '../../package.json';
    2. import pluginLogo from './assets/images/logo.svg';
    3. import App from './containers/App';
    4. import Initializer from './containers/Initializer';
    5. import lifecycles from './lifecycles';
    6. import trads from './translations';
    7. import pluginId from './pluginId';
    9. export default strapi => {
    10.   const pluginDescription = pluginPkg.strapi.description || pluginPkg.description;
    11.   const plugin = {
    12.     blockerComponent: null,
    13.     blockerComponentProps: {},
    14.     description: pluginDescription,
    15.     icon: pluginPkg.strapi.icon,
    16.     id: pluginId,
    17.     initializer: Initializer,
    18.     injectedComponents: [],
    19.     isRequired: pluginPkg.strapi.required || false,
    20.     layout: null,
    21.     lifecycles,
    22.     mainComponent: App,
    23.     name: pluginPkg.strapi.name,
    24.     pluginLogo,
    25.     preventComponentRendering: false,
    26.     trads,
    27.   };
    29.   return strapi.registerPlugin(plugin);
    30. };

    Consuming the Field API

    Consuming the Field API can only be done by using the provided react-hook useStrapi. Here’s an example from the content-manager plugin:

    Path — ~/strapi-plugin-content-manager/admin/src/components/Inputs/index.js.

    1. import React, { memo, useMemo } from 'react';
    2. // Other imports
    3. // ...
    4. // Import the Inputs component from our component library Buffet.js
    5. import { Inputs as InputsIndex } from '@buffetjs/custom';
    7. // Import the Hook with which you can access the Field API
    8. import { useStrapi } from 'strapi-helper-plugin';
    10. function Inputs({ autoFocus, keys, layout, name, onBlur }) {
    11.   // This is where you will access the field API
    12.   const {
    13.     strapi: { fieldApi },
    14.   } = useStrapi();
    16.   // Other boilerplate code
    17.   // ...
    19.   return (
    20.     <FormattedMessage id={errorId}>
    21.       {error => {
    22.         return (
    23.           <InputsIndex
    24.             {...metadatas}
    25.             autoComplete="new-password"
    26.             autoFocus={autoFocus}
    27.             didCheckErrors={didCheckErrors}
    28.             disabled={disabled}
    29.             error={
    30.                 ? null
    31.                 : error
    32.             }
    33.             inputDescription={description}
    34.             description={description}
    35.             contentTypeUID={layout.uid}
    36.             customInputs={{
    37.               json: InputJSONWithErrors,
    38.               wysiwyg: WysiwygWithErrors,
    39.               uid: InputUID,
    41.               // Retrieve all the fields that other plugins have registered
    42.               ...fieldApi.getFields(),
    43.             }}
    44.             multiple={get(attribute, 'multiple', false)}
    45.             attribute={attribute}
    46.             name={keys}
    47.             onBlur={onBlur}
    48.             onChange={onChange}
    49.             options={enumOptions}
    50.             step={step}
    51.             type={getInputType(type)}
    52.             validations={validations}
    53.             value={inputValue}
    54.             withDefaultValue={false}
    55.           />
    56.         );
    57.       }}
    58.     </FormattedMessage>
    59.   );
    60. }

    Field API definition

    Plugin’s front-end settings API

    As plugins developer you may need to add some settings into the main application Settings view (it corresponds to the Settings link located in the menu). To do so an API is available in order for a plugin to add links into the main view.

    These settings can be declared directly into the main plugin object so they will dynamically be injected into the view.

    The front-end part of a plugin exports a function which registers the plugin in the administration panel. The argument is composed of two main parameters:

    • registerPlugin: Function
    • settingsBaseURL: String

    Creating the links into the view’s menu

    Each plugin that comes with a setting object will create a new section into the view’s menu.

    The menu section can be declared as follows:

    Path — plugins/my-plugin/admin/src/index.js.

    1. import pluginPkg from '../../package.json';
    2. import pluginId from './pluginId';
    4. export default strapi => {
    5.   const pluginDescription = pluginPkg.strapi.description || pluginPkg.description;
    7.   // Declare the links that will be injected into the settings menu
    8.   const menuSection = {
    9.     // Unique id of the section
    10.     id: pluginId,
    11.     // Title of Menu section using i18n
    12.     title: {
    13.       id: `${pluginId}.foo`,
    14.       defaultMessage: 'Super cool setting',
    15.     },
    16.     // Array of links to be displayed
    17.     links: [
    18.       {
    19.         // Using string
    20.         title: 'Setting page 1',
    21.         to: `${strapi.settingsBaseURL}/${pluginId}/setting1`,
    22.         name: 'setting1',
    23.         permissions: [{ action: 'plugins::my-plugin.action-name', subject: null }], // This key is not mandatory it can be null, undefined or an empty array
    24.       },
    25.       {
    26.         // Using i18n with a corresponding translation key
    27.         title: {
    28.           id: `${pluginId}.bar`,
    29.           defaultMessage: 'Setting page 2',
    30.         },
    31.         to: `${strapi.settingsBaseURL}/${pluginId}/setting2`,
    32.         name: 'setting2',
    33.         // Define a specific component if needed:
    34.         Component: () => <div />,
    35.       },
    36.     ],
    37.   };
    39.   const plugin = {
    40.     blockerComponent: null,
    41.     blockerComponentProps: {},
    42.     description: pluginDescription,
    43.     icon: pluginPkg.strapi.icon,
    44.     id: pluginId,
    45.     initializer: () => null,
    46.     injectedComponents: [],
    47.     isReady: true,
    48.     mainComponent: null,
    49.     name: pluginPkg.strapi.name,
    50.     preventComponentRendering: false,
    51.     settings: {
    52.       menuSection,
    53.     },
    54.     trads: {},
    55.   };
    57.   return strapi.registerPlugin(plugin);
    58. };

    At this point, the plugin creates a new section (Super cool setting) which will contains two links Setting page 1 and Setting page 2 these links don’t point to any component as the corresponding one as not been declared yet.

    Declaring the setting Component

    The exported Setting component which receives settingsBaseURL as props in order to generate a dynamic routing which should be used to associate the two endpoints created with their corresponding components.

    With the configuration from above we could easily create our plugin Settings view.

    Path — plugins/my-plugin/admin/src/containers/Settings/index.js.

    1. import React from 'react';
    2. import PropTypes from 'prop-types';
    3. import { Switch, Route } from 'react-router-dom';
    4. import pluginId from '../../pluginId';
    6. const SettingPage1 = () => (
    7.   <div>
    8.     <h1>Setting Page 1</h1>
    9.   </div>
    10. );
    11. const SettingPage2 = () => (
    12.   <div>
    13.     <h1>Setting Page 2</h1>
    14.   </div>
    15. );
    17. const Settings = ({ settingsBaseURL }) => {
    18.   return (
    19.     <Switch>
    20.       <Route component={SettingPage1} path={`${settingsBaseURL}/${pluginId}/setting1`} />
    21.       <Route component={SettingPage2} path={`${settingsBaseURL}/${pluginId}/setting2`} />
    22.     </Switch>
    23.   );
    24. };
    26. Settings.propTypes = {
    27.   settingsBaseURL: PropTypes.string.isRequired,
    28. };
    30. export default Settings;

    Now that the Settings component is declared in your plugin the only thing left is to add it to your settings configuration:

    Path — plugins/my-plugin/admin/src/index.js.

    Adding a setting into the global section

    In order to add a link into the global section of the settings view you need to create a global array containing the links you want to add:

    Path — plugins/my-plugin/admin/src/index.js.

    1. import pluginPkg from '../../package.json';
    2. // Import the component
    3. import Settings from './containers/Settings';
    4. import SettingLink from './components/SettingLink';
    5. import pluginId from './pluginId';
    7. export default strapi => {
    8.   const pluginDescription = pluginPkg.strapi.description || pluginPkg.description;
    10.   // Declare the links that will be injected into the settings menu
    11.   const menuSection = {
    12.     id: pluginId,
    13.     title: {
    14.       id: `${pluginId}.foo`,
    15.       defaultMessage: 'Super cool setting',
    16.     },
    17.     links: [
    18.       {
    19.         title: 'Setting page 1',
    20.         to: `${strapi.settingsBaseURL}/${pluginId}/setting1`,
    21.         name: 'setting1',
    22.       },
    23.       {
    24.         title: {
    25.           id: `${pluginId}.bar`,
    26.           defaultMessage: 'Setting page 2',
    27.         },
    28.         to: `${strapi.settingsBaseURL}/${pluginId}/setting2`,
    29.         name: 'setting2',
    30.       },
    31.     ],
    32.   };
    34.   const plugin = {
    35.     blockerComponent: null,
    36.     blockerComponentProps: {},
    37.     description: pluginDescription,
    38.     icon: pluginPkg.strapi.icon,
    39.     id: pluginId,
    40.     initializer: () => null,
    41.     injectedComponents: [],
    42.     isReady: true,
    43.     mainComponent: null,
    44.     name: pluginPkg.strapi.name,
    45.     preventComponentRendering: false,
    46.     settings: {
    47.       // Add a link into the global section of the settings view
    48.       global: {
    49.         links: [
    50.           {
    51.             title: 'Setting link 1',
    52.             to: `${strapi.settingsBaseURL}/setting-link-1`,
    53.             name: 'settingLink1',
    54.             Component: SettingLink,
    55.             // Bool : https://reacttraining.com/react-router/web/api/Route/exact-bool
    56.             exact: false,
    57.             permissions: [{ action: 'plugins::my-plugin.action-name', subject: null }],
    58.           },
    59.         ],
    60.       },
    61.       mainComponent: Settings,
    62.       menuSection,
    63.     },
    64.     trads: {},
    65.   };
    67.   return strapi.registerPlugin(plugin);

    WARNING