v0.41.48 - Migration Guide

[endigo9740]

See the full release notes

Migration Guide

The new release of Skeleton makes significant changes to the structure of the library. To make the migration process easier, we've provided a detailed guide below to walk you through the process.

Please read each step carefully.

1. Tailwind Config

https://skeleton.brainandbonesllc.com/guides/tailwind

• We now include more specific instructions for configuring dark mode in your app.
• The Skeleton Tailwind plugin has changed to allow support for additional plugins in the future.
  • Was: @brainandbones/skeleton/tailwind.cjs
  • Now: @brainandbones/skeleton/tailwind/theme.cjs

2. Stylesheet Updates

https://skeleton.brainandbonesllc.com/guides/styling

• For most users, we recommend dropping individual stylesheets in favor of the new combined all.css stylesheet.
• For advanced users, we've provided instructions for keeping and importing individual stylesheets (see "Select Styles")
• If using all.css your root layout should contain these three stylesheets, imported in this order:
  • Your Skeleton theme stylesheet
  • The new all.css stylesheet
  • Your global stylesheet

If you use all.css or import the tailwind.css stylesheets make sure to remove the @tailwind directives from your global stylesheet. Failure to do so will mean certain styles, like typography headings, will not work!

FYI: Check out the new per-component style guidance while you're here!

3. Migrate to Tailwind Elements

See the release notes for a full explanation of this new feature or checkout the new Features page.

Now, let's review the process of migrating from Svelte Components to Tailwind Elements.

Migrate a Button

https://skeleton.brainandbonesllc.com/tailwind/buttons

To begin, make sure to remove the Button import in your script tag. This is no longer needed!

import { Button } from '@brainandbones/skeleton'; // remove this!

Here's an example of a the old Button component:

<button variant="filled-primary">Label</button>

This now becomes a native button element with the classes btn btn-filled-primary:

<button class="btn btn-filled-primary">Label</button>

Visually, the button will operate very similar to the Component version, but it's now much easier to override styles using your global stylesheet. This also allows for features like SvelteKit link options, which was not possible with components!

Migrate a Card

https://skeleton.brainandbonesllc.com/tailwind/cards

Similar to the button migration, we remove the import statement in your script tag.

import { Card } from '@brainandbones/skeleton'; // remove this!

Here's an example of an old Card component:

<Card>Contents</Card>

This can now be converted to either a native anchor or div element, with the new card classes applied. The card-body class is optional, but it will add the p-4 padding class for you.

<div class="card card-body">Contents</div>
<a href="/" class="card card-body">Contents</a>

If you need a more complex card element with a header, body, and footer - use the following structure:

<div class="card">
  <header class="card-header">(header)</header>
  <div class="card-body">(body)</div>
  <footer class="card-footer">(footer)</footer>
</div>

Migrating Lists/ListItem

See the List changes here:

#194 (comment)

In short, we've split this in half. We now have Tailwind Element Lists (OL/LI/DL/NAV) and Svelte Component Listboxes (aka selection lists).

If you need to replicate a highlighted navigation list, like our documentation site sidebar, you can reference how it was built here:

https://github.com/Brain-Bones/skeleton/blob/dev/src/docs/DocsNavigation/DocsSidebar.svelte

Migrating Other Component

See the dedicated documentation pages for each Tailwind Element.

• Badges
• Buttons
• Cards
• Lists
• Logo Clouds

5. Remove Deprecated Svelte Components

⚠️As of this release, any Svelte Component that now exists as a Tailwind Element will be considered deprecated. These components will no longer receive updates or support. Additionally, these will be REMOVED from the library in the next release!. It is strongly advised you migrate to the Tailwind Elements as soon as possible.

If you need to review the old component docs, they may be found here:

• Component: Badges
• Component: Buttons
• Component: Cards
• Component: Lists
• Component: Logo Clouds

Note these pages are currently delisted from the docs site menu and will be removed alongside the components in the following release!

6. Breaking Changes to Existing Components

In addition to the new Elements, many existing components received major updates, both structural and visual. The goal was to bring consistency across the library - including updates to prop names, visual styles, and more. A full list of the changes have been provided in this ticket.

• Improve Component Consistency #194

Please note the following,

• Per this link, the first post details global changes, made to most components.
• Per this link, the second post details per-component changes.

If you experience an issue with a component after updating, please reference this document or the component's documentation page. It's very likely due to one of these changes!

Tips and Recommendations

Here's a few tips and tricks to make the migration process easier.

• Use your text editor's Find & Replace feature to to make multiple changes in bulk.
• Use case-sensitive search to differentiate between items like "Card" and "card."
• Make use of the updated documentation site! We've added a lot of new information this release.
• Review the Skeleton documentation source code. This serves as a real world example utilizing all the latest changes.
• The doc site sidebar navigation now includes a basic Search feature. Use this to quickly locate any desired Element or Component.

Getting Support

If you encounter issues, please feel free to reach out. The Skeleton crew is available nearly 24/7 to help troubleshoot via one of the following methods.

• File a support ticket on GitHub Issues
• Make a post in the #support-threads channel on Discord
• If an issue is critical you can @ myself (endigo9740) or Nik (niktek) on Discord. We'll respond asap!

Thanks for all your continued support! We hope you enjoy all the new features and updates!