v2.0 Migration Guide

[endigo9740]

Release Notes

• View the full v2 Release Notes

Migration Guide

This guide is geared toward users migrating from either Skeleton v1.x or Skeleton v2 RC. Follow the instruction clearly, and make sure to read this page in full.

Using the Skeleton CLI

If you wish to create a new Skeleton v2 project, you can use the Skeleton CLI as follows:

npm create skeleton-app@latest my-skeleton-app
    - Enable Typescript when prompted (recommended)
cd my-skeleton-app
npm install
npm run dev

Migrating v2 Release Candidate Projects

Uninstall the @rc tagged versions of the Skeleton core package and Skeleton Tailwind plugin:

npm uninstall @skeletonlabs/skeleton @skeletonlabs/tw-plugin

Install the latest stable release of these two packages:

npm add -D @skeletonlabs/skeleton @skeletonlabs/tw-plugin

Note that if you use vite-plugin-tailwind-purgecss, we advise updating this to the latest release as well.

Migrating v1.x Projects

1. Uninstall the Skeleton v1.x package.

npm uninstall @skeletonlabs/skeleton

2. Install the updated Skeleton core package and Skeleton Tailwind plugin:

npm add -D @skeletonlabs/skeleton @skeletonlabs/tw-plugin

3. If your SvelteKit projects uses Typescript, install the standard Node type definitions:

npm add -D @types/node

4. Add the following Tailwind directives to the top of your global stylesheet /src/app.postcss

@tailwind base;
@tailwind components;
@tailwind utilities;
@tailwind variants;

/* (all other styles here...) */

5. Remove the Skeleton stylesheet imports in /src/routes/+layout.svelte

<script>
	// Remove:
-	import '@skeletonlabs/skeleton/themes/theme-skeleton.css';
-	import '@skeletonlabs/skeleton/styles/skeleton.css';

	import '../app.postcss'; // KEEP THIS!
</script>

NOTE: this includes any preset or custom generated themes. We'll cover theme migration in detail below.

6. (OPTIONAL) Install vite-plugin-tailwind-purgecss to dramatically reduce your production CSS bundle size.

7. Follow the steps in the sections below. You'll need to update your Tailwind Config, theme registration, and more.

Migrating your Tailwind Configuration

Next, we'll need to migrate tailwind.config.cjs to either a Typescript or Javascript format. If your project has Typescript enabled, use .ts (Typescript) otherwise please opt for .js (Javascript).

Typescript (tailwind.config.ts)

import { join } from 'path';
import type { Config } from 'tailwindcss';

// 1. Import the Skeleton plugin
import { skeleton } from '@skeletonlabs/tw-plugin';

const config = {
	// 2. Opt for dark mode to be handled via the class method
	darkMode: 'class',
	content: [
		'./src/**/*.{html,js,svelte,ts}',
		// 3. Append the path to the Skeleton package
		join(require.resolve(
			'@skeletonlabs/skeleton'),
			'../**/*.{html,js,svelte,ts}'
		)
	],
	theme: {
		extend: {},
	},
	plugins: [
		// 4. Append the Skeleton plugin (after other plugins)
		skeleton
	]
} satisfies Config;

export default config;

Javascript (tailwind.config.js)

// @ts-check
import { join } from 'path';

// 1. Import the Skeleton plugin
import { skeleton } from '@skeletonlabs/tw-plugin';

/** @type {import('tailwindcss').Config} */
export default {
	// 2. Opt for dark mode to be handled via the class method
	darkMode: 'class',
	content: [
		'./src/**/*.{html,js,svelte,ts}',
		// 3. Append the path to the Skeleton package
		join(require.resolve(
			'@skeletonlabs/skeleton'),
			'../**/*.{html,js,svelte,ts}'
		)
	],
	theme: {
		extend: {},
	},
	plugins: [
		// 4. Append the Skeleton plugin (after other plugins)
		skeleton
	]
}

