docs: add migration guide

docs/content/1.get-started/5.migration.md

@@ -0,0 +1,158 @@
+---
+title: Migration to v2
+description: 'A comprehensive guide to migrate your application from Nuxt Image v1 to Nuxt Image v2.'
+navigation.title: 'Migration'
+---
+
+Nuxt Image v2 brings improved performance, enhanced TypeScript support, and a better developer experience.
+
+Most apps should be able to upgrade with minimal changes.
+
+## Update dependencies
+
+Update `@nuxt/image` to v2:
+
+::code-group{sync="pm"}
+
+```bash [pnpm]
+pnpm add @nuxt/image
+```
+
+```bash [yarn]
+yarn add @nuxt/image
+```
+
+```bash [npm]
+npm install @nuxt/image
+```
+
+```bash [bun]
+bun add @nuxt/image
+```
+
+::
+
+## Check your Nuxt version
+
+Nuxt Image v2 requires at least **Nuxt 3.1**. Check your current version:
+
+```bash
+npm list nuxt
+```
+
+If you're on Nuxt 3.0.x, upgrade first:
+
+```bash
+npx nuxt upgrade --channel v3
+```
+
+::tip
+Nuxt Image v2 is fully compatible with Nuxt 4. See the [Nuxt 4 migration guide](https://nuxt.com/docs/getting-started/upgrade#nuxt-4) if you're ready to upgrade.
+::
+
+## Update screen sizes
+
+The `xs` and `xxl` breakpoints have been removed to align with Tailwind CSS defaults.
+
+Search for usage in your project:
+
+```bash
+grep -r "sizes.*xs:" --include="*.vue"
+grep -r "sizes.*xxl:" --include="*.vue"
+```
+
+**If you are using these screen sizes**, you can either replace `xs` with `sm` and `xxl` with `2xl`:
+
+```diff
+  <NuxtImg 
+    src="/image.jpg" 
+-   sizes="xs:100vw sm:50vw md:400px"
++   sizes="sm:100vw md:50vw lg:400px"
+  />
+```
+
+... or you can add them back in your config:
+
+```ts [nuxt.config.ts]
+export default defineNuxtConfig({
+  image: {
+    screens: {
+      xs: 320,
+      xxl: 1536
+    }
+  }
+})
+```
+
+## Update custom providers
+
+If you have custom image providers, update them to use `defineProvider`.
+
+**Before (v1):**
+
+```ts [providers/my-provider.ts]
+export const getImage = (src, { modifiers }) => {
+  // ...
+  return { url }
+}
+```
+
+**After (v2):**
+
+```ts [providers/my-provider.ts]
+import { defineProvider } from '@nuxt/image/runtime'
+
+export default defineProvider({
+  getImage(src, { modifiers }) {
+    // ...
+    return { url }
+  }
+})
+```
+
+### Add modifier types (optional)
+
+Add types for custom modifiers:
+
+```ts [providers/my-provider.ts]
+import { defineProvider } from '@nuxt/image/runtime'
+import type { ImageModifiers } from '@nuxt/image'
+
+interface MyProviderModifiers extends ImageModifiers {
+  watermark?: 'logo' | 'text' | 'none'
+  rotate?: number
+}
+
+export default defineProvider<MyProviderModifiers>({
+  getImage(src, { modifiers }) {
+    // ...
+    return { url }
+  }
+})
+```
+
+Modifiers will now be typed within your provider, and also when it is used within `<NuxtImg>` and `<NuxtPicture>`.
+
+### Update formatter
+
+Within `createOperationsGenerator`, if you used `joinWith` for parameter formatting, but didn't use `formatter`, you will now need to add a custom formatter.
+
+```ts [providers/my-provider.ts]
+import { createOperationsGenerator, defineProvider } from '@nuxt/image/runtime'
+
+const operationsGenerator = createOperationsGenerator({
+  keyMap: { width: 'w', height: 'h' },
+  joinWith: '&',
+  formatter: (key, value) => `${key}=${encodeURIComponent(value)}`
+})
+
+export default defineProvider({
+  getImage(src, { modifiers, baseURL = '/' }) {
+    const operations = operationsGenerator(modifiers)
+    return {
+      url: `${baseURL}${src}?${operations}`
+    }
+  }
+})
+```
+