Skip to main content

Server API for plugins

A Strapi plugin can interact with both the back end and the front end of a Strapi application. The Server API is about the back-end part, i.e. how the plugin interacts with the server part of a Strapi application.

Prerequisites

You have created a Strapi plugin.

The Server API includes:

Once you have declared and exported the plugin interface, you will be able to use the plugin interface.

Note

The whole code for the server part of your plugin could live in the /server/src/index.ts|js file. However, it's recommended to split the code into different folders, just like the structure created by the Plugin SDK.

Entry file​

The /src/server/index.js file at the root of the plugin folder exports the required interface, with the following parameters available:

Parameter typeAvailable parameters
Lifecycle functions
Configuration
Backend customizations

Lifecycle functions​

register()​

This function is called to load the plugin, before the application is bootstrapped, in order to register permissions, the server part of custom fields, or database migrations.

Type: Function

Example:

/src/plugins/my-plugin/server/src/register.js

'use strict';

const register = ({ strapi }) => {
  // execute some register code
};

module.exports = register;

bootstrap()​

The bootstrap function is called right after the plugin has registered.

Type: Function

Example:

/src/plugins/my-plugin/server/src/bootstrap.js
'use strict';

const bootstrap = ({ strapi }) => {
  // execute some bootstrap code
};

module.exports = bootstrap;

destroy()​

The destroy lifecycle function is called to cleanup the plugin (close connections, remove listeners, etc.) when the Strapi instance is destroyed.

Type: Function

Example:

/src/plugins/my-plugin/server/src/destroy.js
'use strict';

const destroy = ({ strapi }) => {
  // execute some destroy code
};

module.exports = destroy;

Configuration​

config stores the default plugin configuration. It loads and validates the configuration inputted from the user within the ./config/plugins.js configuration file.

Type: Object

ParameterTypeDescription
defaultObject, or Function that returns an ObjectDefault plugin configuration, merged with the user configuration
validatorFunction
  • Checks if the results of merging the default plugin configuration with the user configuration is valid
  • Throws errors when the resulting configuration is invalid

Example:

/src/plugins/my-plugin/server/src/config/index.js

module.exports = {
  default: ({ env }) => ({ optionA: true }),
  validator: (config) => { 
    if (typeof config.optionA !== 'boolean') {
      throw new Error('optionA has to be a boolean');
    }
  },
};

Once defined, the configuration can be accessed:

  • with strapi.plugin('plugin-name').config('some-key') for a specific configuration property,
  • or with strapi.config.get('plugin.plugin-name') for the whole configuration object.
Tip

Run yarn strapi console or npm run strapi console to access the strapi object in a live console.

Backend customization​

All elements of the back-end server of Strapi can be customized through a plugin using the Server API.

Prerequisites

To better understand this section, ensure you have read through the back-end customization documentation of a Strapi application.

Content-types​

An object with the content-types the plugin provides.

Type: Object

Note

Content-Types keys in the contentTypes object should re-use the singularName defined in the info key of the schema.

Example:

/src/plugins/my-plugin/server/content-types/index.js

'use strict';

const contentTypeA = require('./content-type-a');
const contentTypeB = require('./content-type-b');

module.exports = {
  'content-type-a': { schema: contentTypeA }, // should re-use the singularName of the content-type
  'content-type-b': { schema: contentTypeB },
};
/src/plugins/my-plugin/server/content-types/content-type-a.js

module.exports = {
  kind: 'collectionType',
  collectionName: 'content-type',
  info: {
    singularName: 'content-type-a', // kebab-case mandatory
    pluralName: 'content-type-as', // kebab-case mandatory
    displayName: 'Content Type A',
    description: 'A regular content-type',
  },
  options: {
    draftAndPublish: true,
  },
  pluginOptions: {
    'content-manager': {
      visible: false,
    },
    'content-type-builder': {
      visible: false,
    }
  },
  attributes: {
    name: {
      type: 'string',
      min: 1,
      max: 50,
      configurable: false,
    },
  }
};

Routes​

An array of routes configuration.

Type: Object[]

Examples:

/src/plugins/my-plugin/server/index.js

const routes = require('./routes');

module.exports = () => ({
  routes,
  type: 'content-api', // can also be 'admin' depending on the type of route
});
/src/plugins/my-plugin/server/routes/index.js

module.exports = [
  {
    method: 'GET',
    path: '/model',
    handler: 'controllerName.action',
    config: {
      policies: ['policyName'],
    },
  },
];

Controllers​

