diff --git a/docs/developer-docs/latest/developer-resources/cli/CLI.md b/docs/developer-docs/latest/developer-resources/cli/CLI.md index 872b31d921..c4df7b6094 100644 --- a/docs/developer-docs/latest/developer-resources/cli/CLI.md +++ b/docs/developer-docs/latest/developer-resources/cli/CLI.md @@ -334,6 +334,22 @@ options [--delete-files] Some plugins have admin panel integrations, your admin panel might have to be rebuilt. This can take some time. ::: +## strapi telemetry:disable + +Disable data collection for the project (see [Usage Information](/developer-docs/latest/getting-started/usage-information.md)). + +```bash +strapi telemetry:disable +``` + +## strapi telemetry:enable + +Re-enable data collection for the project after it was disabled (see [Usage Information](/developer-docs/latest/getting-started/usage-information.md)). + +```bash +strapi telemetry:enable +``` + ## strapi console Start the server and eval commands in your application in real time. diff --git a/docs/developer-docs/latest/development/plugins-extension.md b/docs/developer-docs/latest/development/plugins-extension.md index 4cc3181314..e09c65b09e 100644 --- a/docs/developer-docs/latest/development/plugins-extension.md +++ b/docs/developer-docs/latest/development/plugins-extension.md @@ -7,7 +7,7 @@ canonicalUrl: https://docs.strapi.io/developer-docs/latest/development/plugins-e # Plugins extension -Strapi comes with [plugins](/developer-docs/latest/plugins/plugins-intro.md) that can be installed from the Marketplace or as npm packages. You can also create your own plugins (see [plugins development](/developer-docs/latest/development/plugins-development.md)) or extend the existing ones. +Strapi comes with [plugins](/developer-docs/latest/plugins/plugins-intro.md) that can be installed from the [Marketplace](/user-docs/latest/plugins/installing-plugins-via-marketplace.md#installing-marketplace-plugins-and-providers) or as npm packages. You can also create your own plugins (see [plugins development](/developer-docs/latest/development/plugins-development.md)) or extend the existing ones. Plugin extensions code is located in the `./src/extensions` folder (see [project structure](/developer-docs/latest/setup-deployment-guides/file-structure.md)). Some plugins automatically create files there, ready to be modified. @@ -16,7 +16,6 @@ Plugin extensions code is located in the `./src/extensions` folder (see [project ```bash /extensions /some-plugin-to-extend - strapi-admin.js strapi-server.js /content-types /some-content-type-to-extend @@ -24,16 +23,26 @@ Plugin extensions code is located in the `./src/extensions` folder (see [project /another-content-type-to-extend model.json /another-plugin-to-extend - strapi-admin.js + strapi-server.js ``` ::: Plugins can be extended in 2 ways: -- [extending the plugin's Content-Types](#extending-a-plugin-s-content-types) +- [extending the plugin's content-types](#extending-a-plugin-s-content-types) - [extending the plugin's interface](#extending-a-plugin-s-interface) (e.g. to add controllers, services, policies, middlewares and more) +::: note +Currently it's not possible to extend the admin panel part of a plugin. Consider using [patch-package](https://www.npmjs.com/package/patch-package) if admin panel customizations are required. +::: + +:::warning +New versions of Strapi are released with [migration guides](/developer-docs/latest/update-migration-guides/migration-guides.md), but these guides might not cover unexpected breaking changes in your plugin extensions. Consider forking a plugin if extensive customizations are required. +::: + +## Extending a plugin's content-types + A plugin's Content-Types can be extended in 2 ways: using the programmatic interface within `strapi-server.js` and by overriding the content-types schemas. The final schema of the content-types depends on the following loading order: @@ -43,20 +52,14 @@ The final schema of the content-types depends on the following loading order: 3. the content-types declarations in the [`content-types` key exported from `strapi-server.js`](/developer-docs/latest/developer-resources/plugin-api-reference/server.md#content-types) 4. the content-types declarations in the [`register()` function](/developer-docs/latest/setup-deployment-guides/configurations/optional/functions.md#register) of the Strapi application -:::warning -New versions of Strapi are released with [migration guides](/developer-docs/latest/update-migration-guides/migration-guides.md), but these guides might not cover unexpected breaking changes in your plugin extensions. Consider forking a plugin if extensive customizations are required. -::: - -## Extending a plugin's Content-Types - -To overwrite a plugin's [Content-Types](/developer-docs/latest/development/backend-customization/models.md): +To overwrite a plugin's [content-types](/developer-docs/latest/development/backend-customization/models.md): 1. _(optional)_ Create the `./src/extensions` folder at the root of the app, if the folder does not already exist. 2. Create a subfolder with the same name as the plugin to be extended. 3. Create a `content-types` subfolder. 4. Inside the `content-types` subfolder, create another subfolder with the same [singularName](/developer-docs/latest/development/backend-customization/models.md#model-information) as the content-type to overwrite. -5. Inside this `content-types/name-of-content-type` subfolder, define the new schema for the Content-Type in a `schema.json` file (see [schema](/developer-docs/latest/development/backend-customization/models.md#model-schema) documentation). -6. _(optional)_ Repeat steps 4 and 5 for each Content-Type to overwrite. +5. Inside this `content-types/name-of-content-type` subfolder, define the new schema for the content-type in a `schema.json` file (see [schema](/developer-docs/latest/development/backend-customization/models.md#model-schema) documentation). +6. _(optional)_ Repeat steps 4 and 5 for each content-type to overwrite. ## Extending a plugin's interface @@ -70,13 +73,11 @@ A plugin's interface can be extended at step 2 (i.e. within `./src/extensions`) ### Within the extensions folder -To extend a plugin's interface using the `./src/extensions` folder: +To extend a plugin's server interface using the `./src/extensions` folder: 1. _(optional)_ Create the `./src/extensions` folder at the root of the app, if the folder does not already exist. 2. Create a subfolder with the same name as the plugin to be extended. -3. Depending on what needs to be extended: - * create a `strapi-server.js` file to extend a plugin's back end using the [Server API](/developer-docs/latest/developer-resources/plugin-api-reference/server.md) - * or create a `strapi-admin.js` file to extend the admin panel with the [Admin Panel API](/developer-docs/latest/developer-resources/plugin-api-reference/admin-panel.md). +3. Create a `strapi-server.js` file to extend a plugin's back end using the [Server API](/developer-docs/latest/developer-resources/plugin-api-reference/server.md). 4. Within this file, define and export a function. The function receives the `plugin` interface as an argument so it can be extended. ::: details Example of backend extension diff --git a/docs/developer-docs/latest/getting-started/usage-information.md b/docs/developer-docs/latest/getting-started/usage-information.md index 282f374e06..61c2cf0a29 100644 --- a/docs/developer-docs/latest/getting-started/usage-information.md +++ b/docs/developer-docs/latest/getting-started/usage-information.md @@ -68,7 +68,9 @@ yarn strapi telemetry:disable -Alternatively, the `telemetryDisabled: true` flag in the project `package.json` file will also disable data collection. Deleting the flag or setting it to false will re-enable data collection. +Alternatively, the `telemetryDisabled: true` flag in the project `package.json` file will also disable data collection. + +Data collection can later be re-enabled by deleting the flag or setting it to false, or by using the `telemetry:enable` command. ::: note If you have any questions or concerns regarding data collection, please contact us at the following email address [privacy@strapi.io](mailto:privacy@strapi.io). diff --git a/docs/developer-docs/latest/plugins/graphql.md b/docs/developer-docs/latest/plugins/graphql.md index 5e36e079e1..43cd9b04d9 100644 --- a/docs/developer-docs/latest/plugins/graphql.md +++ b/docs/developer-docs/latest/plugins/graphql.md @@ -15,7 +15,7 @@ The [GraphQL API reference](/developer-docs/latest/developer-resources/database- ## Usage -To get started with GraphQL in your app, please install the plugin first. To do that, open your terminal and run the following command: +To get started with GraphQL in your application, please install the plugin first. To do that, open your terminal and run the following command: @@ -33,44 +33,21 @@ yarn strapi install graphql -Then, start your app and open your browser at [http://localhost:1337/graphql](http://localhost:1337/graphql). You should see the interface (**GraphQL Playground**) that will help you to write GraphQL query to explore your data. +Then, start your app and open your browser at [http://localhost:1337/graphql](http://localhost:1337/graphql). You should now be able to access the **GraphQL Playground** that will help you to write your GraphQL queries and mutations. -## Configurations - -By default, the [Shadow CRUD](#shadow-crud) feature is enabled and the GraphQL path is set to `/graphql`. The Playground is enabled by default for both the development and staging environments, however it is disabled in production. By changing the config option `playgroundAlways` to true, you can enable it. - - +:::note +The GraphQL Playground is enabled by default for both the development and staging environments, but disabled in production environments. Set the `playgroundAlways` configuration option to `true` to also enable the GraphQL Playground in production environments (see [plugins configuration documentation](/developer-docs/latest/setup-deployment-guides/configurations/optional/plugins.md#graphql-configuration)). +::: -Security limits on maximum number of items in your response by default is limited to 100, however you can change this on the following config option `amountLimit`. This should only be changed after careful consideration of the drawbacks of a large query which can cause what would basically be a DDoS (Distributed Denial of Service). And may cause abnormal load on your Strapi server, as well as your database server. +## Configuration -You can also setup any [Apollo Server options](https://www.apollographql.com/docs/apollo-server/api/apollo-server/#apolloserver) with the `apolloServer` option. For example, you can enable the tracing feature, which is supported by the playground to track the response time of each part of your query. To enable this feature just change/add the `"tracing": true` option in the GraphQL settings file. You can read more about the tracing feature from Apollo [here](https://www.apollographql.com/docs/apollo-server/federation/metrics/). +Plugins configuration are defined in the `config/plugins.js` file. This configuration file can include a `graphql.config` object to define specific configurations for the GraphQL plugin (see [plugins configuration documentation](/developer-docs/latest/setup-deployment-guides/configurations/optional/plugins.md#graphql-configuration)). -You can edit these [configurations](/developer-docs/latest/setup-deployment-guides/configurations/optional/plugins.md) by creating the following file: +[Apollo Server](https://www.apollographql.com/docs/apollo-server/api/apollo-server/#apolloserver) options can be set with the `graphql.config.apolloServer` [configuration object](/developer-docs/latest/setup-deployment-guides/configurations/optional/plugins.md#graphql-configuration). Apollo Server options can be used for instance to enable the [tracing feature](https://www.apollographql.com/docs/federation/metrics/), which is supported by the GraphQL playground to track the response time of each part of your query. -:::caution -Please note the setting for GraphQL `tracing` as changed and has been moved to `apolloServer.tracing` +::: caution +The maximum number of items returned by the response is limited to 100 by default. This value can be changed using the `amountLimit` configuration option, but should only be changed after careful consideration: a large query can cause a DDoS (Distributed Denial of Service) and may cause abnormal load on your Strapi server, as well as your database server. ::: - -```js -// path: ./config/plugins.js - -module.exports = { - // - graphql: { - config: { - endpoint: '/graphql', - shadowCRUD: true, - playgroundAlways: false, - depthLimit: 7, - amountLimit: 100, - apolloServer: { - tracing: false, - }, - }, - }, -}; -``` - ## Shadow CRUD To simplify and automate the build of the GraphQL schema, we introduced the Shadow CRUD feature. It automatically generates the type definitions, queries, mutations and resolvers based on your models. diff --git a/docs/developer-docs/latest/setup-deployment-guides/configurations/optional/plugins.md b/docs/developer-docs/latest/setup-deployment-guides/configurations/optional/plugins.md index c314ee20f0..166711caed 100644 --- a/docs/developer-docs/latest/setup-deployment-guides/configurations/optional/plugins.md +++ b/docs/developer-docs/latest/setup-deployment-guides/configurations/optional/plugins.md @@ -44,12 +44,19 @@ If no specific configuration is required, a plugin can also be declared with the ## GraphQL configuration -The [GraphQL plugin](/developer-docs/latest/plugins/graphql.md) has the following specific configuration options: +The [GraphQL plugin](/developer-docs/latest/plugins/graphql.md) has the following specific configuration options that should be declared in a `graphql.config` object. All parameters are optional: -| Parameter | Description | Type | -| -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------- | -| `defaultLimit` | Default value for [the `pagination[limit]` parameter](/developer-docs/latest/developer-resources/database-apis-reference/graphql-api.md#pagination-by-offset) used in API calls | `Integer` | -| `maxLimit` | Maximum value for [the `pagination[limit]` parameter](/developer-docs/latest/developer-resources/database-apis-reference/graphql-api.md#pagination-by-offset) used in API calls | `Integer` | +| Parameter | Description | Type | Default | +| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- | ------- | +| `apolloServer` | Additional configuration for [`ApolloServer`](https://www.apollographql.com/docs/apollo-server/api/apollo-server/#apolloserver). | Object | `{}` | +| `artifacts` | Object containing filepaths, defining where to store generated articats. Can include the following properties: Only works if `generateArtifacts` is set to `true`. | Object | | +| `defaultLimit` | Default value for [the `pagination[limit]` parameter](/developer-docs/latest/developer-resources/database-apis-reference/graphql-api.md#pagination-by-offset) used in API calls | Integer | +| `depthLimit` | Limits the [complexity of GraphQL queries](https://www.npmjs.com/package/graphql-depth-limit). | Integer | `10` | +| `generateArtifacts`| Whether Strapi should automatically generate and output a GraphQL schema file and corresponding TypeScript definitions.

