From a3db102a12be7e453b5bae32d97b003e308c95c7 Mon Sep 17 00:00:00 2001 From: derrickmehaffy Date: Wed, 1 Dec 2021 08:20:44 -0700 Subject: [PATCH 1/5] init email provider readme's from mono and update doc Signed-off-by: Derrick Mehaffy --- docs/developer-docs/latest/plugins/email.md | 63 ++++--- .../plugins/provider-email/amazon-ses.md | 59 +++++++ .../latest/plugins/provider-email/mailgun.md | 59 +++++++ .../plugins/provider-email/nodemailer.md | 157 ++++++++++++++++++ .../latest/plugins/provider-email/sendgrid.md | 58 +++++++ .../latest/plugins/provider-email/sendmail.md | 88 ++++++++++ 6 files changed, 457 insertions(+), 27 deletions(-) create mode 100644 docs/developer-docs/latest/plugins/provider-email/amazon-ses.md create mode 100644 docs/developer-docs/latest/plugins/provider-email/mailgun.md create mode 100644 docs/developer-docs/latest/plugins/provider-email/nodemailer.md create mode 100644 docs/developer-docs/latest/plugins/provider-email/sendgrid.md create mode 100644 docs/developer-docs/latest/plugins/provider-email/sendmail.md diff --git a/docs/developer-docs/latest/plugins/email.md b/docs/developer-docs/latest/plugins/email.md index 408107093d..2932ad0ce4 100644 --- a/docs/developer-docs/latest/plugins/email.md +++ b/docs/developer-docs/latest/plugins/email.md @@ -52,7 +52,7 @@ const emailTemplate = {

Your account is now linked with: <%= user.email %>.

