You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: docusaurus/docs/dev-docs/configurations/plugins.md
+1-68Lines changed: 1 addition & 68 deletions
Original file line number
Diff line number
Diff line change
@@ -25,7 +25,7 @@ Plugin configurations are stored in `/config/plugins.js|ts` (see [project struct
25
25
|`resolve`<br/> _Optional, only required for local plugins_| Path to the plugin's folder | String |
26
26
27
27
:::note
28
-
Some features of Strapi are provided by plugins and the following plugins can also have specific configuration options: [GraphQL](#graphql)and [Upload](#upload).
28
+
Some features of Strapi are provided by plugins and the following plugins can also have specific configuration options: the [GraphQL](/dev-docs/plugins/graphql#code-based-configuration) plugin and the [Upload](/user-docs/features/media-library#available-options) package which powers the Media Library.
29
29
:::
30
30
31
31
**Basic example custom configuration for plugins:**
@@ -91,70 +91,3 @@ export default ({ env }) => ({
91
91
:::tip
92
92
If no specific configuration is required, a plugin can also be declared with the shorthand syntax `'plugin-name': true`.
93
93
:::
94
-
95
-
## GraphQL configuration {#graphql}
96
-
97
-
The [GraphQL plugin](/dev-docs/plugins/graphql) has the following specific configuration options that should be declared in a `graphql.config` object within the `config/plugins` file. All parameters are optional:
|`apolloServer`| Additional configuration for [`ApolloServer`](https://www.apollographql.com/docs/apollo-server/api/apollo-server/#apolloserver). | Object |`{}`|
102
-
|`artifacts`| Object containing filepaths, defining where to store generated artifacts. Can include the following properties: <ul><li>`schema`: path to the generated GraphQL schema file</li><li>`typegen`: path to generated TypeScript types</li></ul>Only works if `generateArtifacts` is set to `true`. | Object | <ul><li>`schema: false`</li><li>`typegen: false`</li></ul> |
103
-
|`defaultLimit`| Default value for [the `pagination[limit]` parameter](/dev-docs/api/graphql#pagination-by-offset) used in API calls | Integer | 100 |
104
-
|`depthLimit`| Limits the [complexity of GraphQL queries](https://www.npmjs.com/package/graphql-depth-limit). | Integer |`10`|
105
-
|`endpoint`| The URL path on which the plugin is exposed | String |`/graphql`|
106
-
|`generateArtifacts`| Whether Strapi should automatically generate and output a GraphQL schema file and corresponding TypeScript definitions.<br/><br/>The file system location can be configured through `artifacts`. | Boolean |`false`|
107
-
|`maxLimit`| Maximum value for [the `pagination[limit]` parameter](/dev-docs/api/graphql#pagination-by-offset) used in API calls | Integer |`-1`|
108
-
|`playgroundAlways`| Whether the playground should be publicly exposed.<br/><br/>Enabled by default in if `NODE_ENV` is set to `development`. | Boolean |`false`|
109
-
|`shadowCRUD`| Whether type definitions for queries, mutations and resolvers based on models should be created automatically (see [Shadow CRUD documentation](/dev-docs/plugins/graphql#shadow-crud)). | Boolean |`true`|
110
-
|`v4ComptabilityMode`| Enables the retro-compatibility with the Strapi v4 format (see more details in the [breaking change entry](/dev-docs/migration/v4-to-v5/breaking-changes/graphql-api-updated)| Boolean |`false`|
By default Strapi create [REST endpoints](/dev-docs/api/rest#endpoints) for each of your content-types. The GraphQL plugin adds a GraphQL endpoint to fetch and mutate your content. With the GraphQL plugin installed, you can use the Apollo Server-based GraphQL Playground to interactively build your queries and mutations and read documentation tailored to your content types.
22
+
By default Strapi create [REST endpoints](/dev-docs/api/rest#endpoints) for each of your content-types. The GraphQL plugin adds a GraphQL endpoint to fetch and mutate your content. With the GraphQL plugin installed, you can use the Apollo Server-based GraphQL Sandbox to interactively build your queries and mutations and read documentation tailored to your content types.
23
23
24
24
:::prerequisites Identity Card of the Plugin
25
25
<Iconname="navigation-arrow"/> **Location:** Usable via the admin panel. Configured through both admin panel and server code, with different sets of options.<br/>
Once installed, the GraphQL playground is accessible at the `/graphql` URL and can be used to interactively build your queries and mutations and read documentation tailored to your content-types.
60
+
Once installed, the GraphQL sandbox is accessible at the `/graphql` URL and can be used to interactively build your queries and mutations and read documentation tailored to your content-types.
61
61
62
-
Once the plugin is installed, the **GraphQL Playground** is accessible at the `/graphql` route (e.g., [localhost:1337/graphql](http://localhost:1337/graphql)) when your Strapi application server is running.
62
+
Once the plugin is installed, the **GraphQL Sandbox** is accessible at the `/graphql` route (e.g., [localhost:1337/graphql](http://localhost:1337/graphql)) when your Strapi application server is running.
63
63
64
64
## Configuration
65
65
@@ -73,29 +73,43 @@ The Strapi admin panel does not provide Strapi-specific settings for the GraphQL
73
73
74
74
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](/dev-docs/configurations/plugins#graphql)).
75
75
76
-
Apollo Server options can be set with the `graphql.config.apolloServer`[configuration object](/dev-docs/configurations/plugins#graphql). 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. From `Apollo Server` version 3.9 default cache option is `cache: 'bounded'`. You can change it in the `apolloServer` configuration (for details, see [Apollo Server Docs](https://www.apollographql.com/docs/apollo-server/performance/cache-backends/)).
76
+
#### Available options
77
+
78
+
[Apollo Server](https://www.apollographql.com/docs/apollo-server/api/apollo-server/#apolloserver) options can be passed directly to Apollo with the `graphql.config.apolloServer`[configuration object](/dev-docs/configurations/plugins#graphql). 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 Sandbox to track the response time of each part of your query. The `Apollo Server` default cache option is `cache: 'bounded'`. You can change it in the `apolloServer` configuration. For more information visit [Apollo Server Docs](https://www.apollographql.com/docs/apollo-server/performance/cache-backends/).
79
+
80
+
The [GraphQL plugin](/dev-docs/plugins/graphql) has the following specific configuration options that should be declared in a `graphql.config` object within the `config/plugins` file. All parameters are optional:
81
+
82
+
| Option | Type | Description | Default Value | Notes |
|`shadowCRUD`| Boolean | Enables or disables automatic schema generation for content types. |`true`||
86
+
|`depthLimit`| Number | Limits the depth of GraphQL queries to prevent excessive nesting. |`10`| Use this to mitigate potential DoS attacks. |
87
+
|`amountLimit`| Number | Limits the maximum number of items returned in a single response. |`100`| Use cautiously to avoid performance issues. |
88
+
|`playgroundAlways`| Boolean |[Deprecated] Enables GraphQL Playground in all environments (deprecated). |`false`| Prefer using `landingPage` instead. |
89
+
|`landingPage`| Boolean \| Function | Enables or disables the landing page for GraphQL. Accepts a boolean or a function returning a boolean or an ApolloServerPlugin implementing `renderLandingPage`. ||`false` in production, `true` in other environments |
90
+
| `apolloServer` | Object | Passes configuration options directly to Apollo Server. | `{}` | Example: `{ tracing: true }`
77
91
78
92
:::caution
79
93
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.
80
94
:::
81
95
82
96
:::note
83
-
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](/dev-docs/configurations/plugins#graphql)).
97
+
The GraphQL Sandbox is enabled by default in all environments except production. Set the `landingPage` configuration option to `true` to also enable the GraphQL Sandbox in production environments.
84
98
:::
85
99
100
+
The following is an example custom configuration:
101
+
86
102
<TabsgroupId="js-ts">
87
103
88
104
<TabItemvalue="javascript"label="JavaScript">
89
105
90
106
```js title="/config/plugins.js"
91
-
92
107
module.exports= {
93
-
//
94
108
graphql: {
95
109
config: {
96
110
endpoint:'/graphql',
97
111
shadowCRUD:true,
98
-
playgroundAlways:false,
112
+
landingPage:false,// disable Sandbox everywhere
99
113
depthLimit:7,
100
114
amountLimit:100,
101
115
apolloServer: {
@@ -111,21 +125,131 @@ module.exports = {
111
125
<TabItemvalue="typescript"label="TypeScript">
112
126
113
127
```ts title="/config/plugins.ts"
114
-
115
-
exportdefault {
116
-
//
128
+
exportdefault () => ({
117
129
graphql: {
118
130
config: {
119
131
endpoint: '/graphql',
120
132
shadowCRUD: true,
121
-
playgroundAlways: false,
133
+
landingPage: false,// disable Sandbox everywhere
122
134
depthLimit: 7,
123
135
amountLimit: 100,
124
136
apolloServer: {
125
137
tracing: false,
126
138
},
127
139
},
128
140
},
141
+
})
142
+
```
143
+
144
+
</TabItem>
145
+
146
+
</Tabs>
147
+
148
+
149
+
#### Dynamically enable Apollo Sandbox
150
+
151
+
You can use a function to dynamically enable Apollo Sandbox depending on the environment:
152
+
153
+
<TabsgroupId="js-ts">
154
+
155
+
<TabItemvalue="javascript"label="JavaScript">
156
+
157
+
```javascript title="./config/plugins.js" {6-12}
158
+
module.exports= ({ env }) => {
159
+
graphql: {
160
+
config: {
161
+
endpoint:'/graphql',
162
+
shadowCRUD:true,
163
+
landingPage: (strapi) => {
164
+
if (env("NODE_ENV") !=="production") {
165
+
returntrue;
166
+
} else {
167
+
returnfalse;
168
+
}
169
+
},
170
+
},
171
+
},
172
+
};
173
+
```
174
+
175
+
</TabItem>
176
+
177
+
<TabItemvalue="typescript"label="TypeScript">
178
+
179
+
```ts title="./config/plugins.ts" {6-12}
180
+
exportdefault ({ env }) => {
181
+
graphql: {
182
+
config: {
183
+
endpoint: '/graphql',
184
+
shadowCRUD: true,
185
+
landingPage: (strapi) => {
186
+
if (env("NODE_ENV") !=="production") {
187
+
returntrue;
188
+
} else {
189
+
returnfalse;
190
+
}
191
+
},
192
+
},
193
+
},
194
+
};
195
+
```
196
+
</TabItem>
197
+
198
+
</Tabs>
199
+
200
+
#### CORS exceptions for Landing Page
201
+
202
+
If the landing page is enabled in production environments (which is not recommended), CORS headers for the Apollo Server landing page must be added manually.
203
+
204
+
To add them globally, you can merge the following into your middleware configuration:
GraphQL is a query language allowing users to use a broader panel of inputs than traditional REST APIs. GraphQL APIs are inherently prone to security risks, such as credential leakage and denial of service attacks, that can be reduced by taking appropriate precautions.
915
1039
916
-
######Disable introspection and playground in production
1040
+
### Disable introspection and Sandbox in production
917
1041
918
-
In production environments, disabling the GraphQL Playground and the introspection query is recommended.
919
-
If you haven't edited the [configuration file](/dev-docs/configurations/plugins#graphql), it is already disabled in production by default.
1042
+
In production environments, disabling the GraphQL Sandbox and the introspection query is strongly recommended.
1043
+
If you haven't edited the [configuration file](#availabel-options), it is already disabled in production by default.
920
1044
921
1045
###### Limit max depth and complexity
922
1046
@@ -973,14 +1097,14 @@ mutation {
973
1097
974
1098
</Request>
975
1099
976
-
Then on each request, send along an `Authorization` header in the form of `{ "Authorization": "Bearer YOUR_JWT_GOES_HERE" }`. This can be set in the HTTP Headers section of your GraphQL Playground.
1100
+
Then on each request, send along an `Authorization` header in the form of `{ "Authorization": "Bearer YOUR_JWT_GOES_HERE" }`. This can be set in the HTTP Headers section of your GraphQL Sandbox.
977
1101
978
1102
#### Usage with API tokens
979
1103
980
1104
To use API tokens for authentication, pass the token in the `Authorization` header using the format `Bearer your-api-token`.
981
1105
982
1106
:::note
983
-
Using API tokens in the the GraphQL playground requires adding the authorization header with your token in the `HTTP HEADERS` tab:
1107
+
Using API tokens in the the GraphQL Sandbox requires adding the authorization header with your token in the `HTTP HEADERS` tab:
0 commit comments