The file system location can be configured through `artifacts`. | Boolean | `false` | +| `maxLimit` | Maximum value for [the `pagination[limit]` parameter](/developer-docs/latest/developer-resources/database-apis-reference/graphql-api.md#pagination-by-offset) used in API calls | Integer | `-1` | +| `playgroundAlways` | Whether the playground should be publicly exposed.

Enabled by default in if `NODE_ENV` is set to `development`. | Boolean | `false` | +| `shadowCRUD` | Whether type definitions for queries, mutations and resolvers based on models should be created automatically (see [Shadow CRUD documentation](/developer-docs/latest/plugins/graphql.md#shadow-crud)). | Boolean | `true` | +| `subscriptions` | Enable GraphQL subscriptions. | Boolean | `false` | ```js // path: ./config/plugins.js @@ -58,8 +65,12 @@ module.exports = () => ({ graphql: { enabled: true, config: { + playgroundAlways: false, defaultLimit: 10, maxLimit: 20 + apolloServer: { + tracing: true, + }, } } }) diff --git a/docs/package.json b/docs/package.json index bfbad4338d..2fd21cfa90 100644 --- a/docs/package.json +++ b/docs/package.json @@ -1,6 +1,6 @@ { "name": "strapi-docs", - "version": "4.2.0", + "version": "4.2.1", "main": "index.js", "scripts": { "dev": "yarn create:config-file && vuepress dev",