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
description: Learn about the security defaults and how to further harden your OG image endpoint.
4
+
---
5
+
6
+
Nuxt OG Image ships with secure defaults by default. Image dimensions are clamped, renders are time limited, internal network requests are blocked, and user provided props are sanitized. No configuration is needed for these protections.
7
+
8
+
If you want to lock things down further, the `security` config key gives you additional controls.
9
+
10
+
```ts [nuxt.config.ts]
11
+
exportdefaultdefineNuxtConfig({
12
+
ogImage: {
13
+
security: {
14
+
restrictRuntimeImagesToOrigin: true,
15
+
maxQueryParamSize: 2048,
16
+
}
17
+
}
18
+
})
19
+
```
20
+
21
+
## Prerender Your Images
22
+
23
+
The most effective security measure is to **prerender your OG images at build time** using [Zero Runtime mode](/docs/og-image/guides/zero-runtime). Prerendered images are served as static files with no runtime rendering code in your production build.
24
+
25
+
```ts [nuxt.config.ts]
26
+
exportdefaultdefineNuxtConfig({
27
+
ogImage: {
28
+
zeroRuntime: true
29
+
}
30
+
})
31
+
```
32
+
33
+
When zero runtime is enabled:
34
+
- No server-side rendering code is included in your production build
35
+
- Images are generated once at build time and served as static assets
36
+
- The `/_og` endpoint is not available at runtime
37
+
38
+
If your OG images don't need to change dynamically after deployment, this is the recommended approach.
39
+
40
+
For sites that need a mix of static and dynamic images, you can prerender specific routes while keeping runtime generation available for others. See the [Zero Runtime guide](/docs/og-image/guides/zero-runtime) for configuration details.
41
+
42
+
## Dimension and Render Limits
43
+
44
+
Every request has its `width` and `height` clamped to `maxDimension` (default `2048` pixels). The Takumi renderer's `devicePixelRatio` is capped to `maxDpr` (default `2`).
45
+
46
+
If a render exceeds `renderTimeout` (default `15000ms`), it is aborted and the server returns a `408` status.
47
+
48
+
These are all enabled by default. You only need to configure them if you want different limits.
49
+
50
+
```ts [nuxt.config.ts]
51
+
exportdefaultdefineNuxtConfig({
52
+
ogImage: {
53
+
security: {
54
+
maxDimension: 2048,
55
+
maxDpr: 2,
56
+
renderTimeout: 15000,
57
+
}
58
+
}
59
+
})
60
+
```
61
+
62
+
## Query String Size Limit
63
+
64
+
OG image options can be passed via query parameters. By default there is no size limit on the query string, but you can set `maxQueryParamSize` to reject requests with oversized query strings.
65
+
66
+
```ts [nuxt.config.ts]
67
+
exportdefaultdefineNuxtConfig({
68
+
ogImage: {
69
+
security: {
70
+
maxQueryParamSize: 2048, // characters
71
+
}
72
+
}
73
+
})
74
+
```
75
+
76
+
Requests exceeding this limit receive a `400` response.
77
+
78
+
If you find yourself passing large amounts of data through query parameters (titles, descriptions, full text), consider loading that data inside your OG image component instead. See the [Performance guide](/docs/og-image/guides/performance#reduce-url-size) for the recommended pattern.
79
+
80
+
## Restrict Runtime Images to Origin
81
+
82
+
When runtime image generation is enabled, anyone who knows the `/_og` endpoint pattern can request an image directly. The `restrictRuntimeImagesToOrigin` option limits runtime generation to requests whose `Host` header matches your configured site URL.
83
+
84
+
```ts [nuxt.config.ts]
85
+
exportdefaultdefineNuxtConfig({
86
+
ogImage: {
87
+
security: {
88
+
restrictRuntimeImagesToOrigin: true,
89
+
}
90
+
}
91
+
})
92
+
```
93
+
94
+
### How It Works
95
+
96
+
The module reads the `Host` header from each runtime request using h3's `getRequestHost` (with `X-Forwarded-Host` support for reverse proxies) and compares it against the host from your [Nuxt Site Config](https://nuxtseo.com/docs/site-config/getting-started/introduction)`url`. If the hosts don't match, the request receives a `403` response.
97
+
98
+
Because the `Host` header is mandatory in HTTP/1.1, this check works with all clients including social media crawlers. No `Origin` or `Referer` header is required.
99
+
100
+
### Allowing Additional Origins
101
+
102
+
To allow extra origins (e.g. a CDN or preview deployment), pass an array. Your site config origin is always included automatically.
This option is **disabled by default** to avoid surprises for sites behind non-standard proxy setups. If your reverse proxy forwards the correct `Host` or `X-Forwarded-Host` header, you can safely enable it.
115
+
116
+
::note
117
+
Prerendering and dev mode bypass the host check entirely.
118
+
::
119
+
120
+
## Debug Mode Warning
121
+
122
+
Enabling `ogImage.debug` in production exposes the `/_og/debug.json` endpoint. The module will log a warning at build time if debug is enabled outside of dev mode. Make sure to disable it before deploying.
logger.warn('`ogImage.debug` is enabled in production. This exposes the `/_og/debug.json` endpoint and should not be enabled in production. Disable it before deploying.')
0 commit comments