Skip to main content
If you’re upgrading from an older version of the Graphy SDK (v0.0.60 and below) that uses the legacy GraphConfig structure, this guide will help you migrate to the new config schema. This page documents the helper exported by @graphysdk/core:
import { migrateFromLegacyGraphConfig } from '@graphysdk/core';
This function is intended for migrating configs that you have already persisted (e.g. in a database). Rather than calling it on-the-fly every time you render a graph, we recommend running the migration once on your stored data and saving the result in the new format.

Key differences

AspectLegacy configNew config
Data structuredata (array of rows) + datasetConfig (columns)data with columns and rows
Chart typevisualisationConfig.typetype (top-level)
Chart optionsScattered across visualisationConfigGrouped in options
Text contenttitleDocument, caption, sourceLabel, sourceUrlGrouped in content
Number formattingnumberFormat (top-level)appearance.numberFormat
Annotationsannotationsannotations (flatter structure)

Inputs

The migration function accepts a set of props for the old version of GraphProvider:
config
LegacyGraphConfig
required
Your existing legacy config object.
theme
GraphTheme
Skip this if you were not previously passing a theme prop to GraphProvider.
customPalettes
CustomPaletteCatalog
Skip this if you were not previously passing a customPalettes prop to GraphProvider.

Outputs

The return value is a new set of GraphProvider props:
config
GraphConfig
required
The migrated config in the new format. Always present.
uiLocale
Locale
Only present if visualisationConfig.locale was set in your legacy config.
formattingLocale
Locale
Only present if visualisationConfig.locale was set in your legacy config.
fontList
FontList
Only present if fontList was set in your legacy config. The legacy config persisted this inside config. The new version expects it as a separate GraphProvider prop instead.

Full example

// New config: import type { GraphConfig } from '@graphysdk/core';
// Old config: import type { InternalGraphConfig } from '@graphysdk/core';

import { Graph, GraphProvider, graphyLightTheme, migrateFromLegacyGraphConfig } from '@graphysdk/core';

const legacyConfig = {
  data: [
    { month: 'Jan', sales: 1000 },
    { month: 'Feb', sales: 1200 }
  ],
  datasetConfig: {
    properties: [
      { key: 'month', label: 'Month' },
      { key: 'sales', label: 'Sales' }
    ]
  },
  visualisationConfig: {
    type: 'column'
  },
  // ... other legacy properties
};

// Optional: custom palettes
const myCustomPalettes = [
  {
    id: 'brand',
    name: 'Brand',
    colors: [
      { id: '1', hex: '#3b82f6', name: 'Blue' }
    ]
  }
];

// Optional: custom theme
const myTheme = { ...graphyLightTheme, values: { ...graphyLightTheme.values, brand: '#3b82f6' } };

// Migrate to new format
const {
  config: migratedConfig,
  uiLocale, // only present if visualisationConfig.locale was set in the legacy config
  formattingLocale, // only present if visualisationConfig.locale was set in the legacy config
  fontList, // only present if fontList was set in the legacy config
} = migrateFromLegacyGraphConfig({
  config: legacyConfig,
  customPalettes: myCustomPalettes,
  theme: myTheme,
});

// New version of the `GraphProvider` which accepts the new set of props returned by the migration function:
<GraphProvider config={migratedConfig} uiLocale={uiLocale} formattingLocale={formattingLocale} fontList={fontList}>
  <Graph />
</GraphProvider>

Property mapping reference

This table shows how legacy config properties map to the new structure:

Data

LegacyNew
data (array of rows)data.rows
datasetConfig.propertiesdata.columns
datasetConfig.properties[].keydata.columns[].key
datasetConfig.properties[].labeldata.columns[].label
datasetConfig.properties[].isHiddendata.columns[]._metadata.isHidden
datasetConfig.dateFormatdata._metadata.parsingLocale
datasetConfig.isDataHorizontaldata._metadata.isDataTransposed
datasetConfig.shouldAggregatedata._metadata.isAggregated

