docs(next): Migration instruction (#1446)

Co-authored-by: Hunter Johnston <[email protected]>

sites/docs/src/content/migration/svelte-5/index.md

@@ -0,0 +1,154 @@
+---
+title: Svelte 5 Migration
+description: How to migrate to Svelte 5 from Svelte 4.
+---
+
+## Prerequisites
+
+1. Ensure you have read up on the changes from Svelte 4 to Svelte 5. Svelte provides a comprehensive guide for this on their [website](https://svelte.dev/docs/svelte/v5-migration-guide).
+2. Commit any pending changes to your repository.
+3. Determine which of your components have custom behavior/styles so that you can reimplement those after updating.
+
+<script>
+    import { Steps, PMExecute, PMInstall, PMRemove } from "$lib/components/docs";
+</script>
+
+## Migrate Configs
+
+The `tailwind.config`, `components.json`, and `utils` files have all changed for Svelte 5.
+
+### Automatic
+
+Note: This works best for projects that have not changed the contents of `tailwind.config`, `utils`, and the global css file.
+
+<PMExecute command="shadcn-svelte@next init"/>
+
+### Manual
+
+<Steps>
+
+### Update `components.json`
+
+Add the `registry` to the root object, and add `hooks` and `ui` keys under `aliases`.
+
+```json {2} {12-13} {16}
+{
+  "$schema": "https://next.shadcn-svelte.com/schema.json",
+  "style": "default",
+  "tailwind": {
+    "config": "tailwind.config.js",
+    "css": "src\\app.pcss",
+    "baseColor": "zinc"
+  },
+  "aliases": {
+    "components": "$lib/components",
+    "utils": "$lib/utils",
+    "ui": "$lib/components/ui",
+    "hooks": "$lib/hooks"
+  },
+  "typescript": true,
+  "registry": "https://next.shadcn-svelte.com/registry"
+}
+```
+
+### Update `tailwind.config`
+
+Add `tailwindcss-animate`.
+
+<PMInstall command="tailwindcss-animate"/>
+
+Add `tailwindcss-animate` plugin and animations config.
+
+```json {2} {22-43}
+import type { Config } from 'tailwindcss';
+import tailwindcssAnimate from 'tailwindcss-animate';
+
+const config: Config = {
+	darkMode: ['class'],
+	content: ['./src/**/*.{html,js,svelte,ts}'],
+	safelist: ['dark'],
+	theme: {
+		container: {
+			// unchanged ...
+		},
+		extend: {
+			colors: {
+				// unchanged ...
+			},
+			borderRadius: {
+				// unchanged ...
+			},
+			fontFamily: {
+                // unchanged ...
+			},
+			keyframes: {
+				'accordion-down': {
+					from: { height: '0' },
+					to: { height: 'var(--radix-accordion-content-height)' }
+				},
+				'accordion-up': {
+					from: { height: 'var(--radix-accordion-content-height)' },
+					to: { height: '0' }
+				},
+				'caret-blink': {
+					'0%,70%,100%': { opacity: '1' },
+					'20%,50%': { opacity: '0' }
+				}
+			},
+			animation: {
+				'accordion-down': 'accordion-down 0.2s ease-out',
+				'accordion-up': 'accordion-up 0.2s ease-out',
+				'caret-blink': 'caret-blink 1.25s ease-out infinite'
+			}
+		}
+	},
+	plugins: [tailwindcssAnimate]
+};
+
+export default config;
+```
+
+### Update `utils`
+
+Note: You may not want to do this if you aren't going to upgrade all your components, as some components may still rely on the now removed `flyAndScale` function.
+
+The only function exported from utils now is `cn`.
+
+```ts
+import { type ClassValue, clsx } from "clsx";
+import { twMerge } from "tailwind-merge";
+
+export function cn(...inputs: ClassValue[]) {
+  return twMerge(clsx(inputs));
+}
+```
+
+</Steps>
+
+## Upgrade Components
+
+Pick and choose which components to upgrade with the `update` command.
+
+<PMExecute command="shadcn-svelte@next update"/>
+
+## Upgrade `bits-ui`
+
+The `update` command doesn't upgrade `bits-ui` so you will need to do that yourself.
+
+<PMInstall command="bits-ui@next"/>
+
+## Remove unused dependencies
+
+In Svelte 5 we have changed some dependencies.
+
+### Remove `cmdk-sv`
+
+`cmdk-sv` has been merged into `bits-ui` and is no longer necessary. Update any imports from `cmdk-sv` to `bits-ui`.
+
+<PMRemove command="cmdk-sv"/>
+
+### Remove `svelte-headless-table`
+
+`svelte-headless-table` has been removed in favor of `@tanstack/table-core`.
+
+<PMRemove command="svelte-headless-table"/>

sites/docs/src/lib/components/docs/index.ts

@@ -8,6 +8,7 @@ export { default as PMExecute } from "./pm-execute.svelte";
 export { default as PMAddComp } from "./pm-add-comp.svelte";
 export { default as PMCreate } from "./pm-create.svelte";
 export { default as PMInstall } from "./pm-install.svelte";
+export { default as PMRemove } from "./pm-remove.svelte";
 export { default as InstallTabs } from "./install-tabs.svelte";
 
 export * from "./page-header/index.js";

sites/docs/src/lib/components/docs/pm-block.svelte

@@ -5,9 +5,10 @@
 		getPackageManager,
 		getPackageManagerInstallCmd,
 		getPackageManagerScriptCmd,
+		getPackageManagerUninstallCmd,
 	} from "$lib/stores/package-manager.js";
 
-	type PMBlockType = "execute" | "create" | "install";
+	type PMBlockType = "execute" | "create" | "install" | "remove";
 
 	export let type: PMBlockType;
 	export let command: string = "";
@@ -24,6 +25,11 @@
 		return getPackageManagerInstallCmd($selectedPackageManager);
 	}
 