An object with the controllers the plugin provides.

Type: Object

Example:

/src/plugins/my-plugin/server/src/index.js

//…
const controllers = require('./controllers');
//…

module.exports = () => ({
  //…
  controllers,
  //…
});
/src/plugins/my-plugin/server/controllers/index.js

const controllerA = require('./controller-a');
const controllerB = require('./controller-b');

module.exports = {
  controllerA,
  controllerB,
};
/src/plugins/my-plugin/server/controllers/controller-a.js

'use strict';

const controllerA = ({ strapi }) => ({
  index(ctx) {
    ctx.body = strapi
      .plugin('my-strapi-plugin')
      // the name of the service file & the method.
      .service('service')
      .getWelcomeMessage();
  },
});

module.exports = controllerA;

Services​

An object with the services the plugin provides.

Services should be functions taking strapi as a parameter.

Type: Object

Example:

/src/plugins/my-plugin/server/src/index.js

// …
const services = require('./services');
// …

module.exports = () => ({
  // …
  services,
  // …
});
/src/plugins/my-plugin/server/services/index.js

const serviceA = require('./service-a');
const serviceB = require('./service-b');

module.exports = {
  serviceA,
  serviceB,
};
./src/plugins/my-plugin/server/services/service-a.js

'use strict';

const service = ({ strapi }) => ({
  getWelcomeMessage() {
    return 'Welcome to Strapi 🚀';
  },
});

module.exports = service;

Policies​

An object with the policies the plugin provides.

Type: Object

Example:

/src/plugins/my-plugin/server/src/index.js

"use strict";

//…
const policies = require('./policies');
//…

module.exports = {
  //…
  policies,
  //…
};
/src/plugins/my-plugin/server/policies/index.js

const policyA = require('./policy-a');
const policyB = require('./policy-b');

module.exports = {
  policyA,
  policyB,
};
/src/plugins/my-plugin/server/policies/policy-a.js

module.exports = (policyContext, config, { strapi }) => {
  if (ctx.state.user && ctx.state.user.isActive) {
    return true;
  }

  return false;
};

Middlewares​

An object with the middlewares the plugin provides.

Type: Object

Example:

/src/plugins/my-plugin/server/middlewares/your-middleware.js

/** 
 * The your-middleware.js file 
 * declares a basic middleware function and exports it.
 */
'use strict';
module.exports = async (ctx, next) => {
  console.log("your custom logic")
  await next();
}
./src/plugins/my-plugin/server/middlewares/index.js

/**
 * The middleware function previously created
 * is imported from its file and
 * exported by the middlewares index.
 */
'use strict';
const yourMiddleware = require('./your-middleware');

module.exports = {
  yourMiddleware
};
./src/plugins/my-plugin/server/register.js

/**
 * The middleware is called from 
 * the plugin's register lifecycle function.
 */
'use strict';
const middlewares = require('./middlewares');

module.exports = ({ strapi }) => {
  strapi.server.use(middlewares.yourMiddleware);
};

Usage​

Once a plugin is exported and loaded into Strapi, its features are accessible in the code through getters. The Strapi instance (strapi) exposes both top-level getters and global getters:

  • top-level getters imply chaining functions
    (e.g., strapi.plugin('the-plugin-name').controller('the-controller-name'),
  • global getters are syntactic sugar that allows direct access using a feature's uid
    (e.g., strapi.controller('plugin::plugin-name.controller-name')).
// Access an API or a plugin controller using a top-level getter 
strapi.api['api-name'].controller('controller-name')
strapi.plugin('plugin-name').controller('controller-name')

// Access an API or a plugin controller using a global getter
strapi.controller('api::api-name.controller-name')
strapi.controller('plugin::plugin-name.controller-name')
Top-level getter syntax examples
strapi.plugin('plugin-name').config
strapi.plugin('plugin-name').routes
strapi.plugin('plugin-name').controller('controller-name')
strapi.plugin('plugin-name').service('service-name')
strapi.plugin('plugin-name').contentType('content-type-name')
strapi.plugin('plugin-name').policy('policy-name')
strapi.plugin('plugin-name').middleware('middleware-name')
Global getter syntax examples
strapi.controller('plugin::plugin-name.controller-name');
strapi.service('plugin::plugin-name.service-name');
strapi.contentType('plugin::plugin-name.content-type-name');
strapi.policy('plugin::plugin-name.policy-name');
strapi.middleware('plugin::plugin-name.middleware-name');
Document Service API

To interact with the content-types, use the Document Service API.