Migrate from v2

This update represents a major overhaul to the Skeleton library. Including a ground up rewrite of every feature in the library. Note that some portions of this guide will be automated, while others require manual intervention. This is not a trivial migration from prior versions, so please ensure you follow this guide very carefully. This transition you through both the v3 and v4 updates.

Prerequisites

While Skeleton v3 introduced support for multiple frameworks, we’ve historically only supported SvelteKit. As such, this guide is only intended for users migrating from Skeleton v2 and SvelteKit. If you you are coming from another meta-framework, this will be outside the scope of this guide. However, this may still provide insight into the primary objectives for the overall migration process.

Create a Migration Branch

We recommend you handle all migration changes on a dedicated feature branch. This ensures you can easily drop or revert changes if something goes wrong.

git checkout -b migration

Prepare Your Skeleton App

• Your app is running the latest release of Skeleton v2.x
• All critical dependencies have been updated (optional but recommended)
• Your app is in a fully functional state before you proceed

Migrate Core Technologies

Skeleton directly utilizes a number of core technologies. These must be migrated individually before proceeding with the Skeleton-specific migration. Note that Svelte and Tailwind provide dedicated CLIs to help automate this process. Please ensure you adhere to their individual migration guides linked below.

Svelte v5

Migrate to the latest release of Svelte v5.

SvelteKit v2

Migrate to the latest release of SvelteKit v2.

Tailwind v4

Before migrating to Tailwind v4, please do the following:

1. Remove the skeleton plugin from your tailwind.config file.
2. Rename your app.{postcss|pcss} to app.css. Make sure to update layout imports too.
3. Remove the purgecss (vite-plugin-tailwind-purgecss) vite plugin from your vite.config (if installed).

Migrate to the latest release of Tailwind v4.

TIP: Having trouble running Tailwind’s automated migration script due to @apply? Comment or remove the classes temporarily, run the migration CLI, then follow these steps to adapt to use native CSS properties and Tailwind’s new utilities. Though ideally you should avoid the use of @apply going forward.

Migrate to the Tailwind Vite Plugin

Use the following steps to migrate to from PostCSS to the Vite plugin:

1. Delete postcss.config.{js|mjs}
2. Run npm uninstall postcss (if present)
3. Run npm uninstall @tailwindcss/postcss (if present)
4. Run npm install @tailwindcss/vite
5. Open your vite.config in the root of your project
6. Include the following import: import tailwindcss from '@tailwindcss/vite'
7. Finally, add the Vite plugin above your framework plugin:

plugins: [
	tailwindcss(),
	sveltekit(), // or svelte()
];

TIP: Please ensure you’ve committed all pending changes before proceeding.

Automated Migration

We’ve provided a dedicated migration script as part of the Skeleton CLI to help automate much of this process.

First, run the following to migrate for Skeleton v3 changes:

npx skeleton migrate skeleton-3

Commit all pending changes. Then run the following to migrate for Skeleton v4 changes:

npx skeleton migrate skeleton-4

This migration WILL handle the following…

• Update all required package.json dependencies.
• Implement all required Skeleton imports in your global stylesheet app.css.
• Modify data-theme in app.html (if you’re using a Skeleton preset theme)
• Temporarily disable custom theme imports to allow for manual theme migration.
• Migrate all modified Skeleton utility classes (ex: variant-* to preset-*)
• Update all Skeleton imports throughout your entire project.
• Some Component imports will be pruned as they are no longer supported.

This migration WILL NOT…

• Adjust the component structure or component props. Unfortunately there’s too many permutations.
• Migrate Utility features (ex: popovers, code blocks, etc). See our recommendations below.

Make sure to consult your local Git Diff (difference) to compare what has been modified before progressing forward or committing these automated changes.

Manual Migration

With automated migration complete, please follow the remaining manual migration steps. The following is not optional.

Update Stylesheet Imports

NOTE: The Skeleton CLI will handle these for you, but please confirm.

In your global stylesheet (ex: app.css), the @source rules for sourcing component styles have been replaced with simpler and more intuitive @import rules.

@source '../node_modules/@skeletonlabs/skeleton-{framework}/dist'; 
@import '@skeletonlabs/skeleton-{framework}'; 

In Skeleton v3, canned Preset styles were split to an optional stylesheet to allow them to be opt-in. However, due to popular demand, these have now been merged back into the core package in Skeleton v4. As such, you can remove this import.

@import '@skeletonlabs/skeleton/optional/presets'; 

Migrate Themes

For Preset Themes

Your preset theme should be automatically migrated by the CLI. Refer to Themes for more information.

For Custom Themes