Chart type and options

LegacyNew
visualisationConfig.typetype
visualisationConfig.curveTypeoptions.isSmoothLine
visualisationConfig.lineThicknessoptions.lineThickness
visualisationConfig.showPointsoptions.showPoints
visualisationConfig.treatEmptyValuesoptions.missingValues
visualisationConfig.sortBarsoptions.sortBars
visualisationConfig.pointSizeoptions.pointSize
visualisationConfig.comboPlotTypeoptions.comboType
visualisationConfig.pieTotalPositionoptions.pieTotalPosition

Axes

LegacyNew
visualisationConfig.topAxisLabel .rightAxisLabel .bottomAxisLabel .leftAxisLabelaxes.x.label / axes.y.label
visualisationConfig.hideMainAxisaxes.x.isHidden / axes.y.isHidden
visualisationConfig.hideCrossAxisaxes.y.isHidden / axes.x.isHidden
visualisationConfig.useLogScaleaxes.y.scaleType / axes.x.scaleType
visualisationConfig.customYAxisStartFromaxes.y.min / axes.x.min
visualisationConfig.customYAxisEndAtaxes.y.max / axes.x.max
visualisationConfig.hasGridLinesaxes.showGridLines
visualisationConfig.comboPlotAxisCountaxes.hasDualYAxis

Content

LegacyNew
titleDocument (first node)content.title
titleDocument (remaining nodes)content.subtitle
captioncontent.caption
sourceLabelcontent.source.label
sourceUrlcontent.source.url
customAppearanceConfig.shouldHideTitlecontent.isTitleHidden
customAppearanceConfig.shouldHideSubtitlecontent.isSubtitleHidden
customAppearanceConfig.shouldHideCaptioncontent.isCaptionHidden
customAppearanceConfig.shouldHideSourceSectioncontent.isSourceHidden

Appearance

LegacyNew
customAppearanceConfig.themeappearance.palette / appearance.paletteId
customAppearanceConfig.seriesConfigappearance.seriesStyles
customAppearanceConfig.shouldTintBackgroundappearance.backgroundModifier
customAppearanceConfig.borderTypeappearance.border.style
customAppearanceConfig.borderColorappearance.border.color
customAppearanceConfig.borderStrokeappearance.border.width
customAppearanceConfig.hasRoundedCornersappearance.hasRoundedCorners
customAppearanceConfig.fontappearance.textStyle
customAppearanceConfig.textScaleappearance.textScale
customAppearanceConfig.highlightStyleappearance.highlightStyle
customAppearanceConfig.shouldHideLogoappearance.isLogoHidden
numberFormatappearance.numberFormat
customAppearanceConfig.disableTooltipsappearance.showTooltips (inverted)
customAppearanceConfig.disableAnimationappearance.animateTransitions (inverted)

Data labels and headline numbers

LegacyNew
visualisationConfig.showDataLabelsdataLabels.showDataLabels
visualisationConfig.showPercentageLabelsdataLabels.dataLabelFormat
visualisationConfig.showStackTotalsdataLabels.showStackTotals
visualisationConfig.showCategoryLabelsdataLabels.showCategoryLabels
visualisationConfig.headlineMetricheadlineNumbers.show
visualisationConfig.headlineMetricComparisonValueheadlineNumbers.compareWith
visualisationConfig.headlineMetricSizeheadlineNumbers.size

Reference lines

LegacyNew
visualisationConfig.customPowerUp (goal)referenceLines.goalLine
visualisationConfig.yGoalValuereferenceLines.goalLine.target
visualisationConfig.xGoalValuereferenceLines.goalLine.marker
visualisationConfig.presetPowerUp (trendline)referenceLines.trendline
visualisationConfig.trendLineTypereferenceLines.trendline
visualisationConfig.presetPowerUp (average)referenceLines.averageLine
visualisationConfig.averageLineSeriesKeyreferenceLines.averageLine.columnKey