v3 CLI Migration Audit

[endigo9740]

The following issues have been identified as part of our first pass through the new v3 migration CLI.

Known Issues

• CLI will handle package updates but is not yet installing the correct versions
• CLI description contains a typo, both in package.json and src/index.ts, relating -> related
• If a package.json uses spaces, it will change it to tabs.
• <packagemanager> install needs to be manually ran after migrating.
• src/app.html isn't included in the migration.
• If FileButton and FileDropzone are imported together they will both be renamed to FileUpload causing a duplicate identifier error.
• Tabs changes: v3 CLI Migration Audit #3090 (comment)

Plugin Configuration

The Skeleton plugin configuration needs to be updated to adhere to the new format.

• Preserve the base option: https://next.skeleton.dev/docs/get-started/plugin#base
• For all preset themes, add the new import, and use the new dot notation names (ex: themes.cerberus)
• Make sure to convert legacy presets; noting that a couple have been renamed in v3
  • skeleton renamed to legacy
  • gold-nouveau renamed to nouveau
• Additionally custom themes should be commented out with a note instructing users on where/how to migrate their v2 themes to v3 format. We should substitute the Cerberus theme as a temporary fallback.

plugins: [
  skeleton({
    themes: [
      themes.cerberus

      // SKELETON-MIGRATION: your custom theme has been disabled.
      // myCustomTheme

      // Please import your v2 theme here to begin migrating to the v3 format:
      // https://themes.skeleton.dev/themes/import
    ]
  })
];

Variants -> Presets

• We had a typo in the reference docs - the v3 option should be preset-filled-[...]
• We need to ensure we're converting generic variants to generic presets. The only exception is Gradients, which do not have a generic version.

Generic changes are as follows from v2 -> v3:

• variant-filled -> preset-filled
• variant-soft -> preset-tonal
• variant-ringed -> preset-outlined
• variant-ghost -> preset-tonal + the surface-tone border

Highlight.js -> Shiki

• Skeleton no longer depends on Highlight.js for code blocks or syntax highlighting. However, it's possible users have branched out and used Highlight directly outside of Skeleton (such as parsing CMS or blog post code blocks). So we should likely prompt users remove and/or replace with Shiki.

If possible, point them to the new integration page:
https://skeleton.dev/docs/integrations/code-block/svelte

NOTE: I've removed the next. subdomain above. This is intentional.

Nice to Haves

The following are not hard requirements, but would be ideal for the full release:

• Update the import path from @skeletonlabs/skeleton -> @skeletonlabs/skeleton-svelte
• Prune non-supported import feature imports (ex: AppShell)
• Rename components as applicable (ex: AppRail -> Navigation)

Component changes can be referenced in the migration guide. See the table lists:

• Skeleton v3 Migration Guide #2921

[endigo9740]

@Hugos68

Per Eric's comment in the beta channel on Discord, this is currently an undocumented change and not included in the CLI:

<!-- v2 -->
<TabGroup>
    <Tab>
</TabGroup>

<!-- v3 -->
<Tabs>
    <!-- (snippets here) -->
    <!-- <Tab> was removed. -->
</Tabs>

I'll update the guide if you can please ensure this handle in the CLI.

[Hugos68]

@endigo9740 to add to that, we're missing a lot more components, specifically a bunch of "subcomponents" like AccordionItem, etc. Let's sync on this and create a list.

[Hugos68]

Remindee for myself: remove the +1 -1 offsets for quotes in svelte and simply grab full text and replace.

[endigo9740]

Moving to here for the public beta:

• Skeleton CLI Beta - Public Feedback #3134