`, }; -await strapi.plugins.email.services.email.sendTemplatedEmail( +await strapi.plugins['email'].services.email.sendTemplatedEmail( { to: user.email, // from: is not specified, so it's the defaultFrom that will be used instead @@ -68,45 +68,43 @@ await strapi.plugins.email.services.email.sendTemplatedEmail( By default Strapi provides a local email system ([sendmail](https://www.npmjs.com/package/sendmail)). If you want to use a third party to send emails, you need to install the correct provider module. Otherwise you can skip this part and continue to configure your provider. -You can check all the available providers developed by the community on npmjs.org - [Providers list](https://www.npmjs.com/search?q=strapi-provider-email-) +Below are the providers maintained by the Strapi team: -To install a new provider run: +- [Amazon SES](/developer-docs/latest/plugins/provider-email/amazon-ses.md) +- [Mailgun](/developer-docs/latest/plugins/provider-email/mailgun.md) +- [Nodemailer](/developer-docs/latest/plugins/provider-email/nodemailer.md) +- [SendGrid](/developer-docs/latest/plugins/provider-email/sendgrid.md) +- [Sendmail](/developer-docs/latest/plugins/provider-email/sendmail.md) +You can also find additional community maintained providers on [NPM](https://www.npmjs.com/). +To install a new provider run: ```sh -npm install strapi-provider-email-sendgrid --save +npm install @strapi/provider-email-sendgrid --save ``` ```sh -yarn add strapi-provider-email-sendgrid --save +yarn add @strapi/provider-email-sendgrid --save ``` -#### Using scoped packages as providers - -If your package name is [scoped](https://docs.npmjs.com/about-scopes) (for example `@username/strapi-provider-email-gmail-oauth2`) you need to take an extra step by aliasing it in `package.json`. Go to the `dependencies` section and change the provider line to look like this: - -`"strapi-provider-email-gmail-oauth2": "npm:@username/strapi-provider-email-gmail-oauth2@0.1.9"` - -The string after the last `@` represents your desired [semver](https://docs.npmjs.com/about-semantic-versioning) version range. - ### Configure your provider -After installing your provider you will need to add some settings in `config/plugins.js`. If this file doesn't exists, you'll need to create it. Check the README of each provider to know what configuration settings the provider needs. +After installing your provider you will need to add some settings in `./config/plugins.js`. If this file doesn't exists, you'll need to create it. Check the README of each provider to know what configuration settings the provider needs. ::: tip Make sure you have the correct spelling of the configuration filename, it is written in plural (with a trailing 's'): `plugins.js`. ::: -Here is an example of a configuration made for the provider [strapi-provider-email-sendgrid](https://www.npmjs.com/package/strapi-provider-email-sendgrid). +Here is an example of a configuration made for the provider [@strapi/provider-email-sendgrid](https://www.npmjs.com/package/strapi-provider-email-sendgrid). **Path —** `./config/plugins.js`. @@ -114,14 +112,16 @@ Here is an example of a configuration made for the provider [strapi-provider-ema module.exports = ({ env }) => ({ // ... email: { - provider: 'sendgrid', - providerOptions: { - apiKey: env('SENDGRID_API_KEY'), - }, - settings: { - defaultFrom: 'juliasedefdjian@strapi.io', - defaultReplyTo: 'juliasedefdjian@strapi.io', - testAddress: 'juliasedefdjian@strapi.io', + config: { + provider: 'sendgrid', + providerOptions: { + apiKey: env('SENDGRID_API_KEY'), + }, + settings: { + defaultFrom: 'juliasedefdjian@strapi.io', + defaultReplyTo: 'juliasedefdjian@strapi.io', + testAddress: 'juliasedefdjian@strapi.io', + }, }, }, // ... @@ -129,7 +129,7 @@ module.exports = ({ env }) => ({ ``` ::: tip -If you're using a different provider depending on your environment, you can specify the correct configuration in `config/env/${yourEnvironment}/plugins.js`. More info here: [Environments](http://localhost:8080/documentation/developer-docs/latest/setup-deployment-guides/configurations/optional/environment.md) +If you're using a different provider depending on your environment, you can specify the correct configuration in `./config/env/${yourEnvironment}/plugins.js`. More info here: [Environments](/developer-docs/latest/setup-deployment-guides/configurations/optional/environment.md) ::: ::: tip @@ -143,8 +143,6 @@ More info here: [Configure templates Locally](/user-docs/latest/settings/configu ## Create new provider -If you want to create your own, make sure the name starts with `strapi-provider-email-` (duplicating an existing one will be easier) and customize the `send` function. - Default template ```js @@ -157,6 +155,17 @@ module.exports = { }; ``` +It is important that your provider's `package.json` includes the following object: + +```json +{ + // ... + "strapi": { + "isProvider": true + } +} +``` + In the `send` function you will have access to: - `providerOptions` that contains configurations written in `plugins.js` @@ -170,7 +179,7 @@ To use it you will have to publish it on **npm**. If you want to create your own provider without publishing it on **npm** you can follow these steps: - Create a `providers` folder in your application. -- Create your provider as explained in the documentation eg. `./providers/strapi-provider-email-[...]/...` +- Create your provider eg. `./providers/strapi-provider-email-[...]/...` - Then update your `package.json` to link your `strapi-provider-email-[...]` dependency to the [local path](https://docs.npmjs.com/files/package.json#local-paths) of your new provider. ```json diff --git a/docs/developer-docs/latest/plugins/provider-email/amazon-ses.md b/docs/developer-docs/latest/plugins/provider-email/amazon-ses.md new file mode 100644 index 0000000000..d4d5af9060 --- /dev/null +++ b/docs/developer-docs/latest/plugins/provider-email/amazon-ses.md @@ -0,0 +1,59 @@ +# @strapi/provider-email-amazon-ses + +## Resources + +- [LICENSE](https://github.com/strapi/strapi/blob/master/packages/providers/email-amazon-ses/LICENSE) + +## Links + +- [Strapi website](https://strapi.io/) +- [Strapi documentation](https://docs.strapi.io) +- [Strapi community on Discord](https://discord.strapi.io) +- [Strapi news on Twitter](https://twitter.com/strapijs) + +## Installation + +```bash +# using yarn +yarn add @strapi/provider-email-amazon-ses + +# using npm +npm install @strapi/provider-email-amazon-ses --save +``` + +## Configuration + +| Variable | Type | Description | Required | Default | +| ----------------------- | ----------------------- | -------------------------------------------------------------------------------------------------------------------------- | -------- | --------- | +| provider | string | The name of the provider you use | yes | | +| providerOptions | object | Will be directly given to `createClient` function. Please refer to [node-ses](https://www.npmjs.com/package/node-ses) doc. | yes | | +| settings | object | Settings | no | {} | +| settings.defaultFrom | string | Default sender mail address | no | undefined | +| settings.defaultReplyTo | string \| array | Default address or addresses the receiver is asked to reply to | no | undefined | + +> :warning: The Shipper Email (or defaultfrom) may also need to be changed in the `Email Templates` tab on the admin panel for emails to send properly + +### Example + +**Path -** `./config/plugins.js` + +```js +module.exports = ({ env }) => ({ + // ... + email: { + config: { + provider: 'amazon-ses', + providerOptions: { + key: env('AWS_SES_KEY'), + secret: env('AWS_SES_SECRET'), + amazon: 'https://email.us-east-1.amazonaws.com', + }, + settings: { + defaultFrom: 'myemail@protonmail.com', + defaultReplyTo: 'myemail@protonmail.com', + }, + }, + }, + // ... +}); +``` diff --git a/docs/developer-docs/latest/plugins/provider-email/mailgun.md b/docs/developer-docs/latest/plugins/provider-email/mailgun.md new file mode 100644 index 0000000000..f85509732a --- /dev/null +++ b/docs/developer-docs/latest/plugins/provider-email/mailgun.md @@ -0,0 +1,59 @@ +# @strapi/provider-email-mailgun + +## Resources + +- [LICENSE](https://github.com/strapi/strapi/blob/master/packages/providers/email-mailgun/LICENSE) + +## Links + +- [Strapi website](https://strapi.io/) +- [Strapi documentation](https://docs.strapi.io) +- [Strapi community on Discord](https://discord.strapi.io) +- [Strapi news on Twitter](https://twitter.com/strapijs) + +## Installation + +```bash +# using yarn +yarn add @strapi/provider-email-mailgun + +# using npm +npm install @strapi/provider-email-mailgun --save +``` + +## Configuration + +| Variable | Type | Description | Required | Default | +| ----------------------- | ----------------------- | ---------------------------------------------------------------------------------------------------------------------------------- | -------- | --------- | +| provider | string | The name of the provider you use | yes | | +| providerOptions | object | Will be directly given to the `require('mailgun-js')`. Please refer to [mailgun-js](https://www.npmjs.com/package/mailgun-js) doc. | yes | | +| settings | object | Settings | no | {} | +| settings.defaultFrom | string | Default sender mail address | no | undefined | +| settings.defaultReplyTo | string \| array | Default address or addresses the receiver is asked to reply to | no | undefined | + +> :warning: The Shipper Email (or defaultfrom) may also need to be changed in the `Email Templates` tab on the admin panel for emails to send properly + +### Example + +**Path -** `config/plugins.js` + +```js +module.exports = ({ env }) => ({ + // ... + email: { + config: { + provider: 'mailgun', + providerOptions: { + apiKey: env('MAILGUN_API_KEY'), + domain: env('MAILGUN_DOMAIN'), //Required if you have an account with multiple domains + host: env('MAILGUN_HOST', 'api.mailgun.net'), //Optional. If domain region is Europe use 'api.eu.mailgun.net' + }, + settings: { + defaultFrom: 'myemail@protonmail.com', + defaultReplyTo: 'myemail@protonmail.com', + }, + }, + }, + // ... +}); +``` diff --git a/docs/developer-docs/latest/plugins/provider-email/nodemailer.md b/docs/developer-docs/latest/plugins/provider-email/nodemailer.md new file mode 100644 index 0000000000..1f9f267742 --- /dev/null +++ b/docs/developer-docs/latest/plugins/provider-email/nodemailer.md @@ -0,0 +1,157 @@ +# @strapi/provider-email-nodemailer + +## Resources + +- [LICENSE](https://github.com/strapi/strapi/blob/master/packages/providers/email-nodemailer/LICENSE) + +## Links + +- [Strapi website](https://strapi.io/) +- [Strapi documentation](https://docs.strapi.io) +- [Strapi community on Discord](https://discord.strapi.io) +- [Strapi news on Twitter](https://twitter.com/strapijs) + +## Installation + +```bash +# using yarn +yarn add @strapi/provider-email-nodemailer + +# using npm +npm install @strapi/provider-email-nodemailer --save +``` + +## Example + +**Path -** `config/plugins.js` + +```js +module.exports = ({ env }) => ({ + // ... + email: { + config: { + provider: 'nodemailer', + providerOptions: { + host: env('SMTP_HOST', 'smtp.example.com'), + port: env('SMTP_PORT', 587), + auth: { + user: env('SMTP_USERNAME'), + pass: env('SMTP_PASSWORD'), + }, + // ... any custom nodemailer options + }, + settings: { + defaultFrom: 'hello@example.com', + defaultReplyTo: 'hello@example.com', + }, + }, + }, + // ... +}); +``` + +Check out the available options for nodemailer: https://nodemailer.com/about/ + +### Development mode + +You can override the default configurations for specific environments. E.g. for +`NODE_ENV=development` in **config/env/development/plugins.js**: + +```js +module.exports = ({ env }) => ({ + email: { + provider: 'nodemailer', + providerOptions: { + host: 'localhost', + port: 1025, + ignoreTLS: true, + }, + }, +}); +``` + +The above setting is useful for local development with +[maildev](https://github.com/maildev/maildev). + +### Custom authentication mechanisms + +It is also possible to use custom authentication methods. +Here is an example for a NTLM authentication: + +```js +const nodemailerNTLMAuth = require('nodemailer-ntlm-auth'); + +module.exports = ({ env }) => ({ + email: { + provider: 'nodemailer', + providerOptions: { + host: env('SMTP_HOST', 'smtp.example.com'), + port: env('SMTP_PORT', 587), + auth: { + type: 'custom', + method: 'NTLM', + user: env('SMTP_USERNAME'), + pass: env('SMTP_PASSWORD'), + }, + customAuth: { + NTLM: nodemailerNTLMAuth, + }, + }, + settings: { + defaultFrom: 'hello@example.com', + defaultReplyTo: 'hello@example.com', + }, + }, +}); +``` + +## Usage + +> :warning: The Shipper Email (or defaultfrom) may also need to be changed in the `Email Templates` tab on the admin panel for emails to send properly + +To send an email from anywhere inside Strapi: + +```js +await strapi + .plugin('email') + .service('email') + .send({ + to: 'someone@example.com', + from: 'someone2@example.com', + subject: 'Hello world', + text: 'Hello world', + html: `

Hello world

`, + }); +``` + +The following fields are supported: + +| Field | Description | +| ----------- | ----------------------------------------------------------------- | +| from | Email address of the sender | +| to | Comma separated list or an array of recipients | +| replyTo | Email address to which replies are sent | +| cc | Comma separated list or an array of recipients | +| bcc | Comma separated list or an array of recipients | +| subject | Subject of the email | +| text | Plaintext version of the message | +| html | HTML version of the message | +| attachments | Array of objects See: https://nodemailer.com/message/attachments/ | + +## Troubleshooting + +Check your firewall to ensure that requests are allowed. If it doesn't work with + +```js +port: 465, +secure: true +``` + +try using + +```js +port: 587, +secure: false +``` + +to test if it works correctly. diff --git a/docs/developer-docs/latest/plugins/provider-email/sendgrid.md b/docs/developer-docs/latest/plugins/provider-email/sendgrid.md new file mode 100644 index 0000000000..10ff4db43c --- /dev/null +++ b/docs/developer-docs/latest/plugins/provider-email/sendgrid.md @@ -0,0 +1,58 @@ +# @strapi/provider-email-sendgrid + +## Resources + +- [LICENSE](https://github.com/strapi/strapi/blob/master/packages/providers/email-sendgrid/LICENSE) + +## Links + +- [Strapi website](https://strapi.io/) +- [Strapi documentation](https://docs.strapi.io) +- [Strapi community on Discord](https://discord.strapi.io) +- [Strapi news on Twitter](https://twitter.com/strapijs) + +## Installation + +```bash +# using yarn +yarn add @strapi/provider-email-sendgrid + +# using npm +npm install @strapi/provider-email-sendgrid --save +``` + +## Configuration + +| Variable | Type | Description | Required | Default | +| ----------------------- | ----------------------- | ----------------------------------------------------------------------------------------------------------------------- | -------- | --------- | +| provider | string | The name of the provider you use | yes | | +| providerOptions | object | Provider options | yes | | +| providerOptions.apiKey | object | Api key given to the function setApiKey. Please refer to [@sendgrid/mail](https://www.npmjs.com/package/@sendgrid/mail) | yes | | +| settings | object | Settings | no | {} | +| settings.defaultFrom | string | Default sender mail address | no | undefined | +| settings.defaultReplyTo | string \| array | Default address or addresses the receiver is asked to reply to | no | undefined | + +> :warning: The Shipper Email (or defaultfrom) may also need to be changed in the `Email Templates` tab on the admin panel for emails to send properly + +### Example + +**Path -** `config/plugins.js` + +```js +module.exports = ({ env }) => ({ + // ... + email: { + config: { + provider: 'sendgrid', + providerOptions: { + apiKey: env('SENDGRID_API_KEY'), + }, + settings: { + defaultFrom: 'myemail@protonmail.com', + defaultReplyTo: 'myemail@protonmail.com', + }, + }, + }, + // ... +}); +``` diff --git a/docs/developer-docs/latest/plugins/provider-email/sendmail.md b/docs/developer-docs/latest/plugins/provider-email/sendmail.md new file mode 100644 index 0000000000..06e5e501be --- /dev/null +++ b/docs/developer-docs/latest/plugins/provider-email/sendmail.md @@ -0,0 +1,88 @@ +# @strapi/provider-email-sendmail + +## Resources + +- [LICENSE](https://github.com/strapi/strapi/blob/master/packages/providers/email-sendmail/LICENSE) + +## Links + +- [Strapi website](https://strapi.io/) +- [Strapi documentation](https://docs.strapi.io) +- [Strapi community on Discord](https://discord.strapi.io) +- [Strapi news on Twitter](https://twitter.com/strapijs) + +## Installation + +```bash +# using yarn +yarn add @strapi/provider-email-sendmail + +# using npm +npm install @strapi/provider-email-sendmail --save +``` + +## Configuration + +| Variable | Type | Description | Required | Default | +| ----------------------- | ----------------- | ------------------------------------------------------------------------------------------------------------------------ | -------- | --------- | +| provider | string | The name of the provider you use | yes | | +| providerOptions | object | Will be directly given to `require('sendmail')`. Please refer to [sendmail](https://www.npmjs.com/package/sendmail) doc. | no | {} | +| settings | object | Settings | no | {} | +| settings.defaultFrom | string | Default sender mail address | no | undefined | +| settings.defaultReplyTo | string \| array | Default address or addresses the receiver is asked to reply to | no | undefined | +| providerOptions.dkim | object \| boolean | DKIM parameters having two properties: { privateKey, keySelector } | no | false | + +> :warning: The Shipper Email (or defaultfrom) may also need to be changed in the `Email Templates` tab on the admin panel for emails to send properly + +### Example + +**Path -** `config/plugins.js` + +```js +module.exports = ({ env }) => ({ + // ... + email: { + config: { + provider: 'sendmail', + settings: { + defaultFrom: 'myemail@protonmail.com', + defaultReplyTo: 'myemail@protonmail.com', + }, + }, + }, + // ... +}); +``` + +### Example with DKIM + +Using **DKIM** (DomainKeys Identified Mail) can prevent emails from being considered as spam. More details about this subject can be found in the discussion on the Strapi forum: [Unsolved problem: emails goes to spam!](https://forum.strapi.io/t/unsolved-problem-emails-goes-to-spam/512?u=soringfs) + +#### Generate the keys using OpenSSL + +```perl +openssl genrsa -out dkim-private.pem 1024 +openssl rsa -in dkim-private.pem -pubout -out dkim-public.pem +``` + +**Path -** `config/plugins.js` + +```js +module.exports = ({ env }) => ({ + // ... + email: { + provider: 'sendmail', + providerOptions: { + dkim: { + privateKey: 'replace-with-dkim-private-key', + keySelector: 'abcd', // the same as the one set in DNS txt record, use online dns lookup tools to be sure that is retreivable + }, + }, + settings: { + defaultFrom: 'myemail@protonmail.com', + defaultReplyTo: 'myemail@protonmail.com', + }, + }, + // ... +}); +``` From 8c955733eeb06a7f8e6301503c1b640939377108 Mon Sep 17 00:00:00 2001 From: derrickmehaffy Date: Wed, 1 Dec 2021 09:10:40 -0700 Subject: [PATCH 2/5] Remove copy of READMEs and change links to npm Signed-off-by: Derrick Mehaffy --- docs/developer-docs/latest/plugins/email.md | 10 +- .../plugins/provider-email/amazon-ses.md | 59 ------- .../latest/plugins/provider-email/mailgun.md | 59 ------- .../plugins/provider-email/nodemailer.md | 157 ------------------ .../latest/plugins/provider-email/sendgrid.md | 58 ------- .../latest/plugins/provider-email/sendmail.md | 88 ---------- 6 files changed, 5 insertions(+), 426 deletions(-) delete mode 100644 docs/developer-docs/latest/plugins/provider-email/amazon-ses.md delete mode 100644 docs/developer-docs/latest/plugins/provider-email/mailgun.md delete mode 100644 docs/developer-docs/latest/plugins/provider-email/nodemailer.md delete mode 100644 docs/developer-docs/latest/plugins/provider-email/sendgrid.md delete mode 100644 docs/developer-docs/latest/plugins/provider-email/sendmail.md diff --git a/docs/developer-docs/latest/plugins/email.md b/docs/developer-docs/latest/plugins/email.md index 2932ad0ce4..41b7702cef 100644 --- a/docs/developer-docs/latest/plugins/email.md +++ b/docs/developer-docs/latest/plugins/email.md @@ -70,11 +70,11 @@ By default Strapi provides a local email system ([sendmail](https://www.npmjs.co Below are the providers maintained by the Strapi team: -- [Amazon SES](/developer-docs/latest/plugins/provider-email/amazon-ses.md) -- [Mailgun](/developer-docs/latest/plugins/provider-email/mailgun.md) -- [Nodemailer](/developer-docs/latest/plugins/provider-email/nodemailer.md) -- [SendGrid](/developer-docs/latest/plugins/provider-email/sendgrid.md) -- [Sendmail](/developer-docs/latest/plugins/provider-email/sendmail.md) +- [Amazon SES](https://www.npmjs.com/package/@strapi/provider-email-amazon-ses) +- [Mailgun](https://www.npmjs.com/package/@strapi/provider-email-mailgun) +- [Nodemailer](https://www.npmjs.com/package/@strapi/provider-email-nodemailer) +- [SendGrid](https://www.npmjs.com/package/@strapi/provider-email-sendgrid) +- [Sendmail](https://www.npmjs.com/package/@strapi/provider-email-sendmail) You can also find additional community maintained providers on [NPM](https://www.npmjs.com/). diff --git a/docs/developer-docs/latest/plugins/provider-email/amazon-ses.md b/docs/developer-docs/latest/plugins/provider-email/amazon-ses.md deleted file mode 100644 index d4d5af9060..0000000000 --- a/docs/developer-docs/latest/plugins/provider-email/amazon-ses.md +++ /dev/null @@ -1,59 +0,0 @@ -# @strapi/provider-email-amazon-ses - -## Resources - -- [LICENSE](https://github.com/strapi/strapi/blob/master/packages/providers/email-amazon-ses/LICENSE) - -## Links - -- [Strapi website](https://strapi.io/) -- [Strapi documentation](https://docs.strapi.io) -- [Strapi community on Discord](https://discord.strapi.io) -- [Strapi news on Twitter](https://twitter.com/strapijs) - -## Installation - -```bash -# using yarn -yarn add @strapi/provider-email-amazon-ses - -# using npm -npm install @strapi/provider-email-amazon-ses --save -``` - -## Configuration - -| Variable | Type | Description | Required | Default | -| ----------------------- | ----------------------- | -------------------------------------------------------------------------------------------------------------------------- | -------- | --------- | -| provider | string | The name of the provider you use | yes | | -| providerOptions | object | Will be directly given to `createClient` function. Please refer to [node-ses](https://www.npmjs.com/package/node-ses) doc. | yes | | -| settings | object | Settings | no | {} | -| settings.defaultFrom | string | Default sender mail address | no | undefined | -| settings.defaultReplyTo | string \| array | Default address or addresses the receiver is asked to reply to | no | undefined | - -> :warning: The Shipper Email (or defaultfrom) may also need to be changed in the `Email Templates` tab on the admin panel for emails to send properly - -### Example - -**Path -** `./config/plugins.js` - -```js -module.exports = ({ env }) => ({ - // ... - email: { - config: { - provider: 'amazon-ses', - providerOptions: { - key: env('AWS_SES_KEY'), - secret: env('AWS_SES_SECRET'), - amazon: 'https://email.us-east-1.amazonaws.com', - }, - settings: { - defaultFrom: 'myemail@protonmail.com', - defaultReplyTo: 'myemail@protonmail.com', - }, - }, - }, - // ... -}); -``` diff --git a/docs/developer-docs/latest/plugins/provider-email/mailgun.md b/docs/developer-docs/latest/plugins/provider-email/mailgun.md deleted file mode 100644 index f85509732a..0000000000 --- a/docs/developer-docs/latest/plugins/provider-email/mailgun.md +++ /dev/null @@ -1,59 +0,0 @@ -# @strapi/provider-email-mailgun - -## Resources - -- [LICENSE](https://github.com/strapi/strapi/blob/master/packages/providers/email-mailgun/LICENSE) - -## Links - -- [Strapi website](https://strapi.io/) -- [Strapi documentation](https://docs.strapi.io) -- [Strapi community on Discord](https://discord.strapi.io) -- [Strapi news on Twitter](https://twitter.com/strapijs) - -## Installation - -```bash -# using yarn -yarn add @strapi/provider-email-mailgun - -# using npm -npm install @strapi/provider-email-mailgun --save -``` - -## Configuration - -| Variable | Type | Description | Required | Default | -| ----------------------- | ----------------------- | ---------------------------------------------------------------------------------------------------------------------------------- | -------- | --------- | -| provider | string | The name of the provider you use | yes | | -| providerOptions | object | Will be directly given to the `require('mailgun-js')`. Please refer to [mailgun-js](https://www.npmjs.com/package/mailgun-js) doc. | yes | | -| settings | object | Settings | no | {} | -| settings.defaultFrom | string | Default sender mail address | no | undefined | -| settings.defaultReplyTo | string \| array | Default address or addresses the receiver is asked to reply to | no | undefined | - -> :warning: The Shipper Email (or defaultfrom) may also need to be changed in the `Email Templates` tab on the admin panel for emails to send properly - -### Example - -**Path -** `config/plugins.js` - -```js -module.exports = ({ env }) => ({ - // ... - email: { - config: { - provider: 'mailgun', - providerOptions: { - apiKey: env('MAILGUN_API_KEY'), - domain: env('MAILGUN_DOMAIN'), //Required if you have an account with multiple domains - host: env('MAILGUN_HOST', 'api.mailgun.net'), //Optional. If domain region is Europe use 'api.eu.mailgun.net' - }, - settings: { - defaultFrom: 'myemail@protonmail.com', - defaultReplyTo: 'myemail@protonmail.com', - }, - }, - }, - // ... -}); -``` diff --git a/docs/developer-docs/latest/plugins/provider-email/nodemailer.md b/docs/developer-docs/latest/plugins/provider-email/nodemailer.md deleted file mode 100644 index 1f9f267742..0000000000 --- a/docs/developer-docs/latest/plugins/provider-email/nodemailer.md +++ /dev/null @@ -1,157 +0,0 @@ -# @strapi/provider-email-nodemailer - -## Resources - -- [LICENSE](https://github.com/strapi/strapi/blob/master/packages/providers/email-nodemailer/LICENSE) - -## Links - -- [Strapi website](https://strapi.io/) -- [Strapi documentation](https://docs.strapi.io) -- [Strapi community on Discord](https://discord.strapi.io) -- [Strapi news on Twitter](https://twitter.com/strapijs) - -## Installation - -```bash -# using yarn -yarn add @strapi/provider-email-nodemailer - -# using npm -npm install @strapi/provider-email-nodemailer --save -``` - -## Example - -**Path -** `config/plugins.js` - -```js -module.exports = ({ env }) => ({ - // ... - email: { - config: { - provider: 'nodemailer', - providerOptions: { - host: env('SMTP_HOST', 'smtp.example.com'), - port: env('SMTP_PORT', 587), - auth: { - user: env('SMTP_USERNAME'), - pass: env('SMTP_PASSWORD'), - }, - // ... any custom nodemailer options - }, - settings: { - defaultFrom: 'hello@example.com', - defaultReplyTo: 'hello@example.com', - }, - }, - }, - // ... -}); -``` - -Check out the available options for nodemailer: https://nodemailer.com/about/ - -### Development mode - -You can override the default configurations for specific environments. E.g. for -`NODE_ENV=development` in **config/env/development/plugins.js**: - -```js -module.exports = ({ env }) => ({ - email: { - provider: 'nodemailer', - providerOptions: { - host: 'localhost', - port: 1025, - ignoreTLS: true, - }, - }, -}); -``` - -The above setting is useful for local development with -[maildev](https://github.com/maildev/maildev). - -### Custom authentication mechanisms - -It is also possible to use custom authentication methods. -Here is an example for a NTLM authentication: - -```js -const nodemailerNTLMAuth = require('nodemailer-ntlm-auth'); - -module.exports = ({ env }) => ({ - email: { - provider: 'nodemailer', - providerOptions: { - host: env('SMTP_HOST', 'smtp.example.com'), - port: env('SMTP_PORT', 587), - auth: { - type: 'custom', - method: 'NTLM', - user: env('SMTP_USERNAME'), - pass: env('SMTP_PASSWORD'), - }, - customAuth: { - NTLM: nodemailerNTLMAuth, - }, - }, - settings: { - defaultFrom: 'hello@example.com', - defaultReplyTo: 'hello@example.com', - }, - }, -}); -``` - -## Usage - -> :warning: The Shipper Email (or defaultfrom) may also need to be changed in the `Email Templates` tab on the admin panel for emails to send properly - -To send an email from anywhere inside Strapi: - -```js -await strapi - .plugin('email') - .service('email') - .send({ - to: 'someone@example.com', - from: 'someone2@example.com', - subject: 'Hello world', - text: 'Hello world', - html: `

Hello world

`, - }); -``` - -The following fields are supported: - -| Field | Description | -| ----------- | ----------------------------------------------------------------- | -| from | Email address of the sender | -| to | Comma separated list or an array of recipients | -| replyTo | Email address to which replies are sent | -| cc | Comma separated list or an array of recipients | -| bcc | Comma separated list or an array of recipients | -| subject | Subject of the email | -| text | Plaintext version of the message | -| html | HTML version of the message | -| attachments | Array of objects See: https://nodemailer.com/message/attachments/ | - -## Troubleshooting - -Check your firewall to ensure that requests are allowed. If it doesn't work with - -```js -port: 465, -secure: true -``` - -try using - -```js -port: 587, -secure: false -``` - -to test if it works correctly. diff --git a/docs/developer-docs/latest/plugins/provider-email/sendgrid.md b/docs/developer-docs/latest/plugins/provider-email/sendgrid.md deleted file mode 100644 index 10ff4db43c..0000000000 --- a/docs/developer-docs/latest/plugins/provider-email/sendgrid.md +++ /dev/null @@ -1,58 +0,0 @@ -# @strapi/provider-email-sendgrid - -## Resources - -- [LICENSE](https://github.com/strapi/strapi/blob/master/packages/providers/email-sendgrid/LICENSE) - -## Links - -- [Strapi website](https://strapi.io/) -- [Strapi documentation](https://docs.strapi.io) -- [Strapi community on Discord](https://discord.strapi.io) -- [Strapi news on Twitter](https://twitter.com/strapijs) - -## Installation - -```bash -# using yarn -yarn add @strapi/provider-email-sendgrid - -# using npm -npm install @strapi/provider-email-sendgrid --save -``` - -## Configuration - -| Variable | Type | Description | Required | Default | -| ----------------------- | ----------------------- | ----------------------------------------------------------------------------------------------------------------------- | -------- | --------- | -| provider | string | The name of the provider you use | yes | | -| providerOptions | object | Provider options | yes | | -| providerOptions.apiKey | object | Api key given to the function setApiKey. Please refer to [@sendgrid/mail](https://www.npmjs.com/package/@sendgrid/mail) | yes | | -| settings | object | Settings | no | {} | -| settings.defaultFrom | string | Default sender mail address | no | undefined | -| settings.defaultReplyTo | string \| array | Default address or addresses the receiver is asked to reply to | no | undefined | - -> :warning: The Shipper Email (or defaultfrom) may also need to be changed in the `Email Templates` tab on the admin panel for emails to send properly - -### Example - -**Path -** `config/plugins.js` - -```js -module.exports = ({ env }) => ({ - // ... - email: { - config: { - provider: 'sendgrid', - providerOptions: { - apiKey: env('SENDGRID_API_KEY'), - }, - settings: { - defaultFrom: 'myemail@protonmail.com', - defaultReplyTo: 'myemail@protonmail.com', - }, - }, - }, - // ... -}); -``` diff --git a/docs/developer-docs/latest/plugins/provider-email/sendmail.md b/docs/developer-docs/latest/plugins/provider-email/sendmail.md deleted file mode 100644 index 06e5e501be..0000000000 --- a/docs/developer-docs/latest/plugins/provider-email/sendmail.md +++ /dev/null @@ -1,88 +0,0 @@ -# @strapi/provider-email-sendmail - -## Resources - -- [LICENSE](https://github.com/strapi/strapi/blob/master/packages/providers/email-sendmail/LICENSE) - -## Links - -- [Strapi website](https://strapi.io/) -- [Strapi documentation](https://docs.strapi.io) -- [Strapi community on Discord](https://discord.strapi.io) -- [Strapi news on Twitter](https://twitter.com/strapijs) - -## Installation - -```bash -# using yarn -yarn add @strapi/provider-email-sendmail - -# using npm -npm install @strapi/provider-email-sendmail --save -``` - -## Configuration - -| Variable | Type | Description | Required | Default | -| ----------------------- | ----------------- | ------------------------------------------------------------------------------------------------------------------------ | -------- | --------- | -| provider | string | The name of the provider you use | yes | | -| providerOptions | object | Will be directly given to `require('sendmail')`. Please refer to [sendmail](https://www.npmjs.com/package/sendmail) doc. | no | {} | -| settings | object | Settings | no | {} | -| settings.defaultFrom | string | Default sender mail address | no | undefined | -| settings.defaultReplyTo | string \| array | Default address or addresses the receiver is asked to reply to | no | undefined | -| providerOptions.dkim | object \| boolean | DKIM parameters having two properties: { privateKey, keySelector } | no | false | - -> :warning: The Shipper Email (or defaultfrom) may also need to be changed in the `Email Templates` tab on the admin panel for emails to send properly - -### Example - -**Path -** `config/plugins.js` - -```js -module.exports = ({ env }) => ({ - // ... - email: { - config: { - provider: 'sendmail', - settings: { - defaultFrom: 'myemail@protonmail.com', - defaultReplyTo: 'myemail@protonmail.com', - }, - }, - }, - // ... -}); -``` - -### Example with DKIM - -Using **DKIM** (DomainKeys Identified Mail) can prevent emails from being considered as spam. More details about this subject can be found in the discussion on the Strapi forum: [Unsolved problem: emails goes to spam!](https://forum.strapi.io/t/unsolved-problem-emails-goes-to-spam/512?u=soringfs) - -#### Generate the keys using OpenSSL - -```perl -openssl genrsa -out dkim-private.pem 1024 -openssl rsa -in dkim-private.pem -pubout -out dkim-public.pem -``` - -**Path -** `config/plugins.js` - -```js -module.exports = ({ env }) => ({ - // ... - email: { - provider: 'sendmail', - providerOptions: { - dkim: { - privateKey: 'replace-with-dkim-private-key', - keySelector: 'abcd', // the same as the one set in DNS txt record, use online dns lookup tools to be sure that is retreivable - }, - }, - settings: { - defaultFrom: 'myemail@protonmail.com', - defaultReplyTo: 'myemail@protonmail.com', - }, - }, - // ... -}); -``` From 19e23e7725bbf715121dd9688c2b0c40a88fd212 Mon Sep 17 00:00:00 2001 From: derrickmehaffy Date: Wed, 1 Dec 2021 09:29:36 -0700 Subject: [PATCH 3/5] Update Upload Provider doc --- docs/developer-docs/latest/plugins/upload.md | 149 ++++++++++--------- 1 file changed, 80 insertions(+), 69 deletions(-) diff --git a/docs/developer-docs/latest/plugins/upload.md b/docs/developer-docs/latest/plugins/upload.md index 06f39c081a..15a0ae26fc 100644 --- a/docs/developer-docs/latest/plugins/upload.md +++ b/docs/developer-docs/latest/plugins/upload.md @@ -14,25 +14,27 @@ Currently the Strapi middleware in charge of parsing requests needs to be config The library we use is [`koa-body`](https://github.com/dlau/koa-body), and it uses the [`node-formidable`](https://github.com/felixge/node-formidable) library to process files. -You can pass configuration to the middleware directly by setting it in the `parser` middleware configuration in `config/middleware.js`: +You can pass configuration to the middleware directly by setting it in the `body` middleware configuration in `./config/middleware.js`: ```js module.exports = { //... - settings: { - parser: { - enabled: true, - multipart: true, + { + name: "strapi::body", + config: { + formLimit: "256mb", // modify form body + jsonLimit: "256mb", // modify JSON body + textLimit: "256mb", // modify text body formidable: { - maxFileSize: 200 * 1024 * 1024 // Defaults to 200mb - } - } + maxFileSize: 200 * 1024 * 1024, // multipart data, modify here limit of uploaded file size + }, + }, }, //... }; ``` -#### Responsive Images +### Responsive Images When the `Enable responsive friendly upload` setting is enabled in the settings panel the plugin will generate the following responsive image sizes: | Name | Largest Dimension | @@ -41,20 +43,24 @@ When the `Enable responsive friendly upload` setting is enabled in the settings | medium | 750px | | small | 500px | -These sizes can be overridden in `config/plugins.js`: -```javascript -module.exports = { +These sizes can be overridden in `./config/plugins.js`: + +```js +module.exports = ({ env }) => ({ upload: { - breakpoints: { - xlarge: 1920, - large: 1000, - medium: 750, - small: 500, - xsmall: 64 - } - } -} + config: { + breakpoints: { + xlarge: 1920, + large: 1000, + medium: 750, + small: 500, + xsmall: 64 + }, + }, + }, +}); ``` + :::caution Breakpoint changes will only apply to new images, existing images will not be resized or have new sizes generated. ::: @@ -86,12 +92,12 @@ module.exports = {
-| Method | Path | Description | -| :----- | :---------------- | :------------------ | -| GET | /upload/files | Get a list of files | -| GET | /upload/files/:id | Get a specific file | -| POST | /upload | Upload files | -| DELETE | /upload/files/:id | Delete a file | +| Method | Path | Description | +| :----- | :-------------------- | :------------------ | +| GET | /api/upload/files | Get a list of files | +| GET | /api/upload/files/:id | Get a specific file | +| POST | /api/upload | Upload files | +| DELETE | /api/upload/files/:id | Delete a file |
@@ -154,9 +160,8 @@ The `Restaurant` model attributes: "type": "string" }, "cover": { - "model": "file", - "via": "related", - "plugin": "upload" + "type": "media", + "multiple": false, } } ``` @@ -206,9 +211,8 @@ The `Restaurant` model attributes: "type": "string" }, "cover": { - "model": "file", - "via": "related", - "plugin": "upload" + "type": "media", + "multiple": false, } } ``` @@ -278,11 +282,10 @@ Adding a file attribute to a model (or the model of another plugin) is like addi In the first example below, you will be able to upload and attach one file to the avatar attribute. -**Path —** `User.settings.json`. +**Path —** `schema.json`. ```json { - "connection": "default", "attributes": { "pseudo": { "type": "string", @@ -294,9 +297,8 @@ In the first example below, you will be able to upload and attach one file to th "unique": true }, "avatar": { - "model": "file", - "via": "related", - "plugin": "upload" + "type": "media", + "multiple": false, } } } @@ -304,20 +306,18 @@ In the first example below, you will be able to upload and attach one file to th In our second example, you can upload and attach multiple pictures to the restaurant. -**Path —** `Restaurant.settings.json`. +**Path —** `schema.json`. ```json { - "connection": "default", "attributes": { "name": { "type": "string", "required": true }, "convers": { - "collection": "file", - "via": "related", - "plugin": "upload" + "type": "media", + "multiple": true, } } } @@ -327,7 +327,14 @@ In our second example, you can upload and attach multiple pictures to the restau By default Strapi provides a provider that uploads files to a local directory. You might want to upload your files to another provider like AWS S3. -You can check all the available providers developed by the community on npmjs.org - [Providers list](https://www.npmjs.com/search?q=strapi-provider-upload-&ranking=popularity) +Below are the providers maintained by the Strapi team: + +- [Amazon S3](https://www.npmjs.com/package/@strapi/provider-upload-aws-s3) +- [Cloudinary](https://www.npmjs.com/package/@strapi/provider-upload-cloudinary) +- [Local](https://www.npmjs.com/package/@strapi/provider-upload-local) +- [Rackspace](https://www.npmjs.com/package/@strapi/provider-upload-rackspace) + +You can also find additional community maintained providers on [NPM](https://www.npmjs.com/). To install a new provider run: @@ -335,13 +342,13 @@ To install a new provider run: ```sh -npm install strapi-provider-upload-aws-s3 --save +npm install @strapi/provider-upload-aws-s3 --save ``` ```sh -yarn add strapi-provider-upload-aws-s3 +yarn add @strapi/provider-upload-aws-s3 ``` @@ -356,45 +363,51 @@ You can provide them by create or edit the file at `./config/plugins.js`. The ex ```js module.exports = ({ env })=>({ upload: { - providerOptions: { - localServer: { - maxage: 300000 - } - } - } + config: { + providerOptions: { + localServer: { + maxage: 300000 + }, + }, + }, + }, }); ``` -### Using scoped packages as providers - -If your package name is [scoped](https://docs.npmjs.com/about-scopes) (for example `@username/strapi-provider-upload-aws2`) you need to take an extra step by aliasing it in `package.json`. Go to the `dependencies` section and change the provider line to look like this: - -`"strapi-provider-upload-aws2": "npm:@username/strapi-provider-upload-aws2@0.1.9"` - -The string after the last `@` represents your desired [semver](https://docs.npmjs.com/about-semantic-versioning) version range. - ### Enabling the provider To enable the provider, create or edit the file at `./config/plugins.js` +:::tip +When using community providers, you need to pass the full package name to the `provider` key, only Strapi maintained providers can use the short-code eg: `provider: 'strapi-provider-upload-google-cloud-storage'` +::: + ```js module.exports = ({ env }) => ({ + // ... upload: { - provider: 'aws-s3', - providerOptions: { - accessKeyId: env('AWS_ACCESS_KEY_ID'), - secretAccessKey: env('AWS_ACCESS_SECRET'), - region: 'aws-region', - params: { - Bucket: 'my-bucket', + config: { + provider: 'aws-s3', + providerOptions: { + accessKeyId: env('AWS_ACCESS_KEY_ID'), + secretAccessKey: env('AWS_ACCESS_SECRET'), + region: env('AWS_REGION'), + params: { + Bucket: env('AWS_BUCKET'), + }, }, }, }, + // ... }); ``` Make sure to read the provider's `README` to know what are the possible parameters. +:::caution +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 or take a look at our [middleare documentation](/developer-docs/latest/setup-deployment-guides/configurations/required/middlewares.md#loading-order) for more information. +::: + ### Configuration per environment When configuring your upload provider you might want to change the configuration based on the `NODE_ENV` environment variable or use environment specific credentials. @@ -405,8 +418,6 @@ You can set a specific configuration in the `./config/env/{env}/plugins.js` conf You can create a Node.js module to implement a custom provider. Read the official documentation [here](https://docs.npmjs.com/creating-node-js-modules). -To work with strapi, your provider name must match the pattern `strapi-provider-upload-{provider-name}`. - Your provider need to export the following interface: ```js From 2bd76272909b2a8cbc34af58ec994e3b6d157323 Mon Sep 17 00:00:00 2001 From: DMehaffy Date: Fri, 3 Dec 2021 07:50:21 -0800 Subject: [PATCH 4/5] Update docs/developer-docs/latest/plugins/email.md Co-authored-by: Pierre Wizla --- docs/developer-docs/latest/plugins/email.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/developer-docs/latest/plugins/email.md b/docs/developer-docs/latest/plugins/email.md index 41b7702cef..70f3badf17 100644 --- a/docs/developer-docs/latest/plugins/email.md +++ b/docs/developer-docs/latest/plugins/email.md @@ -179,7 +179,7 @@ To use it you will have to publish it on **npm**. If you want to create your own provider without publishing it on **npm** you can follow these steps: - Create a `providers` folder in your application. -- Create your provider eg. `./providers/strapi-provider-email-[...]/...` +- Create your provider (e.g. `./providers/strapi-provider-email-[...]/...`) - Then update your `package.json` to link your `strapi-provider-email-[...]` dependency to the [local path](https://docs.npmjs.com/files/package.json#local-paths) of your new provider. ```json From 40b3cfb8f2631540201f41096db27d97a93a79af Mon Sep 17 00:00:00 2001 From: derrickmehaffy Date: Fri, 3 Dec 2021 08:59:59 -0700 Subject: [PATCH 5/5] pr feedback --- docs/developer-docs/latest/plugins/upload.md | 118 ++++++++++++------- 1 file changed, 75 insertions(+), 43 deletions(-) diff --git a/docs/developer-docs/latest/plugins/upload.md b/docs/developer-docs/latest/plugins/upload.md index 15a0ae26fc..d5d50c84e8 100644 --- a/docs/developer-docs/latest/plugins/upload.md +++ b/docs/developer-docs/latest/plugins/upload.md @@ -17,6 +17,8 @@ The library we use is [`koa-body`](https://github.com/dlau/koa-body), and it use You can pass configuration to the middleware directly by setting it in the `body` middleware configuration in `./config/middleware.js`: ```js +// path: ./config/middlewares.js + module.exports = { //... { @@ -46,6 +48,8 @@ When the `Enable responsive friendly upload` setting is enabled in the settings These sizes can be overridden in `./config/plugins.js`: ```js +// path: ./config/plugins.js + module.exports = ({ env }) => ({ upload: { config: { @@ -155,14 +159,20 @@ To upload files that will be linked to a specific entry. The `Restaurant` model attributes: ```json -"attributes": { - "name": { - "type": "string" - }, - "cover": { - "type": "media", - "multiple": false, +// path: ./src/api/restaurant/content-types/restaurant/schema.json + +{ + //.. + "attributes": { + "name": { + "type": "string" + }, + "cover": { + "type": "media", + "multiple": false, + } } +//.. } ``` @@ -206,15 +216,22 @@ You can also add files during your entry creation. The `Restaurant` model attributes: ```json -"attributes": { - "name": { - "type": "string" - }, - "cover": { - "type": "media", - "multiple": false, +// path: ./src/api/restaurant/content-types/restaurant/schema.json + +{ + //.. + "attributes": { + "name": { + "type": "string" + }, + "cover": { + "type": "media", + "multiple": false, + } } + //.. } + ``` Code @@ -282,44 +299,53 @@ Adding a file attribute to a model (or the model of another plugin) is like addi In the first example below, you will be able to upload and attach one file to the avatar attribute. -**Path —** `schema.json`. - ```json +// path: ./src/api/restaurant/content-types/restaurant/schema.json + { - "attributes": { - "pseudo": { - "type": "string", - "required": true - }, - "email": { - "type": "email", - "required": true, - "unique": true - }, - "avatar": { - "type": "media", - "multiple": false, + //.. + { + "attributes": { + "pseudo": { + "type": "string", + "required": true + }, + "email": { + "type": "email", + "required": true, + "unique": true + }, + "avatar": { + "type": "media", + "multiple": false, + } } } + //.. } + ``` In our second example, you can upload and attach multiple pictures to the restaurant. -**Path —** `schema.json`. - ```json +// path: ./src/api/restaurant/content-types/restaurant/schema.json + { - "attributes": { - "name": { - "type": "string", - "required": true - }, - "convers": { - "type": "media", - "multiple": true, + //.. + { + "attributes": { + "name": { + "type": "string", + "required": true + }, + "covers": { + "type": "media", + "multiple": true, + } } } + //.. } ``` @@ -361,6 +387,8 @@ By default Strapi accepts `localServer` configurations for locally uploaded file You can provide them by create or edit the file at `./config/plugins.js`. The example below set `max-age` header. ```js +//path: ./config/plugins.js + module.exports = ({ env })=>({ upload: { config: { @@ -383,6 +411,8 @@ When using community providers, you need to pass the full package name to the `p ::: ```js +//path: ./config/plugins.js + module.exports = ({ env }) => ({ // ... upload: { @@ -443,11 +473,13 @@ You can then publish it to make it available to the community. If you want to create your own provider without publishing it on **npm** you can follow these steps: -- Create a `./providers/strapi-provider-upload-{provider-name}` folder in your root application folder. -- Create your provider as explained in the [documentation](#create-providers) above. -- Then update your `package.json` to link your `strapi-provider-upload-{provider-name}` dependency to point to the [local path](https://docs.npmjs.com/files/package.json#local-paths) of your provider. +1. Create a `./providers/strapi-provider-upload-{provider-name}` folder in your root application folder. +2. Create your provider as explained in the [documentation](#create-providers) above. +3. Then update your `package.json` to link your `strapi-provider-upload-{provider-name}` dependency to point to the [local path](https://docs.npmjs.com/files/package.json#local-paths) of your provider. ```json +//path: ./package.json + { ... "dependencies": { @@ -458,4 +490,4 @@ If you want to create your own provider without publishing it on **npm** you can } ``` -- Finally, run `yarn install` or `npm install` to install your new custom provider. +4. Finally, run `yarn install` or `npm install` to install your new custom provider.