From 18a3f35350ee660417220d4fb00386151d407cec Mon Sep 17 00:00:00 2001 From: Gabriel <83644514+gpene@users.noreply.github.com> Date: Mon, 20 Jun 2022 13:29:16 +0200 Subject: [PATCH 1/4] adds Using Providers page --- docs/.vuepress/config/sidebar-developer.js | 1 + .../latest/development/using-providers.md | 196 ++++++++++++++++++ 2 files changed, 197 insertions(+) create mode 100644 docs/developer-docs/latest/development/using-providers.md diff --git a/docs/.vuepress/config/sidebar-developer.js b/docs/.vuepress/config/sidebar-developer.js index 9a8dbf3b8b..e728198717 100644 --- a/docs/.vuepress/config/sidebar-developer.js +++ b/docs/.vuepress/config/sidebar-developer.js @@ -222,6 +222,7 @@ const developer = [ ['/developer-docs/latest/development/admin-customization', 'Admin panel customization'], ['/developer-docs/latest/development/plugins-extension.md', 'Plugins extension'], ['/developer-docs/latest/development/plugins-development.md', 'Plugins development'], + ['/developer-docs/latest/development/using-providers.md', 'Using providers'], ], }, { diff --git a/docs/developer-docs/latest/development/using-providers.md b/docs/developer-docs/latest/development/using-providers.md new file mode 100644 index 0000000000..1dadc77872 --- /dev/null +++ b/docs/developer-docs/latest/development/using-providers.md @@ -0,0 +1,196 @@ +--- +title: Using Providers - Strapi Developer Docs +description: Install and use providers to extend the functionality of available plugins. +canonicalUrl: https://docs.strapi.io/developer-docs/latest/development/using-providers.html +--- + +# Using Providers + +Certain [plugins](../../../user-docs/latest/plugins/introduction-to-plugins.md) can be extended via the installation and configuration of additional [providers](../../../user-docs/latest/plugins/introduction-to-plugins.md#providers). + +Providers add an extension to the core capabilities of the plugin, for example to upload media files to Rackspace instead of the local server, or using Amazon SES for emails instead of Sendmail. + +::: note +Only the [Upload](./upload.md) and [Email](./email.md) plugins are currently designed to work with providers. +::: + +For the relevant plugins, there are both official providers maintained by Strapi - discoverable via the [Marketplace](../../../user-docs/latest/plugins/installing-plugins-via-marketplace.md) - and many community maintained providers available via [NPM](https://www.npmjs.com/). + +## Installing providers + +Install new providers using `npm` or `yarn` using the format `@strapi/provider-- --save`. + +For example: + + + + +```sh +# Install the AWS S3 provider for the Upload plugin +npm install @strapi/provider-upload-aws-s3 --save + +# Install the Sendgrid provider for the Email plugin +npm install @strapi/provider-email-sendgrid --save +``` + + + +```sh +# Install the AWS S3 provider for the Upload plugin +yarn add @strapi/provider-upload-aws-s3 + +# Install the Sendgrid provider for the Email plugin +yarn add @strapi/provider-email-sendgrid --save +``` + + + + +## Configuring providers + +Newly installed providers are enabled and configured in the `./config/plugins.js` file. If this file does not exist you must create it. + +Each provider will have different configuration settings available, review the respective entry for that provider in the [Marketplace](../../../user-docs/latest/plugins/installing-plugins-via-marketplace.md) or [NPM](https://www.npmjs.com/) to learn more. + +Below are example configurations for the Upload and Email plugins. + +::: tab Upload + +```js +// path: ./config/plugins.js + +module.exports = ({ env }) => ({ + // ... + upload: { + config: { + provider: 'aws-s3', // For community providers pass the full package name (e.g. provider: 'strapi-provider-upload-google-cloud-storage') + providerOptions: { + accessKeyId: env('AWS_ACCESS_KEY_ID'), + secretAccessKey: env('AWS_ACCESS_SECRET'), + region: env('AWS_REGION'), + params: { + Bucket: env('AWS_BUCKET'), + }, + }, + }, + }, + // ... +}); +``` + +Strapi has a default Security Middleware that has a very strict `contentSecurityPolicy` that limits loading images and media to `"'self'"` only, see the example configuration on the [provider page](https://www.npmjs.com/package/@strapi/provider-upload-aws-s3) or the [middleware documentation](/developer-docs/latest/setup-deployment-guides/configurations/required/middlewares.md#loading-order) for more information. + +::: + +::: tab Email + +```js +module.exports = ({ env }) => ({ + // ... + email: { + config: { + provider: 'sendgrid', // For community providers pass the full package name (e.g. provider: 'strapi-provider-email-mandrill') + providerOptions: { + apiKey: env('SENDGRID_API_KEY'), + }, + settings: { + defaultFrom: 'juliasedefdjian@strapi.io', + defaultReplyTo: 'juliasedefdjian@strapi.io', + testAddress: 'juliasedefdjian@strapi.io', + }, + }, + }, + // ... +}); +``` + +Keep in mind that: + +* When using a different provider per environment, specify the correct configuration in `./config/env/${yourEnvironment}/plugins.js`. See [Environments](/developer-docs/latest/setup-deployment-guides/configurations/optional/environment.md). +* Only one email provider will be active at a time. If the email provider setting isn't picked up by Strapi, verify the `plugins.js` file is in the correct folder. +* When testing the new email provider with those two email templates created during strapi setup, the _shipper email_ on the template defaults to `no-reply@strapi.io` and needs to be updated according to your email provider, otherwise it will fail the test. See: [Configure templates locally](/user-docs/latest/settings/configuring-users-permissions-plugin-settings.md#configuring-email-templates). + +::: + +### Configuration per environment + +When configuring your provider you might want to change the configuration based on the `NODE_ENV` environment variable or use environment specific credentials. + +You can set a specific configuration in the `./config/env/{env}/plugins.js` configuration file and it will be used to overwrite the default configuration. + +## Creating providers + +To implement your own custom provider you must [create a Node.js module](https://docs.npmjs.com/creating-node-js-modules). + +The interface that must be exported depends on the plugin you are developing the provider for. Below are templates for the Upload and Email plugins: + +::: tab Upload + +```js +module.exports = { + init(providerOptions) { + // init your provider if necessary + + return { + upload(file) { + // upload the file in the provider + // file content is accessible by `file.buffer` + }, + uploadStream(file) { + // upload the file in the provider + // file content is accessible by `file.stream` + }, + delete(file) { + // delete the file in the provider + }, + }; + }, +}; +``` +::: + +::: tab Email + +```js +module.exports = { + init: (providerOptions = {}, settings = {}) => { + return { + send: async options => {}, + }; + }, +}; +``` + +In the send function you will have access to: + +* `providerOptions` that contains configurations written in `plugins.js` +* `settings` that contains configurations written in `plugins.js` +* `options` that contains options you send when you call the send function from the email plugin service + +::: + +See the [Strapi maintained providers](https://github.com/strapi/strapi/tree/master/packages/providers) for reference. + +After creating your new provider you can [publish it to NPM](https://docs.npmjs.com/creating-and-publishing-unscoped-public-packages) to share with the community or [use it locally](#local-providers) for your project only. + +### Local providers + +If you want to create your own provider without publishing it on **npm** you can follow these steps: + +1. Create a `providers` folder in your application. +2. Create your provider (e.g. `./providers/strapi-provider--`) +3. Then update your `package.json` to link your `strapi-provider--` dependency to the [local path](https://docs.npmjs.com/files/package.json#local-paths) of your new provider. + +```json +{ + ... + "dependencies": { + ... + "strapi-provider--": "file:providers/strapi-provider--", + ... + } +} +``` + +4. Update your `./config/plugins.js` file to [configure the provider](#configuring-providers). +5. Finally, run `yarn install` or `npm install` to install your new custom provider. \ No newline at end of file From e9b12f3193ccf2f0eaae298d0f0714dfb7636023 Mon Sep 17 00:00:00 2001 From: Gabriel <83644514+gpene@users.noreply.github.com> Date: Tue, 21 Jun 2022 15:18:39 +0200 Subject: [PATCH 2/4] fix tabs --- docs/developer-docs/latest/development/using-providers.md | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/docs/developer-docs/latest/development/using-providers.md b/docs/developer-docs/latest/development/using-providers.md index 1dadc77872..ecf263ad5a 100644 --- a/docs/developer-docs/latest/development/using-providers.md +++ b/docs/developer-docs/latest/development/using-providers.md @@ -54,6 +54,8 @@ Each provider will have different configuration settings available, review the r Below are example configurations for the Upload and Email plugins. +:::: tabs card + ::: tab Upload ```js @@ -112,6 +114,8 @@ Keep in mind that: ::: +:::: + ### Configuration per environment When configuring your provider you might want to change the configuration based on the `NODE_ENV` environment variable or use environment specific credentials. @@ -124,6 +128,8 @@ To implement your own custom provider you must [create a Node.js module](https:/ The interface that must be exported depends on the plugin you are developing the provider for. Below are templates for the Upload and Email plugins: +:::: tabs card + ::: tab Upload ```js @@ -169,6 +175,8 @@ In the send function you will have access to: ::: +:::: + See the [Strapi maintained providers](https://github.com/strapi/strapi/tree/master/packages/providers) for reference. After creating your new provider you can [publish it to NPM](https://docs.npmjs.com/creating-and-publishing-unscoped-public-packages) to share with the community or [use it locally](#local-providers) for your project only. From 8cf2a2ea4ca5e389ff7a77d9119e8e6cdefeb8ef Mon Sep 17 00:00:00 2001 From: Gabriel <83644514+gpene@users.noreply.github.com> Date: Thu, 30 Jun 2022 10:13:25 +0200 Subject: [PATCH 3/4] Update based on feedback --- .../latest/development/using-providers.md | 22 +++++++++---------- 1 file changed, 11 insertions(+), 11 deletions(-) diff --git a/docs/developer-docs/latest/development/using-providers.md b/docs/developer-docs/latest/development/using-providers.md index ecf263ad5a..4a642a1f77 100644 --- a/docs/developer-docs/latest/development/using-providers.md +++ b/docs/developer-docs/latest/development/using-providers.md @@ -11,20 +11,20 @@ Certain [plugins](../../../user-docs/latest/plugins/introduction-to-plugins.md) Providers add an extension to the core capabilities of the plugin, for example to upload media files to Rackspace instead of the local server, or using Amazon SES for emails instead of Sendmail. ::: note -Only the [Upload](./upload.md) and [Email](./email.md) plugins are currently designed to work with providers. +Only the [Upload](../plugins/upload.md) and [Email](../plugins/email.md) plugins are currently designed to work with providers. ::: -For the relevant plugins, there are both official providers maintained by Strapi - discoverable via the [Marketplace](../../../user-docs/latest/plugins/installing-plugins-via-marketplace.md) - and many community maintained providers available via [NPM](https://www.npmjs.com/). +For the relevant plugins, there are both official providers maintained by Strapi - discoverable via the [Marketplace](../../../user-docs/latest/plugins/installing-plugins-via-marketplace.md) - and many community maintained providers available via [npm](https://www.npmjs.com/). ## Installing providers -Install new providers using `npm` or `yarn` using the format `@strapi/provider-- --save`. +New providers can be installed using `npm` or `yarn` using the following format `@strapi/provider-- --save`. For example: - + ```sh # Install the AWS S3 provider for the Upload plugin npm install @strapi/provider-upload-aws-s3 --save @@ -50,7 +50,7 @@ yarn add @strapi/provider-email-sendgrid --save Newly installed providers are enabled and configured in the `./config/plugins.js` file. If this file does not exist you must create it. -Each provider will have different configuration settings available, review the respective entry for that provider in the [Marketplace](../../../user-docs/latest/plugins/installing-plugins-via-marketplace.md) or [NPM](https://www.npmjs.com/) to learn more. +Each provider will have different configuration settings available. Review the respective entry for that provider in the [Marketplace](../../../user-docs/latest/plugins/installing-plugins-via-marketplace.md) or [npm](https://www.npmjs.com/) to learn more. Below are example configurations for the Upload and Email plugins. @@ -80,7 +80,7 @@ module.exports = ({ env }) => ({ }); ``` -Strapi has a default Security Middleware that has a very strict `contentSecurityPolicy` that limits loading images and media to `"'self'"` only, see the example configuration on the [provider page](https://www.npmjs.com/package/@strapi/provider-upload-aws-s3) or the [middleware documentation](/developer-docs/latest/setup-deployment-guides/configurations/required/middlewares.md#loading-order) for more information. +Strapi has a default `security` middleware that has a very strict `contentSecurityPolicy` that limits loading images and media to `"'self'"` only, see the example configuration on the [provider page](https://www.npmjs.com/package/@strapi/provider-upload-aws-s3) or the [middleware documentation](/developer-docs/latest/setup-deployment-guides/configurations/required/middlewares.html#security) for more information. ::: @@ -108,9 +108,9 @@ module.exports = ({ env }) => ({ Keep in mind that: -* When using a different provider per environment, specify the correct configuration in `./config/env/${yourEnvironment}/plugins.js`. See [Environments](/developer-docs/latest/setup-deployment-guides/configurations/optional/environment.md). +* When using a different provider per environment, specify the correct configuration in `./config/env/${yourEnvironment}/plugins.js` (See [Environments](/developer-docs/latest/setup-deployment-guides/configurations/optional/environment.md)). * Only one email provider will be active at a time. If the email provider setting isn't picked up by Strapi, verify the `plugins.js` file is in the correct folder. -* When testing the new email provider with those two email templates created during strapi setup, the _shipper email_ on the template defaults to `no-reply@strapi.io` and needs to be updated according to your email provider, otherwise it will fail the test. See: [Configure templates locally](/user-docs/latest/settings/configuring-users-permissions-plugin-settings.md#configuring-email-templates). +* When testing the new email provider with those two email templates created during strapi setup, the _shipper email_ on the template defaults to `no-reply@strapi.io` and needs to be updated according to your email provider, otherwise it will fail the test (See [Configure templates locally](/user-docs/latest/settings/configuring-users-permissions-plugin-settings.md#configuring-email-templates)). ::: @@ -177,13 +177,13 @@ In the send function you will have access to: :::: -See the [Strapi maintained providers](https://github.com/strapi/strapi/tree/master/packages/providers) for reference. +You can review the [Strapi maintained providers](https://github.com/strapi/strapi/tree/master/packages/providers) for example implementations. -After creating your new provider you can [publish it to NPM](https://docs.npmjs.com/creating-and-publishing-unscoped-public-packages) to share with the community or [use it locally](#local-providers) for your project only. +After creating your new provider you can [publish it to npm](https://docs.npmjs.com/creating-and-publishing-unscoped-public-packages) to share with the community or [use it locally](#local-providers) for your project only. ### Local providers -If you want to create your own provider without publishing it on **npm** you can follow these steps: +If you want to create your own provider without publishing it on npm you can follow these steps: 1. Create a `providers` folder in your application. 2. Create your provider (e.g. `./providers/strapi-provider--`) From a4f37f8a8106e5e783b6f0aa7868becd54162783 Mon Sep 17 00:00:00 2001 From: Gabriel <83644514+gpene@users.noreply.github.com> Date: Mon, 11 Jul 2022 09:48:47 +0200 Subject: [PATCH 4/4] feedback revisions --- docs/developer-docs/latest/development/using-providers.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/docs/developer-docs/latest/development/using-providers.md b/docs/developer-docs/latest/development/using-providers.md index 4a642a1f77..c749d9c5dd 100644 --- a/docs/developer-docs/latest/development/using-providers.md +++ b/docs/developer-docs/latest/development/using-providers.md @@ -24,7 +24,7 @@ For example: - + ```sh # Install the AWS S3 provider for the Upload plugin npm install @strapi/provider-upload-aws-s3 --save @@ -80,7 +80,9 @@ module.exports = ({ env }) => ({ }); ``` -Strapi has a default `security` middleware that has a very strict `contentSecurityPolicy` that limits loading images and media to `"'self'"` only, see the example configuration on the [provider page](https://www.npmjs.com/package/@strapi/provider-upload-aws-s3) or the [middleware documentation](/developer-docs/latest/setup-deployment-guides/configurations/required/middlewares.html#security) for more information. +::: note +Strapi has a default [`security` middleware](/developer-docs/latest/setup-deployment-guides/configurations/required/middlewares.html#security) that has a very strict `contentSecurityPolicy` that limits loading images and media to `"'self'"` only, see the example configuration on the [provider page](https://www.npmjs.com/package/@strapi/provider-upload-aws-s3) or the [middleware documentation](/developer-docs/latest/setup-deployment-guides/configurations/required/middlewares.html#security) for more information. +::: :::