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.