A better "manual installation"

[piperun]

Describe what feature you'd like. Pseudo-code, mockups, or screenshots of similar solutions are encouraged!

Looked through the documentation of skeleton and I have to say I absolutely love it!
However when trying to add to an already existing project (with flowbite-svelte mind you), it felt more like the "black sheep" of issues than the blessing the examples (really love the input chips!) show.

The specifically it's the manual installation process to an already existing project, I understand completely if this is not within scope of 0.xx or if it's even possible, but as it stands right now there's too many things to "override" and the process makes you feel constantly worried of 2 things:

• Becoming reliant on a "subset" of tailwind (not entirely accurate, but you have to insert and quite a bit more than flowbite-svelte) - thus fearful of leaving skeleton/svelte in case there's greener pastures out there
• Custom made tailwind elements will not work as intended (I noticed this with my custom sidebar, when trying to install skeleton it quite literally disappeared).

What type of pull request would this be?

Enhancement

Any links to similar examples or other references we should review?

https://www.skeleton.dev/guides/install

[endigo9740]

Hey @piperun, thanks for your feedback. However, we might need more specifics about the issue you faced to help in a meaningful way.

However when trying to add to an already existing project (with flowbite-svelte mind you)

My initial concern is you mentioning you're installing this alongside Flowbite Svelte, which we don't support. Flowbite, Daisy, and our library all implement our own Tailwind plugin for core features. These are not built to work in parallel with other UI library plugin. It's nothing malicious, we just implement our own settings as we need them - we may all be alter the same things, which can lead to conflict. So doing this is definitely not recommended.

it felt more like the "black sheep"

It's not a black sheep, but logically it's a much more complicated process. A CLI doing everything for you is going to provide the easiest onboarding experience possible, which is why we put put that front end center.

but as it stands right now there's too many things to "override"

Specifics would help here. Every step we list is currently required for our system to work. We've put a lot of work into minimizing the steps required, and continue to do so, but as it stands there's no fluff here. These are all hard technical requirements. Let me know if I can explain the purpose of any step(s) in particular. I'd be happy to do so.

Becoming reliant on a "subset" of tailwind (not entirely accurate, but you have to insert and quite a bit more than flowbite-svelte)

I'm not sure what you mean by subset, if anything we're a superset of Tailwind. We change nothing about the base, just extend with our required options and settings. In fact, all our Tailwind plugin settings use theme.extend. Also keep in mind we do a lot more than Flowbite. Trust me, I've had this conversation with Zoltan (creator of Flowbite). There's things we're doing that their team(s) just are not (such as design tokens). I'd venture to guess we'll always have more steps for this reason. But again, this is what led to us spending the time to design and build the CLI - to handle that in an automated fashion for new users.

I understand the frustration if you're migrating an existing project, but the overwhelming majority of our new users are either new to SvelteKit, if not web dev in general. We've designed our onboarding experience with these folks in mind.

Custom made tailwind elements will not work as intended (I noticed this with my custom sidebar, when trying to install skeleton it quite literally disappeared).

I'm going to sound like a broken record, but we need more info to help you debug this. Knee jerk reaction, but I'd venture to guess one of two things are happening:

1. It's using something reliant on the Flowbite plugin, and thus a conflict as mentioned prior
2. A misconfiguration in your tailwind.config.cjs - something we saw a lot when the manual install as the only option

Either way, I'd be happy to help debug if I can.

[piperun]

My initial concern is you mentioning you're installing this alongside Flowbite Svelte, which we don't support

I did assume as much (was just trying out to see if you could), I would then give a suggestion just in case new users were to mistake it as such, to state that only "vanilla" Flowbite is supported.

It's not a black sheep, but logically it's a much more complicated process. A CLI doing everything for you is going to provide the easiest onboarding experience possible, which is why we put put that front end center.

Black sheep was only intended as a metaphor for "because it's more complicated, it has to be the ISSUE!", since there's more paths that can cause issues to occur.

Specifics would help here. Every step we list is currently required for our system to work. We've put a lot of work into minimizing the steps required, and continue to do so, but as it stands there's no fluff here. These are all hard technical requirements. Let me know if I can explain the purpose of any step(s) in particular. I'd be happy to do so.

That is something I understand 100%, for me specifically it was the part about styling: specifically:

SvelteKit's global stylesheet is located in /src/app.postcss. Svelte-Add automatically includes @tailwind directives in your global stylesheet. However, Skeleton imports these for you via all.css. Including these twice can cause issues, so please remove the following from your global stylesheet.

I'm not sure what you mean by subset, if anything we're a superset of Tailwind. We change nothing about the base, just extend with our required options and settings. In fact, all our Tailwind plugin settings use theme.extend. Also keep in mind we do a lot more than Flowbite. Trust me, I've had this conversation with Zoltan (creator of Flowbite). There's things we're doing that their team(s) just are not (such as design tokens). I'd venture to guess we'll always have more steps for this reason. But again, this is what led to us spending the time to design and build the CLI - to handle that in an automated fashion for new users.

Sorry I meant superset, tokens is a concept I'll admit I don't fully grasp (the underlying implementation) I suppose what I worry about is if say I wanted to move away from skeleton, it won't be a simple copy-paste as is the case with vanilla flowbite.

Where would you then say the skeleton team is moving in contrast with the flowbite team?

I understand the frustration if you're migrating an existing project, but the overwhelming majority of our new users are either new to SvelteKit, if not web dev in general. We've designed our onboarding experience with these folks in mind.

