Upgrading to Vanilla Components v1

Switching to Vanilla Components v1 is a straightforward process. It requires a bit of a fresh start, but all your work is portable.

The Basics

To avoid a large number of merge conflicts, Vanilla Components v1 requires configuring a new repository. This will not break any of your existing Embeddables. They should keep right on working as expected, as all of the Vanilla Component names/inputs/etc in v1 remain identical to the version you’re currently working with, which you had to clone from our repo (and which in this document we’ll call v0).

Here are the steps to take:

Build and push, and you’re now using the packaged version of Vanilla Components, which means you’re also using themes!

If you haven’t modified any Vanilla Components code

(other than constants.ts)

You’re pretty much in the clear, however if you have custom components you wrote yourself, you’ll want to bring them over to your new repository. This works the same as it did before: you can just add them to /src/components. Added major bonus: you can now use Embeddable theme values in your component code! See Using Themes for full details.

If you have modified any Vanilla Components code

This is where those overrides we mentioned before come in. The way Embeddable works, you can pick and choose what you bring in from Vanilla Components. It’s not an all-or-nothing deal. So you have two choices:

1. Override Vanilla Components

You can disable the import of any chart or control from the package by specifying it in an exclude array in your embeddable.config.ts like this:

export default defineConfig({
  plugins: [react],
  // don't import the default vanilla pie chart or pivot table
  componentLibraries: [{
    name: '@embeddable.com/vanilla-components',
    exclude: ['BarChart', 'DateRangePicker'],
  }],

With these components excluded, you can copy your components over to the new folder and they’ll work in Embeddable as expected. Note: these components will not be using themes … yet. You can adjust them to do so. See Using Themes for full details.

2. Rename Your Components

This allows you to retain every single packaged Vanilla chart and use your charts as well, but it comes with a serious complication.

Let’s say you heavily modified the Vanilla Components v0 pie chart, and for this example let’s say your company name is “CloseBrace” - you could rename your pie chart folder to CloseBracePieChart and rename PieChart.emb.ts to CloseBracePieChart.ts. Then update the name and label values inside CloseBracePieChart.emb.ts to CloseBracePieChart and CloseBrace Pie Chart respectively.

Copy all of that over from your original repo to the boilerplate repo, and now you have both the Vanilla Components default Pie Chart, and your modified pie chart.

There are two extremely important things to understand about this approach.

1. Any dashboards you built before this change will have no knowledge of your new components - if your component was named “BarChart,” your new one is “CloseBraceBarChart,” and your dashboard was built with “BarChart” … then it’s still going to use “BarChart” (from the Vanilla Components package). This likely means you will need to rebuild some or all of your dashboards in order to use your newly renamed custom components.
2. Your custom components will not be using themes … yet. You can adjust them to do so. See Using Themes for full details.

Because of the first issue, we strongly recommend using the override approach above unless there is a significant reason you need access to all of the default charts from Vanilla Components AND all of your customized components.