Create your first CAP plugin

[WouterLemaire]

Why?

A CAP plugin allows you to extend the framework with your own features without touching the core framework. This offers the great possibility to create something generic and share it with the community so other developers can benefit from it.

SAP already provides several plugins listed here: https://cap.cloud.sap/docs/plugins/

But also the SAP community is creating and sharing plugins which you can find on npm: https://www.npmjs.com/search?q=cap%20plugin and on Best of CAP: https://bestofcapjs.org/

How?

It is super easy to create your own CAP plugin. Just follow these steps:

• Create a new folder for the plugin:

• Go in the folder and open cmd
• Run the command “npm init”
  • Fill in all questions similar to I did below:

• Add dev dependencies:
  • npm i -D @sap/cds
• Add peer dependencies for CAP:

"peerDependencies": {
    "@sap/cds": ">=8"
  },

• Add a cds-plugin.js file to the root of your plugin.
  • This will be automatically loaded when a CAP project has the plugin as an npm dependency
  • 
  • This is the place where you can implement the logic for your plugin, similar as you do in a custom server.js implementation.
  • I also came across some errors when testing my plugins locally. To be able to solve this, I use the following way of loading the cap framework in the plugin. Thanks for the tip @pmuessig !
  • 
• Add an index.cds file
  • This allows you to add entities, aspects or any other possible cds artifact to your plugin
  • 
• Example what could be in the index.cds file:

Test the plugin

Before publishing the plugin you need to test this first. This can be done locally by following these steps:

• Create tests folder in your plugin project

• Create a simple CAP project in this test folder:

• Add the plugin as a dependency to the CAP project using the local path, see below.
  • Run npm i after doing this.

• Use the plugin in this local test project and run it

TypeScript CAP plugin:

You can choose to create a plugin in JS or TS. In case of TS, additional configuration is required:

Install the following devdependencies in the CAP plugin

npm i -D @types/node
npm i -D typescript

• As for every TS project, use .ts for your files and write TypeScript.

Before making this available to npm, you have to build TS to JS. Therefore, you have to foresee a build command: “tsc” https://github.com/lemaiwo/cds-plugin-handlers/blob/39300bb3e6e154ba8eac6f709479325cf9cf7fb9/package...

To be able to run this, you also need a tsonfig file in your project:

https://github.com/lemaiwo/cds-plugin-handlers/blob/main/tsconfig.json

Publish

Once the plugin is ready you can make it available to the SAP Community by publishing this to npm.

Run “npm publish” locally or configure GitHub Actions to automatically publish a new version for every release:

• In case of a TypeScript plugin: run tsc first 😉

Once published, you can simple use it as an npm dependency and start using it in your project.

Examples

It might help you to learn how to create a plugin and about the possibilities by looking in already created plugins. Some examples I made or still working on:

• JavaScript example: https://github.com/lemaiwo/ui5-cap-serverside-rendering-plugin
• TypeScript example: https://github.com/lemaiwo/cds-plugin-handlers/tree/main
• Work in progress: https://github.com/spreadsheetimporter/cds-spreadsheetimporter-plugin

This can help you to learn about the possibilities. What helps me a lot are the examples of SAP: https://cap.cloud.sap/docs/plugins . Each plugin can be found on GitHub here: https://github.com/cap-js .

Also CAP plugins of other community members can help you. You can find them on npm and on best of CAP.

Conclusion

If you have anything that can be reused across CAP projects, turn it into a plugin and share it with the community on npm! Once it is on npm, add it to best of CAP: https://bestofcapjs.org/