+	function getUninstallCommand() {
+		if (command === "") return "install";
+		return getPackageManagerUninstallCmd($selectedPackageManager);
+	}
+
 	let cmdStart = getCmd(type, $selectedPackageManager);
 
 	$: cmdStart = getCmd(type, $selectedPackageManager);
@@ -34,9 +40,15 @@
 		<code data-language="bash" data-theme="github-dark" style="display: grid;">
 			<span data-line>
 				<span style="color:#B392F0;font-weight:bold">{`${cmdStart}`}</span>
-				{#if type === "install" || type === "create"}
+				{#if type === "install" || type === "create" || type == "remove"}
 					<span style="color:#9ECBFF">
-						{`${type === "install" ? getInstallCommand() : "create"}${command === "" ? "" : ` `}`}
+						{#if type === "install"}
+							{`${getInstallCommand()} `}
+						{:else if type == "create"}
+							{"create "}
+						{:else if type == "remove"}
+							{`${getUninstallCommand()} `}
+						{/if}
 					</span>
 				{/if}
 				{#if command !== ""}

sites/docs/src/lib/components/docs/pm-remove.svelte

@@ -0,0 +1,6 @@
+<script lang="ts">
+	import PMBlock from "./pm-block.svelte";
+	export let command: string;
+</script>
+
+<PMBlock type="remove" {command} />

sites/docs/src/lib/config/docs.ts

@@ -86,6 +86,13 @@ export const docsConfig: DocsConfig = {
 					href: "/docs/changelog",
 					items: [],
 				},
+				{
+					title: "Migration",
+					label: "v5",
+					// if there is a svelte 6 migration etc point to /docs/migration
+					href: "/docs/migration/svelte-5",
+					items: [],
+				},
 				{
 					title: "About",
 					href: "/docs/about",

sites/docs/src/lib/stores/package-manager.ts

@@ -43,6 +43,17 @@ export function getPackageManagerInstallCmd(pm: PackageManager): string {
 	return packageManagerToInstallCmd[pm];
 }
 
+const packageManagerToUninstallCmd: Record<PackageManager, string> = {
+	npm: "uninstall",
+	yarn: "remove",
+	pnpm: "remove",
+	bun: "remove",
+};
+
+export function getPackageManagerUninstallCmd(pm: PackageManager): string {
+	return packageManagerToUninstallCmd[pm];
+}
+
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
 export function isPackageManager(value: any): value is PackageManager {
 	return packageManagers.includes(value);