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.
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.
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 | |
| 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:
module.exports = () ({
register({ strapi }) {
// execute some register code
},
});
bootstrap()​
The bootstrap function is called right after the plugin has registered.
Type: Function
Example:
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:
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 |
|
Example:
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.
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.
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.
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.
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
Content-Types keys in the contentTypes object should re-use the singularName defined in the info key of the schema.
Example:
"use strict";
module.exports = require('./server');
const contentTypes = require('./content-types');
module.exports = () ({
contentTypes,
});
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 },
};
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:
"use strict";
module.exports = require('./server');
const routes = require('./routes');
module.exports = () ({
routes,
type: 'content-api', // can also be 'admin' depending on the type of route
});
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:
module.exports = {
admin: require('./admin'),
'content-api': require('./content-api'),
};
module.exports = {
type: 'admin',
routes: [{
method: 'GET',
path: '/model',
handler: 'controllerName.action',
config: {
policies: ['policyName'],
},
}],
};
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:
"use strict";
module.exports = require('./server');
const controllers = require('./controllers');
module.exports = () ({
controllers,
});
const controllerA = require('./controller-a');
const controllerB = require('./controller-b');
module.exports = {
controllerA,
controllerB,
};
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:
"use strict";
module.exports = require('./server');
const services = require('./services');
module.exports = () ({
services,
});
const serviceA = require('./service-a');
const serviceB = require('./service-b');
module.exports = {
serviceA,
serviceB,
};
module.exports = ({ strapi }) ({
someFunction() {
return [1, 2, 3];
},
});
Policies​
An object with the policies the plugin provides.
Type: Object
Example:
"use strict";
module.exports = require('./server');
const policies = require('./policies');
module.exports = () ({
policies,
});
const policyA = require('./policy-a');
const policyB = require('./policy-b');
module.exports = {
policyA,
policyB,
};
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:
/**
* 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();
}
/**
* 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
};
/**
* 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');
:::strapi Entity Service API To interact with the content-types, use the Entity Service API. :::