Static social preview
A route needs a fixed social preview image.
Next.js 16+ · Directive
twitter-image
Use the twitter-image file convention to define the Twitter card image for an App Router route segment. Provide a supported static image or generate one through a dedicated route.
How it works
The twitter-image file convention assigns a social-sharing image to a route segment. Add a supported image file directly within that segment, and Next.js evaluates the file and generates the appropriate document-head tags; dynamic images can instead be produced by a twitter-image route.
Syntax
twitter-image.(jpg|jpeg|png|gif)Key points
- The convention associates a social-sharing image with a specific App Router route segment.
- Choose between supplying a static image asset and generating the image with code.
- No manual metadata tags are needed when the convention is used.
- Supported static formats are JPEG, JPG, PNG, and GIF.
- Use a special route when the image must be generated programmatically.
Common mistakes
- Keep the file at or below 5 MB; exceeding the limit causes the build to fail.
- Use one of the documented extensions and place the file in the intended route segment.
Example: Static Twitter image for a route segment
// app/blog/twitter-image.png
// Place a supported image file in the route segment.
// app/blog/page.tsx
export default function BlogPage() {
return <main>Blog</main>
}Place the image file in the segment whose pages should use it; Next.js discovers it and emits the corresponding Twitter metadata automatically.
When to use it
Dynamic social preview
A preview must reflect route-specific content.
Convention-based metadata
A site wants automatic Twitter metadata without hand-authored head tags.
Interview questions
QHow do you configure a static Twitter image in the App Router?
Add twitter-image.jpg, .jpeg, .png, or .gif to a route segment. Next.js detects it and adds the appropriate Twitter image metadata to the document head.
Follow-up: How would you make the image vary by route data? Create a twitter-image route that default-exports an image-generating function, typically returning an ImageResponse.
QWhat is the scope and benefit of the twitter-image convention?
The convention is route-segment scoped, so the file applies to that segment and its descendants according to the App Router hierarchy. Next.js handles the metadata generation rather than requiring manual head tags.
Follow-up: What alternative exists when a static asset is insufficient? Generate the image with code in a twitter-image route.
QWhat file-size constraint must be observed?
A Twitter image file must not exceed 5 MB. If it is larger, the build fails, so asset size should be checked before deployment.
Follow-up: How does the Open Graph limit differ? The page documents an 8 MB maximum for opengraph-image, which is separate from Twitter's 5 MB limit.
Related
opengraph-imageImageResponsegenerateMetadataMetadata Files