-
Notifications
You must be signed in to change notification settings - Fork 1.2k
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
* Update error-handling.md (#988) camel case → lower camel case * Bump to version 4.2.3 * Add warning callout for enum values (#984) * Add warning callout for enum values * Update wording to be more specific (dev feedback) Co-authored-by: Jean-Sébastien Herbaux <[email protected]> * Downgrade callout from danger to caution Co-authored-by: Jean-Sébastien Herbaux <[email protected]> * update link to public roadmap (#990) * update link to public roadmap From Product Board to Canny * Update wording "our" → "the" Co-authored-by: Pierre Wizla <[email protected]> * Email + Upload Plugins and Providers pages (#992) * fixed code snippets and added ts config * added new introduction * revised wording * add tabs card * Add code snippets for providers * Reorg doc structure * adds Using Providers page * fix tabs * rework text * start programmatic use section * Rework the email template section * various changes * Add code example for lifecycle hook in admin panel * add temp links to new providers page * delete configure the plugin * change wording about SendMail * finalize intro topics * remove unused content * Cleanup code examples and remove troubleshooting section * comment out last section for now * fix grammar * add html tags to table * small content edit * Adding Sentry plugin doc * fix tables * fix controller code example * updated some language * update lifecycle hook section * improve spelling an grammar * improve misc things * improve the introduction * update table and misc improvements * improved lifecycle hook text * Fix email plugin caps * fix * Add missing closing </ul> that prevented VuePress rendering * add bullet points * remove unnecessary fragment * rework intro * Update based on feedback * Update upload.md * improved various parts * add call out and fix titles * misc improvements * simplify wording * fix code block file paths and header levels * fixed various parts * update node engines * add spaces to empty object braces * trim content * shorten send func disc * feedback updates * add optional to table * Add send function properties table * updated send function table * add spacing * Update docs/developer-docs/latest/plugins/email.md Co-authored-by: Pierre Wizla <[email protected]> * updated minor wording + delint * add space * feedback revisions * modify `send` properties table * feedback * feedback * revisions * fix links in admin panel config file * delint * minor fixes * Update docs/developer-docs/latest/development/using-providers.md Co-authored-by: Shaun Brown <[email protected]> * Update docs/developer-docs/latest/plugins/email.md Co-authored-by: Pierre Wizla <[email protected]> * Update docs/developer-docs/latest/plugins/email.md * Feedback * title fix * add table * Add Sentry to PluginLinks component Co-authored-by: Shaun Brown <[email protected]> Co-authored-by: Pierre Wizla <[email protected]> Co-authored-by: Shaun Brown <[email protected]> Co-authored-by: Pierre Wizla <[email protected]> * Fix - → — * Update Email example to include missing path * Fix broken link * Fix another broken link * Update cross-link for compliance with style guide Co-authored-by: Adegbola Stephen <[email protected]> Co-authored-by: Jean-Sébastien Herbaux <[email protected]> Co-authored-by: Victor Coisne <[email protected]> Co-authored-by: Gabriel <[email protected]> Co-authored-by: Shaun Brown <[email protected]> Co-authored-by: Shaun Brown <[email protected]>
- Loading branch information
7 people
authored
Jul 13, 2022
1 parent
524b233
commit 10dac5b
Showing
15 changed files
with
517 additions
and
389 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,205 @@ | ||
| --- | ||
| title: 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/providers.html | ||
| --- | ||
|
|
||
| # 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](../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/). | ||
|
|
||
| ## Installing providers | ||
|
|
||
| New providers can be installed using `npm` or `yarn` using the following format `@strapi/provider-<plugin>-<provider> --save`. | ||
|
|
||
| For example: | ||
|
|
||
| <code-group> | ||
|
|
||
| <code-block title="NPM"> | ||
| ```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 | ||
| ``` | ||
| </code-block> | ||
|
|
||
| <code-block title="YARN"> | ||
| ```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 | ||
| ``` | ||
| </code-block> | ||
|
|
||
| </code-group> | ||
|
|
||
| ## 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. | ||
|
|
||
| :::: tabs card | ||
|
|
||
| ::: 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'), | ||
| }, | ||
| }, | ||
| }, | ||
| }, | ||
| // ... | ||
| }); | ||
| ``` | ||
|
|
||
| ::: note | ||
| Strapi has a default [`security` middleware](/developer-docs/latest/setup-deployment-guides/configurations/required/middlewares.md#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.md#security) for more information. | ||
| ::: | ||
|
|
||
| ::: tab Email | ||
|
|
||
| ```js | ||
| // path: ./config/plugins.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: '[email protected]', | ||
| defaultReplyTo: '[email protected]', | ||
| testAddress: '[email protected]', | ||
| }, | ||
| }, | ||
| }, | ||
| // ... | ||
| }); | ||
| ``` | ||
|
|
||
| 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 `[email protected]` 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: | ||
|
|
||
| :::: tabs card | ||
|
|
||
| ::: 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 | ||
|
|
||
| ::: | ||
|
|
||
| :::: | ||
|
|
||
| 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. | ||
|
|
||
| ### 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-<plugin>-<provider>`) | ||
| 3. Then update your `package.json` to link your `strapi-provider-<plugin>-<provider>` dependency to the [local path](https://docs.npmjs.com/files/package.json#local-paths) of your new provider. | ||
|
|
||
| ```json | ||
| { | ||
| ... | ||
| "dependencies": { | ||
| ... | ||
| "strapi-provider-<plugin>-<provider>": "file:providers/strapi-provider-<plugin>-<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. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Oops, something went wrong.