Important

If your project is actively using additional Tailwind plugins, such as Typography, Forms, etc. Then make sure to import and apply these as well. They should be added directly above the skeleton() plugin.

Migrating Themes

Theme configuration is now handled via your Skeleton Tailwind plugin settings in tailwind.config.[ts|js].

NOTE: You can mix preset and custom themes if you wish!

Preset Themes

1. Register one or more themes within the plugin settings:

plugins: [
	skeleton({
		themes: {
			// Register each theme within this array:
			preset: [ "skeleton", "modern", "crimson" ] 
		}
	})
]

2. Open /src/app.html and set your active theme via the data-theme attribute on the body element:

<body data-theme="skeleton">

If you wish to enable background gradient and other optional preset theme features, see the Enhancements documentation.

Custom Themes

Skeleton themes now use a CSS-in-JS format. If you wish to migrate your v1.x theme, use one of the following techniques:

Option 1) Use the Theme Generator

Recreate your theme using the updated Theme Generator, which provides themes in the new format.

Option 2) Migrate to the v2 CSS-in-JS format

1. Visit https://transform.tools/css-to-js
2. Copy the contents within your theme's :root selector and paste them into the CSS field on the left
3. Copy the converted property values on the right (NOTE: the data within the converted object, not converted itself).

4. Create a new file in the root of your project, such as my-custom-theme.[ts|js] to house your new theme.

5. Copy the following template into this file, then add your converted CSS-in-JS theme properties to the properties field:

NOTE: you may also use .js and strip out the CustomThemeConfig Typescript type definition

import type { CustomThemeConfig } from '@skeletonlabs/tw-plugin';

export const myCustomTheme: CustomThemeConfig = {
    name: 'my-custom-theme',
    properties: {
        // (PASTE YOUR THEME PROPERTIES HERE)
    },
    // properties_dark: {
        // Optionally provide dark mode overrides for your CSS custom properties here
    // }
}

6. Import your new theme in tailwind.config, then register the custom theme within the Skeleton plugin settings as follow:

import { myCustomTheme } from './my-custom-theme';

// ...

plugins: [
	skeleton({
		themes: {
			custom: [ myCustomTheme ]
		}
	})
]

8. Open /src/app.html and set your active theme via the data-theme attribute on the body element:

<body data-theme="my-custom-theme">

Migrating Core Features

The following features include breaking changes that may affect your project.

Table of Contents

This features has been reimplemented from the ground up. We recommend you follow the updated documentation.

Drawer, Modal, and Toast Stores

We've refactored the stores for all singleton-based overlay features to help prevent known SvelteKit SSR issues. This includes two notable changes:

1. You must now initialize the stores via initializeStore() in your root layout.

<script>
	import { initializeStores } from '@skeletonlabs/skeleton';

	initializeStores();
</script>

2. You now import and access the stores in a new manner.

NOTE: getDrawer() can only be invoked at the top level of your component (reference)

<script>
	import { getDrawerStore } from "@skeletonlabs/skeleton";

	const drawerStore = getDrawerStore();
</script>

View the documentation for each respective feature for more information:

• Drawers: https://www.skeleton.dev/utilities/drawers
• Modals: https://www.skeleton.dev/utilities/modals
• Toasts: https://www.skeleton.dev/utilities/toasts

Skeleton Data Tables

This feature has been completely removed in Skeleton v2. We now recommend Svelte Simple Datatables paired with Skeleton's Table Element styles.

Deprecated Autocomplete Props

The deprecated whitelist | blacklist props have been removed, please move to allowlist | denylist respectively

Legacy Typography System

The legacy "on-by-default" Typography system has now been completely phased out. Please migrate to the new opt-in system covered in the Typography documentation. In most cases this requires appending a single class to each typographic element.

Paginator Offset Prop

The PaginatorSettings parameter called offset has now been renamed to page for better semantics.