I'm happy to hear that skeleton team has taken that into account, although I'm curious, would it be possible to extend the skeleton-cli to be able to automate the "manual installation" option?

I'm going to sound like a broken record, but we need more info to help you debug this. Knee jerk reaction, but I'd venture to guess one of two things are happening:

I'll come back with a clean-slate installation to see if there's any issues.

[endigo9740]

I did assume as much (was just trying out to see if you could), I would then give a suggestion just in case new users were to mistake it as such, to state that only "vanilla" Flowbite is supported.

We'll consider adding some warning about using multiple (potentially conflicting) Tailwind plugins in unison. I think that would be a good add.

That is something I understand 100%, for me specifically it was the part about styling specifically: (discussion about Tailwind directives)

Yeah the directives are complicated concept to understand in Tailwind. They're nothing specific to Skeleton. You can read more about them in the official Tailwind docs here:
https://tailwindcss.com/docs/functions-and-directives

The problem is we recommend Svelte-Add, because it makes the configuration of Tailwind trivial. BUT, it comes with one caveat that they automatically insert a few directives in your app.post.css file. This is great if all you're using is Tailwind, but bad for Skeleton, because they have to proceed all style declarations using directives. If left as is, they would be declared twice, which 100% will cause issues (we've seen it).

We use directives heavily for our Element styles. See them near the tops of each file:
https://github.com/skeletonlabs/skeleton/blob/dev/src/lib/styles/typography.css#L3
https://github.com/skeletonlabs/skeleton/blob/dev/src/lib/styles/elements/buttons.css#L3

By declaring our styles with these directives, that unlocks them to be using like Tailwind utility classes, meaning you can use variants like dark: and md:. It's currently the only way to handle this.

Then it becomes an order of operations issue, the styles have to be imported in the correct order, AFTER the directives. Our all.css does all this for you so users never have to think about it.
https://github.com/skeletonlabs/skeleton/blob/dev/src/lib/styles/all.css

However, the duplicate directives in the app.postcss still have to go, so we ask folks to remove those. If the tailwind.css (which contains the directive declarations) were to come after any of these stylesheets, things will break. It's how Tailwind designed these features, so we're subject to their rules.

(per the bit about styling and design tokens)

The good news is you don't have to know how design tokens work to use Skeleton. They're only relevant if you want to build your own custom components using the same techniques we do, or if you wish understand the inner workings of the theme system for components. That said, we provide a fairly in depth post on the subject here if you wish to learn more. We include a video on there by Brad Frost that does a WONDERFUL job of explaining the concept:
https://www.skeleton.dev/blog/deep-dive-skeleton-styling

But again, this is diving into the deep end of the pool. Not required reading to get up and running! But we do mention them because they are import to how Skeleton works under the hood, and something not present other UI libraries in this space (yet; I think that will change over time).

Where would you then say the skeleton team is moving in contrast with the flowbite team?

Frankly I have no idea what Flowbite is doing. I see posts form them on Twitter, but I don't really keep up with specifics. I have enough on my plate heh. For Skeleton we have a pretty well defined roadmap we're following here, leading up to a v1 release (most likely) next month. Right now we're heavy into "polish" mode per the pinned tickets here on GitHub issues.

• Skeleton Roadmap to v1.0 #503

although I'm curious, would it be possible to extend the skeleton-cli to be able to automate the "manual installation" option?

The CLI is built and maintained by a contributor named @niktek. Feel free to ping him on the CLI repo issues/discussions or on our Discord. He's the second most active contributor after myself. I'm sure he would be happy to talk through the technical specifics for this. But from what I understand it's in the "want to have" category, but not top priority.
https://github.com/skeletonlabs/create-skeleton-app

I'll come back with a clean-slate installation to see if there's any issues.

👍

[endigo9740]

FYI I've created this ticket to get a few quick onboarding adjustments out asap. Probably before our next release on Tuesday, if we can manage it. Warning about the mixed plugins will be included, as well as simplifying the Styling section instruction a bit:

#864

Given this thread has turned into more of a discussion, rather than a set of actionable tasks, I'm going to convert it to a proper GitHub Discussion thread. But I welcome your feedback if I can clarify anything above!

[niktek]

I'm happy to hear that skeleton team has taken that into account, although I'm curious, would it be possible to extend the skeleton-cli to be able to automate the "manual installation" option?

It is non-trivial due to the config being javascript based rather than say JSON (full compiler AST traversals vs JSON object manipulation). We are also able to make assumptions about the codebase as it is a clean install. Not only would it be tricky to correctly insert the config into an existing project - are they using Flowbite, carbon-svelte, smui, smelte etc ? We would also have to know how the others are configured to be able to adjust/disable them etc, let alone fix up any errors or misconfigurations.

Even just for a plain SK project being levelled up with Skeleton - we need to make changes to app.html, and +layout.svelte and app.postcss and trying to infer what is safe to change or not in those files is tricky at best.

All of these approaches don't even cover what to do with existing components/pages/layouts.

Choosing a UI library is a decision made at the beginning of a project or a conscious decision to do a migration and not easily automated.

[endigo9740]

@piperun FYI the new documentation updates went live today. I'd welcome some feedback if you get a chance to run through the onboarding again. This includes the following changes:

• Onboarding instruction improvements #864

[piperun]

Will do! Been very busy so haven't had time going over it yet.
Thanks again to the Skeleton team!