Migration guide for Root v2
The latest release of Root brought updates to 3rd party deps such as Vite, Express, SASS, esbuild, and many others. Below are a few things to keep in mind when updating a project to Root v2.
Node updates
Applies to v2.0.0 and above
Support for non-LTS versions of Node.js have been dropped. Please update to Node v20 or above.
Vite config updates
Applies to v2.2.0 and above
Vite has been updated to v7. See Vite's migration guide for more details.
A few items in particular to note:
SASS legacy API deprecation
Vite has deprecated the usage of the SASS legacy API (only the modern API is supported now). Root will automatically attempt under-the-hood to convert config settings to the new API, but you should make the following changes to your root.config.ts file:
⏪ Before:
/** root.config.ts */
import {defineConfig} from '@blinkk/root';
export default defineConfig({
vite: {
css: {
preprocessorOptions: {
scss: {
// `includePaths` should be renamed to `loadPaths`
includePaths: [ /* scss paths */ ],
},
},
},
},
});
⏩ After:
/** root.config.ts */
import {defineConfig} from '@blinkk/root';
export default defineConfig({
vite: {
css: {
preprocessorOptions: {
scss: {
loadPaths: [ /* scss paths */ ],
},
},
},
},
});
SASS updates
Applies to v2.2.0 and above
SASS has been updated to use the latest version of sass‑embedded (v1.92.0 at the time of writing). This version of SASS has a number of breaking changes.
A few items in particular to note:
Mixed Declarations
The way SASS handles Mixed Declarations has changed, which may change the output of your CSS files.
⏪ Before:
/* SCSS input */
.example {
color: red;
&--serious {
font-weight: bold;
}
font-weight: normal;
}
/* CSS output */
.example {
color: red;
font-weight: normal;
}
.example--serious {
font-weight: bold;
}⏩ After:
/* SCSS input */
.example {
color: red;
&--serious {
font-weight: bold;
}
font-weight: normal;
}
/* CSS output */
.example {
color: red;
}
.example--serious {
font-weight: bold;
}
.example {
font-weight: normal;
}Root CMS updates
Applies to v2.2.0 and above
Much of the Root CMS UI has been refactored in order to perform better for large, complex projects. This required a few breaking changes:
Unique names in schema.define()
The schema.define() function now requires a unique named used across the project. This is to help reduce the payload of schemas that reuse a lot of nested schemas throughout components. This change also helps reduce the output size of the root-cms.d.ts file.
❌ Bad:
/* @/components/A.schema.ts */
const Image = schema.define({
name: 'Image',
fields: [...],
});
export default schema.define(...);
/* @/components/B.schema.ts */
const Image = schema.define({
name: 'Image',
fields: [...],
});
export default schema.define(...);✅ Good:
/* @/components/Image.schema.ts */
export default schema.define({
name: 'Image',
fields: [...],
});
/* @/components/A.schema.ts */
import Image from './Image.schema.ts';
export default schema.define(...);
/* @/components/B.schema.ts */
import Image from './Image.schema.ts';
export default schema.define(...);Other issues
Find any other issues that weren't mentioned above? File a ticket in Github and we'll get on it!