Prerender chart API endpoints for Cloudflare compatibility and document edge runtime limitations

Author: techniq

docs/src/content/guides/ssr-images.md

@@ -187,10 +187,10 @@ These examples are rendered live from the API endpoints in this project.
 ```
 
 ```html
-<img src="/api/charts/line?background=white" />
+<img src="/api/charts/line" />
 ```
 
-![Line chart](/api/charts/line?background=white)
+![Line chart](/api/charts/line)
 
 ### Bar chart
 
@@ -215,10 +215,10 @@ These examples are rendered live from the API endpoints in this project.
 ```
 
 ```html
-<img src="/api/charts/bar?background=white" />
+<img src="/api/charts/bar" />
 ```
 
-![Bar chart](/api/charts/bar?background=white)
+![Bar chart](/api/charts/bar)
 
 ### Area chart (multi-series)
 
@@ -245,10 +245,10 @@ These examples are rendered live from the API endpoints in this project.
 ```
 
 ```html
-<img src="/api/charts/area?background=white" />
+<img src="/api/charts/area" />
 ```
 
-![Area chart](/api/charts/area?background=white)
+![Area chart](/api/charts/area)
 
 ### Scatter chart
 
@@ -271,10 +271,10 @@ These examples are rendered live from the API endpoints in this project.
 ```
 
 ```html
-<img src="/api/charts/scatter?background=white" />
+<img src="/api/charts/scatter" />
 ```
 
-![Scatter chart](/api/charts/scatter?background=white)
+![Scatter chart](/api/charts/scatter)
 
 ## Supported components
 
@@ -334,6 +334,23 @@ const buffer = renderChart(MyChart, {
 });
 ```
 
+### Cloudflare and edge runtimes
+
+Server-side chart rendering requires a **native Node.js canvas library** such as `@napi-rs/canvas`, `node-canvas`, or `skia-canvas`. These are native addons that do not run on edge runtimes like Cloudflare Workers.
+
+If you deploy to Cloudflare Pages (or similar edge platforms), **prerender your chart endpoints** so the images are generated at build time:
+
+```ts
+// +server.ts
+export const prerender = true;
+
+export const GET: RequestHandler = async ({ url }) => {
+	return renderChartResponse({ component: MyChart, props: { data }, url });
+};
+```
+
+Prerendered endpoints become static files served directly from the CDN — no server-side canvas library needed at runtime. Note that query parameters (like `?width=1200`) are not available for prerendered routes, so bake any defaults into the endpoint code.
+
 ### Inline styles only
 
 Since there is no DOM or CSS engine on the server, use inline style props (`fill`, `stroke`, `strokeWidth`, etc.) instead of CSS classes or Tailwind utilities.

docs/src/routes/api/charts/area/+server.ts

@@ -2,6 +2,8 @@ import { renderChartResponse } from '../renderChartEndpoint.js';
 import type { RequestHandler } from './$types';
 import AreaChart from './AreaChart.svelte';
 
+export const prerender = true;
+
 const data = Array.from({ length: 50 }, (_, i) => ({
 	date: i,
 	value: 50 + 30 * Math.sin(i / 5) + 10 * Math.cos(i / 3),

docs/src/routes/api/charts/bar/+server.ts

@@ -2,6 +2,8 @@ import { renderChartResponse } from '../renderChartEndpoint.js';
 import type { RequestHandler } from './$types';
 import BarChart from './BarChart.svelte';
 
+export const prerender = true;
+
 const data = [
 	{ category: 'A', value: 28 },
 	{ category: 'B', value: 55 },

docs/src/routes/api/charts/geo/+server.ts

@@ -5,6 +5,8 @@ import { renderChartResponse } from '../renderChartEndpoint.js';
 import type { RequestHandler } from './$types';
 import GeoChart from './GeoChart.svelte';
 
+export const prerender = true;
+
 let cachedStates: ReturnType<typeof feature> | null = null;
 
 async function getStates(fetchFn: typeof fetch) {

docs/src/routes/api/charts/line/+server.ts

@@ -2,6 +2,8 @@ import { renderChartResponse } from '../renderChartEndpoint.js';
 import type { RequestHandler } from './$types';
 import LineChart from './LineChart.svelte';
 
+export const prerender = true;
+
 const data = Array.from({ length: 50 }, (_, i) => ({
 	date: i,
 	value: 50 + 30 * Math.sin(i / 5) + 10 * Math.cos(i / 3)

docs/src/routes/api/charts/renderChartEndpoint.ts

@@ -25,7 +25,7 @@ export function renderChartResponse({
 	const width = Number(url.searchParams.get('width') ?? 800);
 	const height = Number(url.searchParams.get('height') ?? 400);
 	const format = url.searchParams.get('format') === 'jpeg' ? 'jpeg' : 'png';
-	const background = url.searchParams.get('background') ?? undefined;
+	const background = url.searchParams.get('background') ?? 'white';
 
 	const buffer = renderChart(component, {
 		width,

docs/src/routes/api/charts/scatter/+server.ts

@@ -2,6 +2,8 @@ import { renderChartResponse } from '../renderChartEndpoint.js';
 import type { RequestHandler } from './$types';
 import ScatterChart from './ScatterChart.svelte';
 
+export const prerender = true;
+
 // Generate clustered scatter data
 const random = (seed: number) => {
 	const x = Math.sin(seed) * 10000;