1. Use the Import feature provided by the new Theme Generator.
2. Drag and drop your v2 theme into the file upload field.
3. Your theme will be automatically converted to the newest format.
4. Update and modify any theme settings in the live preview.
5. Make sure to set a valid theme name in the right-hand panel.
6. Tap the “Code” tab to preview your generated theme code.
7. Copy the theme code, then following our custom theme instructions .
8. Similar to preset themes, you will need to both register and set an active theme.

Replace AppShell with Custom Layouts

Skeleton has now sunset the ( troublesome ) <AppShell> component in favor of user-defined custom layouts. We’ve provided a dedicated Layouts guide for replicating common layout structures using only semantic HTML and Tailwind - no Skeleton specific features are required.

Migrating Components

Components have undergone a major overhaul starting in Skeleton v3, with further refinements in Skeleton v4. Given the sheer number of changes, we recommend you compare each component to it’s current production documentation.

Key Changes in v3

• Changes to adopt the new Svelte 5 APIs like runes, snippets, event handlers, etc.
• Changes to support Zag.js , which serves as a foundation of our cross-framework components.
• Changes to the import path: @skeletonlabs/skeleton-svelte.
• Changes to the component name and/or structure (including sub-components)
• Changes based on newly introduces features and properties.

Key Changes in v4

• Changes to adopt the newest component conventions
• Changes to introduce new component patterns .

How to Migrate Components

The following showcases the process of migrating a single component.

Was (v2)

<Avatar src="https://i.pravatar.cc/150?img=48" />

Now (v4)

<Avatar>
	<Avatar.Image src="https://i.pravatar.cc/150?img=48" alt="Jane Doe" />
	<Avatar.Fallback>SK</Avatar.Fallback>
</Avatar>

This was handled as follows:

1. We consulted the documentation for the Avatar component
2. The Skeleton migration CLI will have handled all component imports automatically.
3. The root component <Avatar> remains; remove src and other unsupported props.
4. Now implements the new <Avatar.Image> child and pass the src path and alt text.
5. Now implements the new <Avatar.Fallback> child and pass a fallback value, icon, image, etc.

Tips for Component Migration

Until all components are migrated to the new format, they will throw errors when trying to run your local developement server. Use the following technique to update in a more progressive manner.

1. Use your editor of choice to search for Skeleton components via the import path (@skeletonlabs/skeleton-svelte)
2. Comment out each component one-by-one until all are disabled.
3. Consider adding messages such as <p>(avatar)</p> as visible placeholders for components on each page.
4. Uncomment each component individually as you migrate forward to the new syntax.
5. Once all components are migrated, you should no longer receive errors when running the dev server.

Renamed Components in v3

As part of the Skeleton v3 update, several components were renamed to be more semantic.

Renamed Components in v4

Then again in Skeleton v4, select components were renamed to follow the Zag.js naming conventions. This will serve as the baselines going foward.

Tailwind v4 Changes

Tailwind v4 represents a major update for Tailwind. We’ve detailed the most notable features as they may relate to your Skeleton project. Please consult the Tailwind v4 announcement post for the full roster of changes.

• The tailwing.config has been removed in favor of CSS-based configuration .
• New strategies are available to support Dark Mode .
• The Tailwind Forms Plugin is still required for form elements.
• The Skeleton data-theme attribute has moved from <body> to <html>.
• Themes colors are now oklch format , but optionally support any format.

Replacing @apply

We strongly encourage you take this opportunity to move away from any usage of @apply. Tailwind has long since advocated against its use, and the latest release of introduces new directives and functions that make this much easier to avoid. Below a trivial example:

/* Before */

.foo {
	@apply bg-surface-50-950 text-surface-950 dark:text-surface-50 p-4;
}

/* After */

.foo {
	background-color: var(--color-surface-50-950);
	color: var(--color-surface-950);
	padding: --spacing(4);
	@variant dark {
		color: var(--color-surface-50);
	}
}

• Refer to the Skeleton Core API documentation for a full list of Skeleton’s CSS custom properties.
• Refer to the Tailwind’s functions and directives for more information on these new features.

Replace Unsupported Features

Skeleton v3 represented a point of reflection on what features should remain as part of the core experience. As such, we identified a number of features that fall outside of this scope. Don’t fret though, we’ve gone out of our way to detail each feature and provide the best alternative available.

Svelte Actions

TIP: We also recommend Runed for a similar approach to small composable features for Svelte 5.

Components

Utilities

Migrate Input Groups

Although the automated migration script will handle the majority of class updates, Input Groups are the exception and must be migrated manually. Refer to the documentation for updated examples.

Migration Complete

If you’ve completed all steps above in full, your application should once again be in a functional state. Run your application’s local dev server to confirm. Then remember to merge all changes into your primary branch.

npm run dev

Support and Feedback

If you have any questions or issues about the migration process, please contact us on Discord (the #contributors channel) or via GitHub . We are here to help!