v2.0 Release Candidate - Migration Guide #1854

endigo9740 · 2023-08-11T21:15:19Z

endigo9740
Aug 11, 2023
Maintainer

* Skeleton v2 is now live! *

Migration Guide

If you would like like participate in testing the Skeleton v2 release candidate, please follow the instructions provided below.

Important

Unlike standard Skeleton releases, the v2 release candidate is designated as a pre-release, meaning there's a few extra steps to move from v1.x to v2 RC. Please read and follow the instruction below very carefully.

Using the Skeleton CLI

To install and test a new Skeleton v2 RC project using the Skelton CLI, use the @rc tag instead @latest

npm create skeleton-app@rc my-skeleton-app
    - Enable Typescript when prompted (recommended)
cd my-skeleton-app

Migrating v1.x Projects

Uninstall the Skeleton v1.x package.

npm uninstall @skeletonlabs/skeleton

Install the Skeleton v2 RC package and the new standalone Skeleton Tailwind plugin.

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

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

npm add -D @types/node

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...) */

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.

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

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
	]
}

Migrating Themes

Theme configuration is now handled via your Skeleton Tailwind plugin settings in tailwind.config.

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

Preset Themes

Register one or more themes within the plugin settings:

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

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

<body data-theme="skeleton">

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

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

Create a new file in the root of your project, such as my-custom-theme.[ts|js] to house your new theme.
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)
	}
}

Import your new theme in tailwind.config and update your Skeleton plugin settings as follows:

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

// ...

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

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.

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:

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

import { initializeStores } from '@skeletonlabs/skeleton';

initializeStores();

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

import { getDrawerStore } from "@skeletonlabs/skeleton";

const drawerStore = getDrawerStore();

View the documentation for each respective feature for more information:

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.

dev-guy · 2023-08-16T15:59:13Z

dev-guy
Aug 16, 2023

Regarding "Legacy Typography System", I was already using class="h1" etc.. In 1.x, fonts are thick. In 2.x, fonts are thin. I'm using the skeleton theme. Maybe there's something I'm not aware of.

1 reply

endigo9740 Aug 16, 2023
Maintainer Author

@dev-guy you're referring to what are now called theme "enhancements":
https://skeleton-docs-git-v2-skeleton-labs.vercel.app/docs/themes#enhancements

Some themes have a set of extra styles provided, and you can enable this using this feature. This includes some adjustment to font headings for certain themes. Enable this feature and things should display as they did prior.

alexvdvalk · 2023-08-24T21:56:33Z

alexvdvalk
Aug 24, 2023

Remember to include:

plugins: [
    require('@tailwindcss/forms'),
    // ...
  ],

into the tailwind config if using tailwind forms.

1 reply

endigo9740 Aug 24, 2023
Maintainer Author

Thanks for the suggestion! FYI I'll be revising the migration guide for the v2 stable release next week. I'll aim to include this, as it's tripped up a few people in testing.

Uh oh!

v2.0 Release Candidate - Migration Guide #1854

Uh oh!

Uh oh!

endigo9740 Aug 11, 2023 Maintainer

*** Skeleton v2 is now live! ***

Migration Guide

Using the Skeleton CLI

Migrating v1.x Projects

Migrating your Tailwind Configuration

Typescript (tailwind.config.ts)

Javascript (tailwind.config.js)

Migrating Themes

Preset Themes

Custom Themes

Option 1) Use the Theme Generator

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

Migrating Core Features

Table of Contents

Drawer, Modal, and Toast Stores

Skeleton Data Tables

Deprecated Autocomplete Props

Legacy Typography System

Paginator Offset Prop

Replies: 2 comments · 2 replies

Uh oh!

dev-guy Aug 16, 2023

Uh oh!

endigo9740 Aug 16, 2023 Maintainer Author

Uh oh!

Uh oh!

alexvdvalk Aug 24, 2023

Uh oh!

endigo9740 Aug 24, 2023 Maintainer Author

endigo9740
Aug 11, 2023
Maintainer

* Skeleton v2 is now live! *

Replies: 2 comments 2 replies

dev-guy
Aug 16, 2023

endigo9740 Aug 16, 2023
Maintainer Author

alexvdvalk
Aug 24, 2023

endigo9740 Aug 24, 2023
Maintainer Author