docs: update for v4 release + add migration guide

danielroe · danielroe · commit 7edce298f5c7 · 2025-11-11T21:54:59.000Z
diff --git a/README.md b/README.md
@@ -22,14 +22,14 @@
 
 ## Features
 
-- Add `.${color}-mode` class to `<html>` for easy CSS theming
+- Add `.${color}` class to `<html>` for easy CSS theming
 - Force a page to a specific color mode (perfect for incremental development)
 - Works with client-side and universal rendering
 - Auto detect system [color-mode](https://drafts.csswg.org/mediaqueries-5/#descdef-media-prefers-color-mode)
 
 [📖 &nbsp;Read more](https://color-mode.nuxtjs.org)
 
-**Note**: v3 of `@nuxtjs/color-mode` is compatible with [Nuxt 3+ and Nuxt Bridge](https://nuxt.com). If you're looking for the previous version of this module, check out [the previous docs](https://v2.color-mode.nuxtjs.org/), or [read more about the differences](https://color-mode.nuxtjs.org/#migrating-to-v3).
+**Note**: v4 of `@nuxtjs/color-mode` is compatible with [Nuxt 3+](https://nuxt.com). If you're looking for the previous version of this module, check out [the previous docs](https://v2.color-mode.nuxtjs.org/), or [read more about the differences](https://color-mode.nuxtjs.org/#migrating-to-v3).
 
 ## Contributing
 
diff --git a/docs/content/3.advanced/2.migration.md b/docs/content/3.advanced/2.migration.md
@@ -1,8 +1,75 @@
 ---
-title: Migrating to v3
-description: Guide for migrating from v2 to v3
+title: Migration Guide
+description: Guide for migrating between major versions
 ---
 
+## Migrating to v4
+
+v4 of `@nuxtjs/color-mode` requires Nuxt 3+ and drops support for Nuxt Bridge. It also introduces several breaking changes to improve the module.
+
+### Main Changes
+
+#### 1. No Default Class Suffix
+
+The default `classSuffix` has been removed. If you were relying on the default `-mode` suffix, you'll need to explicitly set it in your configuration:
+
+```ts
+export default defineNuxtConfig({
+  colorMode: {
+    classSuffix: '-mode'
+  }
+})
+```
+
+Or update your CSS classes to remove the suffix:
+
+```diff
+- .dark-mode { }
+- .light-mode { }
++ .dark { }
++ .light { }
+```
+
+#### 2. CommonJS Support Dropped
+
+The module no longer provides CommonJS builds. Ensure your project is using ESM (which is the default for Nuxt 3).
+
+#### 3. Read-Only Color Mode Value
+
+You can no longer directly set `colorMode.value`. Use `colorMode.preference` instead:
+
+```diff
+<script setup>
+const colorMode = useColorMode()
+
+- colorMode.value = 'dark'
++ colorMode.preference = 'dark'
+</script>
+```
+
+The `value` property is now read-only and reflects the actual color mode being used (which may differ from `preference` when using system preference detection).
+
+#### 4. Removed `hid` Option
+
+The defunct `hid` configuration option has been removed. If you were using it in your config, simply remove it:
+
+```diff
+export default defineNuxtConfig({
+  colorMode: {
+-   hid: 'nuxt-color-mode-script',
+    preference: 'system',
+  }
+})
+```
+
+#### 5. Nuxt Bridge Support Dropped
+
+Support for Nuxt Bridge has been removed. If you're still using Nuxt Bridge, you should continue using v3. Otherwise, upgrade to Nuxt 3+.
+
+---
+
+## Migrating to v3
+
 v3 of `@nuxtjs/color-mode` requires either Nuxt Bridge or Nuxt 3+. If you are using Nuxt 2 without Bridge, you should continue to use v2.
 
 ## Main Changes
