Server API for plugins

🏗 Work in progress

The content of this page might not be fully up-to-date with Strapi 5 yet.

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:

an entry file which export the required interface,
lifecycle functions,
a configuration API,
the ability to add cron jobs,
and the ability to customize all elements of the back-end server.

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 /strapi-server.js|ts or /server/index.js|ts file. However, it's recommended to split the code into different folders, just like the structure created by the strapi generate plugin CLI generator command.

Entry file

To tap into the Server API, create a strapi-server.js file at the root of the plugin package folder. This file exports the required interface, with the following parameters available:

Parameter type	Available parameters
Lifecycle functions	register bootstrap destroy
Configuration	config object Cron
Backend customizations	contentTypes routes controllers services policies middlewares

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/strapi-server.js

module.exports = () => ({
  register({ strapi }) {
    // execute some register code
  },
});

bootstrap()

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

Type: Function

Example:

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

module.exports = () => ({
  bootstrap({ strapi }) {
    // execute some bootstrap code
  },
});

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/strapi-server.js

module.exports = () => ({
  destroy({ strapi }) {
    // execute some destroy code
  },
});

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

Parameter	Type	Description
`default`	Object, or Function that returns an Object	Default plugin configuration, merged with the user configuration
`validator`	Function	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/strapi-server.js or ./src/plugins/my-plugin/server/index.js

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

module.exports = () => ({
  config: {
    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.

Cron

The cron object allows you to add cron jobs to the Strapi instance.

./src/plugins/my-plugin/strapi-server.js
module.exports = () => ({
  bootstrap({ strapi }) {
    strapi.cron.add({
      // runs every second
      myJob: {
        task: ({ strapi }) => {
          console.log("hello from plugin");
        },
        options: {
          rule: "* * * * * *",
        },
      },
    });
  },
});

To remove a CRON job you can call the remove function on the strapi.cron object and pass in the key corresponding to the CRON job you want to remove.

✏️ Note

Cron jobs that are using the key as the rule can not be removed.

strapi.cron.remove("myJob");

List cron jobs

To list all the cron jobs that are currently running you can call the jobs array on the strapi.cron object.

strapi.cron.jobs

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/strapi-server.js

"use strict";

module.exports = require('./server');

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

const contentTypes = require('./content-types');

module.exports = () => ({
  contentTypes,
});

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

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 },
};

path: ./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:

Content API routes only
Content API and admin routes

path: ./src/plugins/my-plugin/strapi-server.js

"use strict";

module.exports = require('./server');

path: ./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
});

path: ./src/plugins/my-plugin/server/routes/index.js

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

It is also possible to combine both admin and Content API routes if you need different policies on these:

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

module.exports = {
  admin: require('./admin'),
  'content-api': require('./content-api'),
};

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

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

./src/plugins/my-plugin/server/routes/content-api/index.js

module.exports = {
  type: 'content-api',
  routes: [{
    method: 'GET',
    path: '/model',
    handler: 'controllerName.action',
    config: {
      policies: ['differentPolicyName'],
    },
  }],
};

Controllers

An object with the controllers the plugin provides.

Type: Object

Example:

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

"use strict";

module.exports = require('./server');

./src/plugins/my-plugin/server/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

module.exports = ({ strapi }) => ({
  doSomething(ctx) {
    ctx.body = { message: 'HelloWorld' };
  },
});

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/strapi-server.js

"use strict";

module.exports = require('./server');

./src/plugins/my-plugin/server/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

module.exports = ({ strapi }) => ({
  someFunction() {
    return [1, 2, 3];
  },
});

Policies

An object with the policies the plugin provides.

Type: Object

Example:

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

"use strict";

module.exports = require('./server');

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

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');

🤓 Entity Service API

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

Server API for plugins

Entry file​

Lifecycle functions​

register()​

bootstrap()​

destroy()​

Configuration​

Cron​

List cron jobs​

Backend customization​

Content-types​

Routes​

Controllers​

Services​

Policies​

Middlewares​

Usage​

Entry file

Lifecycle functions

register()

bootstrap()

destroy()

Configuration

Cron

List cron jobs

Backend customization

Content-types

Routes

Controllers

Services

Policies

Middlewares

Usage