diff --git a/docs/.vuepress/config/sidebar-developer.js b/docs/.vuepress/config/sidebar-developer.js index cf1aba58ec..2546cdb018 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/providers.md', 'Providers'], ], }, { @@ -423,6 +424,7 @@ const developer = [ ['/developer-docs/latest/plugins/users-permissions', 'Users & Permissions'], ['/developer-docs/latest/plugins/email', 'Email'], ['/developer-docs/latest/plugins/upload', 'Upload'], + ['/developer-docs/latest/plugins/sentry', 'Sentry'], ['/developer-docs/latest/plugins/documentation', 'API Documentation'], ], sidebarDepth: 1, diff --git a/docs/.vuepress/theme/global-components/PluginsLinks.vue b/docs/.vuepress/theme/global-components/PluginsLinks.vue index 0ea10d7a8f..dd869ce40f 100644 --- a/docs/.vuepress/theme/global-components/PluginsLinks.vue +++ b/docs/.vuepress/theme/global-components/PluginsLinks.vue @@ -261,6 +261,19 @@ + + +
+ + + + + +
diff --git a/docs/developer-docs/latest/developer-resources/error-handling.md b/docs/developer-docs/latest/developer-resources/error-handling.md index e8dacf8c5f..239e01de46 100644 --- a/docs/developer-docs/latest/developer-resources/error-handling.md +++ b/docs/developer-docs/latest/developer-resources/error-handling.md @@ -63,7 +63,7 @@ Errors thrown by the GraphQL API are included in the [response](/developer-docs/ The recommended way to throw errors when developing any custom logic with Strapi is to have the [controller](/developer-docs/latest/development/backend-customization/controllers.md) respond with the correct status and body. -This can be done by calling an error function on the context (i.e. `ctx`). Available error functions are listed in the [http-errors documentation](https://github.com/jshttp/http-errors#list-of-all-constructors) but their name should be camel-cased to be used by Strapi (e.g. `badRequest`). +This can be done by calling an error function on the context (i.e. `ctx`). Available error functions are listed in the [http-errors documentation](https://github.com/jshttp/http-errors#list-of-all-constructors) but their name should be lower camel-cased to be used by Strapi (e.g. `badRequest`). Error functions accept 2 parameters that correspond to the `error.message` and `error.details` attributes [received](#receiving-errors) by a developer querying the API: diff --git a/docs/developer-docs/latest/development/providers.md b/docs/developer-docs/latest/development/providers.md new file mode 100644 index 0000000000..27b68d0e2b --- /dev/null +++ b/docs/developer-docs/latest/development/providers.md @@ -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-- --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. + +:::: 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: '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: + +:::: 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--`) +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 diff --git a/docs/developer-docs/latest/getting-started/troubleshooting.md b/docs/developer-docs/latest/getting-started/troubleshooting.md index f52b23ce78..2f721601a6 100644 --- a/docs/developer-docs/latest/getting-started/troubleshooting.md +++ b/docs/developer-docs/latest/getting-started/troubleshooting.md @@ -103,6 +103,6 @@ Due to these two issues, it is recommended you use a proxy application such as [ ## Is X feature available yet? -You can see the [ProductBoard roadmap](https://portal.productboard.com/strapi) to see which feature requests are currently being worked on and which have not been started yet. +You can see the [Public roadmap](https://feedback.strapi.io/) to see which feature requests are currently being worked on and which have not been started yet. diff --git a/docs/developer-docs/latest/plugins/email.md b/docs/developer-docs/latest/plugins/email.md index 9885fe6347..3c4fc8d572 100644 --- a/docs/developer-docs/latest/plugins/email.md +++ b/docs/developer-docs/latest/plugins/email.md @@ -6,219 +6,119 @@ canonicalUrl: https://docs.strapi.io/developer-docs/latest/plugins/email.html # Email -Thanks to the plugin `Email`, you can send email from your server or externals providers such as **Sendgrid**. +The Email plugin enables applications to send emails from a server or an external provider. The Email plugin uses the Strapi global API, meaning it can be called from anywhere inside a Strapi application. Two of the most common use cases are in the Strapi back end and in the admin panel. The following documentation describes how to use the Email plugin in a controller or service for back-end use cases and using a lifecycle hook for admin panel use cases. -## Programmatic usage +::: prerequisites -### Send an email - `.send()` +The Email plugin requires a provider and a provider configuration in the `plugins.js` file. See the [Providers](/developer-docs/latest/development/providers.md) documentation for detailed installation and configuration instructions. -In your custom controllers or services you may want to send email. -By using the following function, Strapi will use the configured provider to send an email. +::: + +::: note +[`Sendmail`](https://www.npmjs.com/package/sendmail) is the default email provider in the Strapi Email plugin. It provides functionality for the local development environment but is not production-ready in the default configuration. For production stage applications you need to further configure `Sendmail` or change providers. The [Providers](/developer-docs/latest/development/providers.md) documentation has instructions for changing providers, configuring providers, and creating a new email provider. +::: + +## Sending emails with a controller or service + +The Email plugin has an `email` [service](/developer-docs/latest/development/backend-customization/services.md#services) that contains 2 functions to send emails: + +* `send()` directly contains the email contents, +* `sendTemplatedEmail()` consumes data from the Content Manager to populate emails, streamlining programmatic emails. + +### Using the `send()` function + +To trigger an email in response to a user action add the `send()` function to a [controller](/developer-docs/latest/development/backend-customization/controllers.md) or [service](/developer-docs/latest/development/backend-customization/services.md). The send function has the following properties: -**Example** +| Property | Type | Format | Description | +|-----------|----------|---------------|-------------------------------------------------------| +| `from` | `string` | email address | If not specified, uses `defaultFrom` in `plugins.js`. | +| `to` | `string` | email address | Required | +| `cc` | `string` | email address | Optional | +| `bcc` | `string` | email address | Optional | +| `replyTo` | `string` | email address | Optional | +| `subject` | `string` | - | Required | +| `text` | `string` | - | Either `text` or `html` is required. | +| `html` | `string` | HTML | Either `text` or `html` is required. | ```js -await strapi.plugins['email'].services.email.send({ - to: 'paulbocuse@strapi.io', - from: 'joelrobuchon@strapi.io', - cc: 'helenedarroze@strapi.io', - bcc: 'ghislainearabian@strapi.io', - replyTo: 'annesophiepic@strapi.io', - subject: 'Use strapi email provider successfully', - text: 'Hello world!', - html: 'Hello world!', -}); -``` -### Send an email using a template - `.sendTemplatedEmail()` +// This code example can be used in a controller or a service +// path: ./src/api/{api name}/controllers/{api name}.js or ./src/api/{api name}/services/{api name}.js + + await strapi.plugins['email'].services.email.send({ + to: 'valid email address', + from: 'your verified email address', //e.g. single sender verification in SendGrid + cc: 'valid email address', + bcc: 'valid email address', + replyTo: 'valid email address', + subject: 'The Strapi Email plugin worked successfully', + text: 'Hello world!', + html: 'Hello world!', + }), +``` -When you send an email, you will most likely want to build it from a template you wrote. -The email plugin provides the service `sendTemplatedEmail` that compile the email and then sends it. The function have the following params: +### Using the `sendTemplatedEmail()` function -| param | description | type | default | -| --------------- | ------------------------------------------------------------------------------------------------------------------------ | ------ | ------- | -| `emailOptions` | Object that contains email options (`to`, `from`, `replyTo`, `cc`, `bcc`) except `subject`, `text` and `html` | object | `{}` | -| `emailTemplate` | Object that contains `subject`, `text` and `html` as [lodash string templates](https://lodash.com/docs/4.17.15#template) | object | `{}` | -| `data` | Object that contains the data used to compile the templates | object | `{}` | +The `sendTemplatedEmail()` function is used to compose emails from a template. The function compiles the email from the available properties and then sends the email. To use the `sendTemplatedEmail()` function, define the `emailTemplate` object and add the function to a controller or service. The function calls the `emailTemplate` object, and can optionally call the `emailOptions` and `data` objects: -**Example** +| Parameter | Description | Type | Default | +|-----------------|--------------------------------------------------------------------------------------------------------------------------------------------|----------|---------| +| `emailOptions`

Optional | Contains email addressing properties: `to`, `from`, `replyTo`, `cc`, and `bcc` | `object` | { } | +| `emailTemplate` | Contains email content properties: `subject`, `text`, and `html` using [Lodash string templates](https://lodash.com/docs/4.17.15#template) | `object` | { } | +| `data`

Optional | Contains the data used to compile the templates | `object` | { } | ```js + +// This code example can be used in a controller or a service +// path: ./src/api/{api name}/controllers/{api name}.js or ./src/api/{api name}/services/{api name}.js + const emailTemplate = { subject: 'Welcome <%= user.firstname %>', - text: `Welcome on mywebsite.fr! + text: `Welcome to mywebsite.fr! Your account is now linked with: <%= user.email %>.`, - html: `

Welcome on mywebsite.fr!

+ html: `

Welcome to mywebsite.fr!

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

`, }; await strapi.plugins['email'].services.email.sendTemplatedEmail( { to: user.email, - // from: is not specified, so it's the defaultFrom that will be used instead + // from: is not specified, the defaultFrom is used. }, - emailTemplate, + emailTemplate, { user: _.pick(user, ['username', 'email', 'firstname', 'lastname']), } ); ``` -## Configure the plugin - -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. - -Below are the providers maintained by the Strapi team: - -- [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/). +## Sending emails with a lifecycle hook -To install a new provider run: - - - - -```sh -npm install @strapi/provider-email-sendgrid --save -``` - - - -```sh -yarn add @strapi/provider-email-sendgrid --save -``` - - - - -### 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. - -::: note -When using community providers, pass the full package name to the `provider` key (e.g. `provider: 'strapi-provider-email-mandrill'`). Only Strapi-maintained providers can use the shortcode format (e.g. `provider: 'sendmail'`). -::: - -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`. + To trigger an email based on administrator actions in the admin panel use [lifecycle hooks](/developer-docs/latest/development/backend-customization/models.md#lifecycle-hooks) and the [`send()` function](#using-the-send-function). For example, to send an email each time a new content entry is added in the Content Manager use the `afterCreate` lifecycle hook: ```js -module.exports = ({ env }) => ({ - // ... - email: { - config: { - provider: 'sendgrid', - providerOptions: { - apiKey: env('SENDGRID_API_KEY'), - }, - settings: { - defaultFrom: 'juliasedefdjian@strapi.io', - defaultReplyTo: 'juliasedefdjian@strapi.io', - testAddress: 'juliasedefdjian@strapi.io', - }, - }, - }, - // ... -}); -``` - -::: 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](/developer-docs/latest/setup-deployment-guides/configurations/optional/environment.md) -::: - -::: tip -Only one email provider will be active at all time. If the email provider setting isn't picked up by strapi, verify you have put the file `plugins.js` in the correct folder, and with correct filename. The selection of email provider is done via configuration file only. -::: - -::: tip -When testing the new email provider with those two email templates created during strapi setup, the _shipper email_ on the template, with default no-reply@strapi.io need to be updated in according to your email provider, otherwise it will fail the test. -More info here: [Configure templates Locally](/user-docs/latest/settings/configuring-users-permissions-plugin-settings.md#configuring-email-templates) -::: -## Create new provider +// path: ./src/api/{api-name}/content-types/{content-type-name}/lifecycles.js -Default template - -```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 - -To use it you will have to publish it on **npm**. - -### Create a local provider - -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 (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 -{ - ... - "dependencies": { - ... - "strapi-provider-email-[...]": "file:providers/strapi-provider-email-[...]", - ... - } -} -``` - -- Finally, run `yarn install` or `npm install` to install your new custom provider. - -## Troubleshooting - -You received an `Auth.form.error.email.invalid` error even though the email is valid and exists in the database. - -Here is the error response you get from the API. - -```json -{ - "statusCode": 400, - "error": "Bad Request", - "message": [ - { - "messages": [ - { - "id": "Auth.form.error.email.invalid" + async afterCreate(event) { // Connected to "Save" button in admin panel + const { result } = event; + + try{ + await strapi.plugins['email'].services.email.send({ + to: 'valid email address', + from: 'your verified email address', // e.g. single sender verification in SendGrid + cc: 'valid email address', + bcc: 'valid email address', + replyTo: 'valid email address', + subject: 'The Strapi Email plugin worked successfully', + text: '${fieldName}', // Replace with a valid field ID + html: 'Hello world!', + + }) + } catch(err) { + console.log(err); } - ] } - ] } ``` - -This error is due to your IP connection. By default, Strapi uses the [`sendmail`](https://github.com/guileen/node-sendmail) package. - -This package sends an email from the server it runs on. Depending on the network you are on, the connection to the SMTP server could fail. - -Here is the `sendmail` error. - -``` -Error: SMTP code:550 msg:550-5.7.1 [87.88.179.13] The IP you're using to send mail is not authorized to -550-5.7.1 send email directly to our servers. Please use the SMTP relay at your -550-5.7.1 service provider instead. Learn more at -550 5.7.1 https://support.google.com/mail/?p=NotAuthorizedError 30si2132728pjz.75 - gsmtp -``` - -To fix it, we suggest you to use another email provider that uses third party to send emails. - -When using a third party provider, you avoid having to setup a mail server on your server and get extra features such as email analytics. diff --git a/docs/developer-docs/latest/plugins/sentry.md b/docs/developer-docs/latest/plugins/sentry.md new file mode 100644 index 0000000000..5949d933e3 --- /dev/null +++ b/docs/developer-docs/latest/plugins/sentry.md @@ -0,0 +1,140 @@ +--- +title: Sentry - Strapi Developer Docs +description: Send email from your server or externals providers. +canonicalUrl: https://docs.strapi.io/developer-docs/latest/plugins/email.html +--- + +# Sentry + +This plugin enables you to track errors in your Strapi application using [Sentry](https://sentry.io/welcome/). + +By using the Sentry plugin you can: + +* Initialize a Sentry instance upon startup of a Strapi application +* Send Strapi application errors as events to Sentry +* Include additional metadata in Sentry events to assist in debugging +* Expose a [global Sentry service](#global-sentry-service-access) + +Begin by first [installing](#installation) the Sentry plugin, and then [configuring](#configuration) the plugin to enable your Strapi application to send events to the Sentry instance. + +## Installation + +Install the Sentry plugin by adding the dependency to your Strapi application as follows: + + + + +```sh +npm install @strapi/plugin-sentry +``` + + + +```sh +yarn add @strapi/plugin-sentry +``` + + + + +## Configuration + +Create or edit your `./config/plugins.js` file to configure the Sentry plugin. The following properties are available: + +| Property | Type | Default Value | Description | +| -------- | ---- | ------------- |------------ | +| `dsn` | string | `null` | Your Sentry [data source name](https://docs.sentry.io/product/sentry-basics/dsn-explainer/). | +| `sendMetadata` | boolean | `true` | Whether the plugin should attach additional information (e.g. OS, browser, etc.) to the events sent to Sentry. | +| `init` | object | `{}` | A config object that is passed directly to Sentry during initialization. See the official [Sentry documentation](https://docs.sentry.io/platforms/node/configuration/options/) for all available options. | + +An example configuration: + +```js +// path: ./config/plugins.js + +module.exports = ({ env }) => ({ + // ... + sentry: { + enabled: true, + config: { + dsn: env('SENTRY_DSN'), + sendMetadata: true, + }, + }, + // ... +}); +``` + +### Environment configuration + +Using the [`env` utility](/developer-docs/latest/setup-deployment-guides/configurations/optional/environment.md#configuration-using-environment-variables), you can enable or disable the Sentry plugin based on the environment. For example, to only enable the plugin in your `production` environment: + +```js +// path: ./config/plugins.js + +module.exports = ({ env }) => ({ + // ... + sentry: { + enabled: env('NODE_ENV') === 'production', + }, + // ... +}); +``` + +## Global Sentry service access + +After installing and configuring the plugin, you can access a Sentry service in your Strapi application as follows: + +```js +const sentryService = strapi.plugin('sentry').service('sentry'); +``` + +This service exposes the following methods: + +| Method | Description | Parameters | +| ------ | ----------- | ---------- | +| `sendError()` | Manually send errors to Sentry. |

  • error: The error to be sent.
  • configureScope: Optional. Enables you to customize the error event.

See the official [Sentry documentation](https://docs.sentry.io/platforms/node/enriching-events/scopes/#configuring-the-scope) for more details. | +| `getInstance()` | Used for direct access to the Sentry instance. | | + +Below are examples for each method. + +:::: tabs card + +::: tab sendError + +```js +try { + // Your code here +} catch (error) { + // Either send a simple error + strapi + .plugin('sentry') + .service('sentry') + .sendError(error); + + // Or send an error with a customized Sentry scope + strapi + .plugin('sentry') + .service('sentry') + .sendError(error, (scope, sentryInstance) => { + // Customize the scope here + scope.setTag('my_custom_tag', 'Tag value'); + }); + throw error; +} +``` + +::: + +::: tab getInstance + +```js +const sentryInstance = strapi + .plugin('sentry') + .service('sentry') + .getInstance(); +``` + +::: + +:::: \ No newline at end of file diff --git a/docs/developer-docs/latest/plugins/upload.md b/docs/developer-docs/latest/plugins/upload.md index 4ce38efb77..5722342c84 100644 --- a/docs/developer-docs/latest/plugins/upload.md +++ b/docs/developer-docs/latest/plugins/upload.md @@ -6,15 +6,50 @@ canonicalUrl: https://docs.strapi.io/developer-docs/latest/plugins/upload.html # Upload -The `Upload` plugin is used to implement the Media Library available in the admin panel. With it you can upload any kind of file on your server or external providers such as **AWS S3**. +The Upload plugin is the backend powering the Media Library plugin available by default in the Strapi admin panel. Using either the Media Library from the admin panel or the upload API directly, you can upload any kind of file for use in your Strapi application. + +By default Strapi provides a [provider](../development/providers.md) that uploads files to a local directory. Additional providers are available should you want to upload your files to another location. + +The providers maintained by Strapi include: + +- [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) ## Configuration -Currently the Strapi middleware in charge of parsing requests needs to be configured to support file sizes larger than the default of **200MB**. +This section details configuration options for the default upload provider. If using another provider (e.g. AWS S3 or Rackspace), see the available configuration parameters in that provider's documentation. + +### Local server + +By default Strapi accepts `localServer` configurations for locally uploaded files. These will be passed as the options for [koa-static](https://github.com/koajs/static). + +You can provide them by creating or editing the `./config/plugins.js` file. The following example sets the `max-age` header. + +```js +// path: ./config/plugins.js + +module.exports = ({ env })=>({ + upload: { + config: { + providerOptions: { + localServer: { + maxage: 300000 + }, + }, + }, + }, +}); +``` + +### Max file size + +Currently the Strapi middleware in charge of parsing requests needs to be configured to support file sizes larger than the default of 200MB. 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 `body` middleware configuration in `./config/middlewares.js`: +You can pass configuration to the middleware directly by setting it in the [`body` middleware](/developer-docs/latest/setup-deployment-guides/configurations/required/middlewares.md#body) configuration in `./config/middlewares.js`: ```js // path: ./config/middlewares.js @@ -36,7 +71,7 @@ module.exports = { }; ``` -### 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 | @@ -105,11 +140,13 @@ module.exports = ({ env }) => ({ -## Upload files +## Examples + +### Upload files -To upload files to your application. +Upload one or more files to your application. -### Parameters +The following parameters are accepted: - `files`: The file(s) to upload. The value(s) can be a Buffer or Stream. @@ -166,22 +203,22 @@ const response = await fetch('http://localhost:1337/api/upload', { You have to send FormData in your request body. ::: -## Upload files related to an entry +### Upload entry files -To upload files that will be linked to a specific entry. +Upload one or more files that will be linked to a specific entry. -### Request parameters - -- `files`: The file(s) to upload. The value(s) can be a Buffer or Stream. -- `path` (optional): The folder where the file(s) will be uploaded to (only supported on strapi-provider-upload-aws-s3). -- `refId`: The ID of the entry which the file(s) will be linked to. -- `ref`: The unique ID (uid) of the model which the file(s) will be linked to (see more below). -- `source` (optional): The name of the plugin where the model is located. -- `field`: The field of the entry which the file(s) will be precisely linked to. +The following parameters are accepted: -### Examples +| Parameter | Description | +| --------- | ----------- | +|`files` | The file(s) to upload. The value(s) can be a Buffer or Stream. | +|`path` (optional) | The folder where the file(s) will be uploaded to (only supported on strapi-provider-upload-aws-s3). | +| `refId` | The ID of the entry which the file(s) will be linked to. | +| `ref` | The unique ID (uid) of the model which the file(s) will be linked to (see more below). | +| `source` (optional) | The name of the plugin where the model is located. | +| `field` | The field of the entry which the file(s) will be precisely linked to. | -The `Restaurant` model attributes: +For example, given the `Restaurant` model attributes: ```json // path: ./src/api/restaurant/content-types/restaurant/schema.json @@ -201,7 +238,7 @@ The `Restaurant` model attributes: } ``` -Code +The corresponding code would be: ```html
@@ -231,13 +268,11 @@ Code You have to send FormData in your request body. ::: -## Upload file during entry creation +### Upload files at entry creation You can also add files during your entry creation. -### Examples - -The `Restaurant` model attributes: +For example, given the `Restaurant` model attributes: ```json // path: ./src/api/restaurant/content-types/restaurant/schema.json @@ -255,10 +290,9 @@ The `Restaurant` model attributes: } // ... } - ``` -Code +The corresponding code would be: ```html @@ -298,18 +332,17 @@ Code ``` -Your entry data has to be contained in a `data` key and you need to `JSON.stringify` this object. The keys for files, need to be prefixed with `files` (example with a cover attribute: `files.cover`). +Your entry data has to be contained in a `data` key and you need to `JSON.stringify` this object. The keys for files need to be prefixed with `files` (e.g. for a cover attribute: `files.cover`). ::: tip -If you want to upload files for a component, you will have to specify the index of the item you want to add the file to. -Example `files.my_component_name[the_index].attribute_name` +If you want to upload files for a component, you will have to specify the index of the item you want to add the file to: `files.my_component_name[the_index].attribute_name` ::: :::caution You have to send FormData in your request body. ::: -## Models definition +### Models definition Adding a file attribute to a model (or the model of another plugin) is like adding a new association. @@ -364,172 +397,3 @@ In our second example, you can upload and attach multiple pictures to the restau // ... } ``` - -## Using a provider - -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. - -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: - - - - -```sh -npm install @strapi/provider-upload-aws-s3 --save -``` - - - -```sh -yarn add @strapi/provider-upload-aws-s3 -``` - - - - -### Local server - -By default Strapi accepts `localServer` configurations for locally uploaded files. They will be passed as the options for [koa-static](https://github.com/koajs/static). - -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: { - providerOptions: { - localServer: { - maxage: 300000 - }, - }, - }, - }, -}); -``` - -### Enabling the provider - -To enable the provider, create or edit the file at `./config/plugins.js` - -::: note -When using community providers, pass the full package name to the `provider` key (e.g. `provider: 'strapi-provider-upload-google-cloud-storage'`). Only Strapi-maintained providers can use the shortcode format (e.g. `provider: 'aws-s3'`). -::: - -```js -// path: ./config/plugins.js - -module.exports = ({ env }) => ({ - // ... - upload: { - 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 [middleware 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. - -You can set a specific configuration in the `./config/env/{env}/plugins.js` configuration file and it will be used to overwrite the one in the default configuration. - -## Create providers - -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). - -Your provider needs to export the following interface: - -```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 - }, - }; - }, -}; -``` - -:::tip -For performance reasons, the upload plugin will only use the `uploadStream` function if it exists, otherwise it will fallback on the `upload` function. -::: - -You can then publish it to make it available to the community. - -### Create a local provider - -If you want to create your own provider without publishing it on **npm** you can follow these steps: - -1. Create a `./providers/upload-{provider-name}` folder in your root application folder. -2. Create your provider as explained in the [documentation](#create-providers) above. -3. Update your `package.json` to link your `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": { - ... - "@strapi/provider-upload-{provider-name}": "file:providers/upload-{provider-name}" - ... - } -} -``` - -4. Update the Upload plugin configuration: - -```js -// path: ./config/plugins.js - -module.exports = ({ env }) => ({ - // ... - upload: { - config: { - provider: '{provider-name}', - providerOptions: {}, - }, - }, - // ... -}); -``` - -5. Run `yarn install` or `npm install` to install your new custom provider. diff --git a/docs/developer-docs/latest/setup-deployment-guides/configurations/required/admin-panel.md b/docs/developer-docs/latest/setup-deployment-guides/configurations/required/admin-panel.md index 99e38a5405..b575ae401a 100644 --- a/docs/developer-docs/latest/setup-deployment-guides/configurations/required/admin-panel.md +++ b/docs/developer-docs/latest/setup-deployment-guides/configurations/required/admin-panel.md @@ -28,10 +28,10 @@ The `./config/admin.js` file can include the following parameters: | `host` | Use a different host for the admin panel. Only used along with `strapi develop --watch-admin` | string | `localhost` | | `port` | Use a different port for the admin panel. Only used along with `strapi develop --watch-admin` | string | `8000` | | `serveAdminPanel` | If false, the admin panel won't be served. Note: the `index.html` will still be served, see [defaultIndex option](/developer-docs/latest/setup-deployment-guides/configurations/required/middlewares.md) | boolean | `true` | -| `forgotPassword` | Settings to customize the forgot password email (see more here: [Forgot Password Email](/developer-docs/latest/development/admin-customization.md#forgotten-password-email)) | object | {} | -| `forgotPassword.emailTemplate` | Email template as defined in [email plugin](/developer-docs/latest/plugins/email.md#programmatic-usage) | object | [Default template](https://github.com/strapi/strapi/tree/master/packages/strapi-admin/config/email-templates/forgot-password.js) | -| `forgotPassword.from` | Sender mail address | string | Default value defined in your [provider configuration](/developer-docs/latest/plugins/email.md#configure-the-plugin) | -| `forgotPassword.replyTo` | Default address or addresses the receiver is asked to reply to | string | Default value defined in your [provider configuration](/developer-docs/latest/plugins/email.md#configure-the-plugin) | +| `forgotPassword` | Settings to customize the forgot password email (see [Forgot Password Email](/developer-docs/latest/development/admin-customization.md#forgotten-password-email)) | object | {} | +| `forgotPassword.emailTemplate` | Email template as defined in [email plugin](/developer-docs/latest/plugins/email.md#using-the-sendtemplatedemail-function) | object | [Default template](https://github.com/strapi/strapi/tree/master/packages/strapi-admin/config/email-templates/forgot-password.js) | +| `forgotPassword.from` | Sender mail address | string | Default value defined in your [provider configuration](/developer-docs/latest/development/providers.md#configuring-providers) | +| `forgotPassword.replyTo` | Default address or addresses the receiver is asked to reply to | string | Default value defined in your [provider configuration](/developer-docs/latest/development/providers.md#configuring-providers) | ## Configurations diff --git a/docs/developer-docs/latest/setup-deployment-guides/deployment/hosting-guides/amazon-aws.md b/docs/developer-docs/latest/setup-deployment-guides/deployment/hosting-guides/amazon-aws.md index a13aea9bc0..63a169011b 100644 --- a/docs/developer-docs/latest/setup-deployment-guides/deployment/hosting-guides/amazon-aws.md +++ b/docs/developer-docs/latest/setup-deployment-guides/deployment/hosting-guides/amazon-aws.md @@ -362,7 +362,7 @@ module.exports = ({ env }) => ({ }); ``` -Checkout the documentation about using an upload provider [here](/developer-docs/latest/plugins/upload.md#using-a-provider). +Checkout the documentation about using an upload provider [here](/developer-docs/latest/development/providers.md). #### 4. Push your local changes to your project's GitHub repository. diff --git a/docs/developer-docs/latest/setup-deployment-guides/deployment/hosting-guides/azure.md b/docs/developer-docs/latest/setup-deployment-guides/deployment/hosting-guides/azure.md index 497dbad6fe..6ef12e727a 100644 --- a/docs/developer-docs/latest/setup-deployment-guides/deployment/hosting-guides/azure.md +++ b/docs/developer-docs/latest/setup-deployment-guides/deployment/hosting-guides/azure.md @@ -662,4 +662,4 @@ There are many different types of proxy services you could use, anything from lo #### 3. File upload providers -There are many options for storing files outside of your virtual machine, Strapi have built a few and the community is constantly building new ones. See the [following guide](/developer-docs/latest/plugins/upload.md#create-providers) on searching for options as well as installing them. +There are many options for storing files outside of your virtual machine, Strapi have built a few and the community is constantly building new ones. See the [following guide](/developer-docs/latest/development/providers.md) on searching for options as well as installing them. diff --git a/docs/developer-docs/latest/setup-deployment-guides/deployment/hosting-guides/heroku.md b/docs/developer-docs/latest/setup-deployment-guides/deployment/hosting-guides/heroku.md index e849aa6e98..55286efa60 100644 --- a/docs/developer-docs/latest/setup-deployment-guides/deployment/hosting-guides/heroku.md +++ b/docs/developer-docs/latest/setup-deployment-guides/deployment/hosting-guides/heroku.md @@ -363,7 +363,7 @@ heroku open Like with project updates on Heroku, the file system doesn't support local uploading of files as they will be wiped when Heroku "cycles" the dyno. This type of file system is called [ephemeral](https://devcenter.heroku.com/articles/dynos#ephemeral-filesystem), which means the file system only lasts until the dyno is restarted (with Heroku this happens any time you redeploy or during their regular restart which can happen every few hours or every day). -Due to Heroku's filesystem you will need to use an upload provider such as AWS S3, Cloudinary, or Rackspace. You can view the documentation for installing providers [here](/developer-docs/latest/plugins/upload.md#create-providers) and you can see a list of providers from both Strapi and the community on [npmjs.com](https://www.npmjs.com/search?q=strapi-provider-upload-&page=0&perPage=20). +Due to Heroku's filesystem you will need to use an upload provider such as AWS S3, Cloudinary, or Rackspace. You can view the documentation for installing providers [here](/developer-docs/latest/development/providers.md) and you can see a list of providers from both Strapi and the community on [npmjs.com](https://www.npmjs.com/search?q=strapi-provider-upload-&page=0&perPage=20). ## Gzip diff --git a/docs/package.json b/docs/package.json index 971d861569..5a211870a7 100644 --- a/docs/package.json +++ b/docs/package.json @@ -1,6 +1,6 @@ { "name": "strapi-docs", - "version": "4.2.2", + "version": "4.2.3", "main": "index.js", "scripts": { "dev": "yarn create:config-file && vuepress dev", diff --git a/docs/user-docs/latest/content-types-builder/configuring-fields-content-type.md b/docs/user-docs/latest/content-types-builder/configuring-fields-content-type.md index b23c33b28c..5866aa4d29 100644 --- a/docs/user-docs/latest/content-types-builder/configuring-fields-content-type.md +++ b/docs/user-docs/latest/content-types-builder/configuring-fields-content-type.md @@ -302,6 +302,10 @@ The Enumeration field allows to configure a list of values displayed in a drop-d :::: +::: caution +Since Strapi v4.1.3, enumeration values should always have an alphabetical character preceding any number as it could otherwise cause the server to crash without notice when the GraphQL plugin is installed. +::: + ### Media The Media field allows to choose one or more media files (e.g. image, video) from those uploaded in the Media Library of the application. diff --git a/docs/user-docs/latest/plugins/introduction-to-plugins.md b/docs/user-docs/latest/plugins/introduction-to-plugins.md index 41c33fbbeb..e5a34ce22f 100644 --- a/docs/user-docs/latest/plugins/introduction-to-plugins.md +++ b/docs/user-docs/latest/plugins/introduction-to-plugins.md @@ -32,5 +32,5 @@ Some plugins can be further extended through the configuration of _providers_, p Currently, the only plugins designed to work with providers are the: -* [Email plugin](../../../developer-docs/latest/plugins/email.md#configure-the-plugin), and -* [Media Library plugin](../../../developer-docs/latest/plugins/upload.md#using-a-provider) (implemented via the [Upload plugin](../../../developer-docs/latest/plugins/upload.md)). +* [Email plugin](/developer-docs/latest/plugins/email.md), and +* Media Library plugin (implemented via the [Upload plugin](/developer-docs/latest/plugins/upload.md)).