{/* flexDirection: column */}
{/* flexWrap: wrap */}
```
### Positioning
```jsx
```
### Typography
```jsx
```
### OG Image with Logo
```jsx
```
### Two Column Layout
```jsx
)
```
## Light/Dark Mode Build Script
Create diagrams in both light and dark variants automatically:
### `scripts/generate-diagrams.ts`
```typescript
import satori from 'satori'
import { Resvg } from '@resvg/resvg-js'
import { readFileSync, writeFileSync, mkdirSync } from 'fs'
import { join } from 'path'
// load font once
const interRegular = readFileSync('./fonts/Inter-Regular.ttf')
const interBold = readFileSync('./fonts/Inter-Bold.ttf')
const fonts = [
{ name: 'Inter', data: interRegular, weight: 400, style: 'normal' as const },
{ name: 'Inter', data: interBold, weight: 700, style: 'normal' as const },
]
// theme definitions
const themes = {
light: {
bg: 'white',
bgSecondary: '#f3f4f6',
text: '#111827',
textSecondary: '#6b7280',
accent: '#3b82f6',
border: '#e5e7eb',
},
dark: {
bg: '#111827',
bgSecondary: '#1f2937',
text: '#f9fafb',
textSecondary: '#9ca3af',
accent: '#60a5fa',
border: '#374151',
},
}
type Theme = typeof themes.light
// your diagram component - receives theme colors
function createDiagram(theme: Theme) {
return (
)
}
interface GenerateOptions {
name: string
width?: number
height?: number
outputDir?: string
formats?: ('svg' | 'png')[]
}
async function generateDiagram(options: GenerateOptions) {
const {
name,
width = 1200,
height = 630,
outputDir = './output',
formats = ['svg', 'png'],
} = options
mkdirSync(outputDir, { recursive: true })
for (const [themeName, theme] of Object.entries(themes)) {
const element = createDiagram(theme)
// generate SVG
const svg = await satori(element, { width, height, fonts })
if (formats.includes('svg')) {
const svgPath = join(outputDir, `${name}-${themeName}.svg`)
writeFileSync(svgPath, svg)
console.log(`Created: ${svgPath}`)
}
if (formats.includes('png')) {
// convert to PNG at 2x resolution for retina
const resvg = new Resvg(svg, {
fitTo: { mode: 'width', value: width * 2 },
})
const pngData = resvg.render()
const pngPath = join(outputDir, `${name}-${themeName}.png`)
writeFileSync(pngPath, pngData.asPng())
console.log(`Created: ${pngPath}`)
}
}
}
// generate all diagrams
async function main() {
await generateDiagram({ name: 'og-image' })
await generateDiagram({ name: 'twitter-card', width: 1200, height: 600 })
await generateDiagram({ name: 'square', width: 1080, height: 1080 })
}
main().catch(console.error)
```
### `package.json` Scripts
```json
{
"scripts": {
"generate:diagrams": "tsx scripts/generate-diagrams.ts",
"generate:watch": "tsx watch scripts/generate-diagrams.ts"
},
"dependencies": {
"satori": "^0.10.0",
"@resvg/resvg-js": "^2.6.0"
},
"devDependencies": {
"tsx": "^4.0.0",
"@types/node": "^20.0.0"
}
}
```
### Usage
```bash
# generate all diagrams
npm run generate:diagrams
# output:
# output/og-image-light.svg
# output/og-image-light.png
# output/og-image-dark.svg
# output/og-image-dark.png
# ...
```
## Converting to PNG
For high-quality PNG output, use `@resvg/resvg-js`:
```typescript
import { Resvg } from '@resvg/resvg-js'
const svg = await satori(element, options)
// 2x resolution for retina displays
const resvg = new Resvg(svg, {
fitTo: { mode: 'width', value: 2400 }, // 2x of 1200
})
const pngBuffer = resvg.render().asPng()
```
## Standard Dimensions
| Platform | Size | Aspect Ratio |
|----------|------|--------------|
| Open Graph | 1200×630 | 1.91:1 |
| Twitter Card | 1200×600 | 2:1 |
| LinkedIn | 1200×627 | 1.91:1 |
| Instagram Square | 1080×1080 | 1:1 |
| Instagram Story | 1080×1920 | 9:16 |
## Limitations & Gotchas
### Not Supported
- **CSS Grid** - use Flexbox only
- **z-index** - elements render in document order
- **calc()** - no CSS calculations
- **Animations** - static output only
- **React hooks** - no useState, useEffect, etc.
- **WOFF2 fonts** - use TTF, OTF, or WOFF
- **RTL languages** - Arabic, Hebrew not supported
- **3D transforms** - 2D only (rotate, scale, translate, skew)
### Important Notes
- **Fonts required**: Always provide at least one font
- **Default display is flex**: All elements default to `display: flex`
- **Default flexWrap is wrap**: Unlike CSS default
- **Images need dimensions**: Always specify width/height on `![]()
`
- **Use base64 for images**: Avoids network requests during render
- **No currentColor**: Except for the `color` property itself
- **Never pass `undefined` to style props**: Causes `trim()` crash. Build style objects conditionally instead.
- **Use flexbox, avoid hardcoded dimensions**: Let content determine size with padding. Use `flex-1`, `w-full`, `items-stretch` etc. Don't manually wrap text with multiple spans. Exception: icons need fixed sizes.
### Font Loading
```typescript
// good: load font once, reuse
const fontData = await fetch(fontUrl).then(r => r.arrayBuffer())
const fonts = [{ name: 'Inter', data: fontData, weight: 400, style: 'normal' }]
// use same fonts array for multiple renders
const svg1 = await satori(element1, { fonts, width: 1200, height: 630 })
const svg2 = await satori(element2, { fonts, width: 1200, height: 630 })
```
**Recommended: Use fontsource packages** for reliable local fonts (avoids network issues):
```bash
bun add @fontsource/inter @fontsource/jetbrains-mono
```
```typescript
import { readFileSync } from 'fs';
import { join } from 'path';
const FONT_DIR = join(__dirname, 'node_modules/@fontsource/inter/files');
const fonts = [{
name: 'Inter',
data: readFileSync(join(FONT_DIR, 'inter-latin-400-normal.woff')), // woff only, not woff2
weight: 400 as const,
style: 'normal' as const,
}];
```
### Image Handling
```typescript
// convert image to base64 for embedding
const imageBuffer = await fetch(imageUrl).then(r => r.arrayBuffer())
const base64 = `data:image/png;base64,${Buffer.from(imageBuffer).toString('base64')}`
// use in component
```
## Custom Tailwind Config
```typescript
await satori(element, {
width: 1200,
height: 630,
fonts,
tailwindConfig: {
theme: {
extend: {
colors: {
brand: '#ff6b00',
},
fontFamily: {
display: ['Custom Font'],
},
},
},
},
})
```
## Debug Mode
Enable bounding boxes to debug layout issues:
```typescript
await satori(element, {
width: 1200,
height: 630,
fonts,
debug: true, // shows element boundaries
})
```
## Resources
- [Satori GitHub](https://github.com/vercel/satori)
- [Vercel OG Image Generation](https://vercel.com/docs/functions/og-image-generation)
- [Satori Playground](https://og-playground.vercel.app/)
Positioned
Corner
Large bold text
Small caps
``` ### Colors & Backgrounds ```jsx // solid colorsBlue background
// gradients (use style for complex gradients)
Gradient
```
### Text Gradients
```jsx
Gradient Text
```
### Shadows
```jsx
Card with shadow
```
### Transforms (2D Only)
```jsx
Rotated
Scaled
Moved
```
## Common Patterns
### Centered Card Layout
```jsx
Card Title
Card description goes here
{/* header */}
Brand
{/* main content */}
{/* footer */}
```
### Background Pattern (Dots)
```jsx
Your Dynamic Title Here
example.com
@username
Content over pattern
{/* left column */}
{/* right column */}
```
### Component Composition
```jsx
const Badge = ({ children, color }) => (
{children}
)
const Card = ({ title, tags }) => (
Title
Description text
{title}
{tags.map(tag => {tag} )}
S
My Diagram
Dynamic Content
Generated with Satori in light and dark mode
example.com
Generated at {new Date().toISOString().split('T')[0]}