---
title: "Server-Side Rendering"
enterprise: true
framework: react
version: "14.1.0"
---

# Server-Side Rendering

The `ag-charts-server-side` package renders AG Charts to PNG and JPEG image buffers in Node.js, without the need for a browser. Use it to generate chart images for email reports, PDF documents, or API endpoints.

[Video](https://www.ag-grid.com/charts/_astro/server-side-rendering-demo.BidXoyIH.mp4)

> **Tip**
>
> Try server-side rendering with zero setup in [GitHub Codespaces]([object Object]).  
> Note that in Codespaces, the server URL will be a forwarded port URL (e.g. `https://<name>-3000.<domain>`) rather than `localhost:3000`.

## Installation

Install the `ag-charts-server-side` package:

#### NPM

```bash
npm install ag-charts-server-side
```

#### Yarn

```bash
yarn add ag-charts-server-side
```

Node.js 20.0.0 or later is required to run `ag-charts-server-side`.

### Module Registration

Register chart modules before rendering any charts. This is typically done once at application startup.

```js
import { AllEnterpriseModule, LicenseManager, ModuleRegistry } from 'ag-charts-enterprise';

LicenseManager.setLicenseKey('your-licence-key');
ModuleRegistry.registerModules([AllEnterpriseModule]);
```

See [Module Registry](https://www.ag-grid.com/charts/react/module-registry/) for details on selecting specific modules to reduce bundle size.

### Licensing

Server-side rendering requires an AG Charts Enterprise licence.

See [Upgrading to Enterprise](https://www.ag-grid.com/charts/react/licensing/) for licence options, and [Installing Your Licence Key](https://www.ag-grid.com/charts/react/license-install/) for setup instructions.

## Rendering

`AgChartsServerSide` is the static entry point for all server-side rendering.

It exposes `render()`, `renderGauge()`, and `renderFinancialChart()` methods, each returning a `Promise<Uint8Array>` containing the image data.

Because there is no DOM container to derive dimensions from, `width` and `height` are required top-level options on every render call.

The `options` property accepts all [AG Charts options](https://www.ag-grid.com/charts/options/), excluding `container`, `width`, and `height`.

Multiple render calls can safely be issued concurrently. The package serialises rendering internally to prevent global state conflicts.

### Basic Rendering

Use `render()` to render all standard chart types. This method is the equivalent of the browser-based `AgCharts.create()`.

```js
import * as fs from 'fs';

import { AllEnterpriseModule, ModuleRegistry } from 'ag-charts-enterprise';
import { AgChartsServerSide } from 'ag-charts-server-side';

ModuleRegistry.registerModules([AllEnterpriseModule]);

const buffer = await AgChartsServerSide.render({
    options: {
        data: [
            { category: 'Q1', value: 10 },
            { category: 'Q2', value: 25 },
            { category: 'Q3', value: 15 },
            { category: 'Q4', value: 30 },
        ],
        series: [{ type: 'bar', xKey: 'category', yKey: 'value' }],
    },
    width: 400,
    height: 300,
});

fs.writeFileSync('chart.png', buffer);
```

In this configuration:

- `options` contains the chart configuration — the same structure used in browser rendering.
- `width` and `height` set the output image dimensions in pixels.
- The default output format is PNG. See [Image Format](#image-format) for JPEG output.

### Rendering Gauges

Use `renderGauge()` to render [Radial](https://www.ag-grid.com/charts/react/radial-gauge/) and [Linear Gauges](https://www.ag-grid.com/charts/react/linear-gauge/).

```js
const buffer = await AgChartsServerSide.renderGauge({
    options: {
        type: 'radial-gauge',
        value: 75,
        scale: { min: 0, max: 100 },
    },
    width: 300,
    height: 300,
});
```

See [Radial Gauge](https://www.ag-grid.com/charts/react/radial-gauge/) and [Linear Gauge](https://www.ag-grid.com/charts/react/linear-gauge/) for the full range of Gauge options.

### Rendering Financial Charts

Use `renderFinancialChart()` to render [Financial Charts](https://www.ag-grid.com/charts/react/financial-charts/).

```js
const buffer = await AgChartsServerSide.renderFinancialChart({
    options: {
        data: financialData,
    },
    width: 800,
    height: 500,
});
```

See [Financial Charts](https://www.ag-grid.com/charts/react/financial-charts-configuration/#reference-AgFinancialChartOptions) for the full range of Financial Chart options.

### Timeout

By default, each render call times out after 30 seconds. Use the `timeout` option to adjust this limit.

```js
const buffer = await AgChartsServerSide.render({
    // ... chart options ...
    timeout: 60000, // 60 seconds
});
```

Increase the timeout for charts with large datasets or complex animations that need more time to settle. Decrease it in request handlers where fast failure is preferable to a long wait.

## Image Format

### High-DPI Output

Set `pixelRatio` to produce higher-resolution images suitable for Retina displays, print-quality PDFs, or any context where sharp text and crisp lines are important.

```js
const buffer = await AgChartsServerSide.render({
    // ... chart options ...
    width: 200,
    height: 150,
    pixelRatio: 2,
});
```

The actual pixel dimensions of the output are `width * pixelRatio` by `height * pixelRatio`.

### JPEG Output

The default output format is PNG. Set `format: 'jpeg'` to produce JPEG images instead.

Use the `quality` option (0–100) to control JPEG compression. Lower values produce smaller files with more compression artefacts. This option has no effect on PNG output.

```js
const buffer = await AgChartsServerSide.render({
    // ... chart options ...
    format: 'jpeg',
    quality: 85,
});
```

## Loading Custom Fonts

The `ag-charts-server-side` does not fetch Google Fonts or other remote font resources automatically. Use the `loadFonts()` method to load custom fonts from local font files.

Font variants are detected automatically from the font file metadata. Register each variant under the same family name:

```js
AgChartsServerSide.loadFonts([
    { family: 'CustomFont', path: '/path/to/CustomFont-Regular.ttf' },
    { family: 'CustomFont', path: '/path/to/CustomFont-Bold.ttf' },
    { family: 'CustomFont', path: '/path/to/CustomFont-Italic.ttf' },
]);
```

Special characters, extended Unicode, and non-Latin scripts may not render correctly unless their fonts are explicitly loaded.

## Examples

There are many use cases for server-side rendering. We recommend you take a look at those in our [GitHub Codespaces]([object Object]).

Additionally, here are a few code examples to get you started.

### Express.js Endpoint

Serve chart images dynamically from an HTTP endpoint:

```js
import express from 'express';

import { AllEnterpriseModule, ModuleRegistry } from 'ag-charts-enterprise';
import { AgChartsServerSide } from 'ag-charts-server-side';

ModuleRegistry.registerModules([AllEnterpriseModule]);

const app = express();

app.get('/chart.png', async (req, res) => {
    const buffer = await AgChartsServerSide.render({
        options: {
            data: [
                { category: 'Q1', value: 10 },
                { category: 'Q2', value: 25 },
                { category: 'Q3', value: 15 },
                { category: 'Q4', value: 30 },
            ],
            series: [{ type: 'bar', xKey: 'category', yKey: 'value' }],
        },
        width: 800,
        height: 600,
    });

    res.set('Content-Type', 'image/png');
    res.send(buffer);
});

app.listen(3000);
```

### Saving to File

Generate chart images during build steps or scheduled jobs:

```js
import * as fs from 'fs';

import { AllEnterpriseModule, ModuleRegistry } from 'ag-charts-enterprise';
import { AgChartsServerSide } from 'ag-charts-server-side';

ModuleRegistry.registerModules([AllEnterpriseModule]);

const charts = [
    { name: 'sales', data: salesData, series: [{ type: 'bar', xKey: 'month', yKey: 'revenue' }] },
    { name: 'users', data: userData, series: [{ type: 'line', xKey: 'month', yKey: 'count' }] },
];

for (const chart of charts) {
    const buffer = await AgChartsServerSide.render({
        options: { data: chart.data, series: chart.series },
        width: 800,
        height: 400,
    });
    fs.writeFileSync(`output/${chart.name}.png`, buffer);
}
```

## API Reference

#### AgChartsServerSide

| Property | Type | Default | Description |
| --- | --- | --- | --- |
| render | Function |  | Renders a standard chart to an image buffer. |
| renderGauge | Function |  | Renders a gauge chart to an image buffer. |
| renderFinancialChart | Function |  | Renders a financial chart to an image buffer. |
| loadFonts | Function |  | Registers custom fonts for rendering. |

#### AgBaseRenderOptions

| Property | Type | Default | Description |
| --- | --- | --- | --- |
| width | number |  | Output image width in pixels. |
| height | number |  | Output image height in pixels. |
| format | 'png' \| 'jpeg' |  | Output image format. Default: `'png'`. |
| pixelRatio | number |  | Pixel density multiplier for high-DPI output. Default: `1`. |
| quality | number |  | JPEG quality 0–100 (only applies when `format` is `'jpeg'`). |
| timeout | number |  | Render timeout in milliseconds. Default: `30000`. |

#### AgFontDefinition

| Property | Type | Default | Description |
| --- | --- | --- | --- |
| family | string |  | Font family name used in chart options. |
| path | string |  | File path to the font file (`.ttf`, `.otf`, etc.). Font variants (weight, style) are detected automatically from the font file metadata. |