From 91fe010eadd2406e51f67da06258024005196481 Mon Sep 17 00:00:00 2001
From: Sanchitv3 <sanchitverma03032003@gmail.com>
Date: Mon, 23 Feb 2026 16:08:16 +0530
Subject: [PATCH] Update migration guide to include instructions for overriding
 lightningcss version in package.json

- Added detailed steps for pinning lightningcss to version 1.30.1 using npm, yarn, pnpm, and bun.
- Included a warning about potential deserialization errors with global.css if the version is not pinned.
---
 components/copy-migration-button.tsx  | 38 +++++++++++++++++++-
 content/blog/v5-migration-guide.mdx   | 51 ++++++++++++++++++++++++++-
 content/v5/guides/migrate-from-v4.mdx | 51 ++++++++++++++++++++++++++-
 3 files changed, 137 insertions(+), 3 deletions(-)

diff --git a/components/copy-migration-button.tsx b/components/copy-migration-button.tsx
index af3a4f0..b2b51fa 100644
--- a/components/copy-migration-button.tsx
+++ b/components/copy-migration-button.tsx
@@ -123,7 +123,42 @@ const { withNativewind } = require("nativewind/metro");
 module.exports = withNativewind(config);
 \`\`\`
 
-### Step 6: Clear Cache and Restart
+### Step 6: Override the lightningcss version
+
+Force \`lightningcss\` to a specific version in your \`package.json\` to avoid deserialization errors with \`global.css\` when building:
+
+**npm / bun:** Add to \`package.json\`:
+\`\`\`json
+{
+  "overrides": {
+    "lightningcss": "1.30.1"
+  }
+}
+\`\`\`
+
+**yarn:** Add to \`package.json\`:
+\`\`\`json
+{
+  "resolutions": {
+    "lightningcss": "1.30.1"
+  }
+}
+\`\`\`
+
+**pnpm:** Add to \`package.json\`:
+\`\`\`json
+{
+  "pnpm": {
+    "overrides": {
+      "lightningcss": "1.30.1"
+    }
+  }
+}
+\`\`\`
+
+If you don't pin the \`lightningcss\` version, you may encounter deserialization errors with respect to \`global.css\` when building your app.
+
+### Step 7: Clear Cache and Restart
 
 \`\`\`bash
 npx expo start --clear
@@ -471,6 +506,7 @@ Use this checklist to ensure a complete migration:
 - [ ] Update \`global.css\` with new Tailwind v4 imports
 - [ ] Remove Nativewind from \`babel.config.js\`
 - [ ] Update \`metro.config.js\` to remove second argument from \`withNativewind\`
+- [ ] Pin \`lightningcss\` to 1.30.1 in \`package.json\` (overrides/resolutions)
 - [ ] Clear Metro cache (\`npx expo start --clear\`)
 - [ ] Search and replace renamed classes (\`elevation-sm\` → \`elevation-xs\`, etc.)
 - [ ] Replace \`{}-[\` with \`@prop-[\` for dynamic modifiers
diff --git a/content/blog/v5-migration-guide.mdx b/content/blog/v5-migration-guide.mdx
index 2ed6f7f..4090acb 100644
--- a/content/blog/v5-migration-guide.mdx
+++ b/content/blog/v5-migration-guide.mdx
@@ -110,7 +110,56 @@ Update the `withNativewind` function call (no longer requires a second argument)
 + module.exports = withNativewind(config);
 ```
 
-### Step 6: Clear Cache and Restart
+### Step 6: Override the lightningcss version
+
+Force `lightningcss` to a specific version in your `package.json`:
+
+<Tabs groupId="v5-npm-install" items={["npm", "yarn", "pnpm", "bun"]}>
+  <Tab value="npm">
+    ```json title="package.json"
+    {
+      "overrides": {
+        "lightningcss": "1.30.1"
+      }
+    }
+    ```
+  </Tab>
+  <Tab value="yarn">
+    ```json title="package.json"
+    {
+      "resolutions": {
+        "lightningcss": "1.30.1"
+      }
+    }
+    ```
+  </Tab>
+  <Tab value="pnpm">
+    ```json title="package.json"
+    {
+      "pnpm": {
+        "overrides": {
+          "lightningcss": "1.30.1"
+        }
+      }
+    }
+    ```
+  </Tab>
+  <Tab value="bun">
+    ```json title="package.json"
+    {
+      "overrides": {
+        "lightningcss": "1.30.1"
+      }
+    }
+    ```
+  </Tab>
+</Tabs>
+
+<Callout type="warn">
+  If you don't pin the `lightningcss` version, you may encounter deserialization errors with respect to `global.css` when building your app.
+</Callout>
+
+### Step 7: Clear Cache and Restart
 
 ```bash
 npx expo start --clear
diff --git a/content/v5/guides/migrate-from-v4.mdx b/content/v5/guides/migrate-from-v4.mdx
index cb24bd3..5da1d30 100644
--- a/content/v5/guides/migrate-from-v4.mdx
+++ b/content/v5/guides/migrate-from-v4.mdx
@@ -82,7 +82,56 @@ Update the `withNativewind` function call (no longer requires a second argument)
 
 Note: While `withNativeWind` was renamed to `withNativewind`, either will work.
 
-### Step 6: Clear Cache and Restart
+### 6. Override the lightningcss version
+
+Force `lightningcss` to a specific version in your `package.json`:
+
+<Tabs groupId="v5-npm-install" items={["npm", "yarn", "pnpm", "bun"]}>
+  <Tab value="npm">
+    ```json title="package.json"
+    {
+      "overrides": {
+        "lightningcss": "1.30.1"
+      }
+    }
+    ```
+  </Tab>
+  <Tab value="yarn">
+    ```json title="package.json"
+    {
+      "resolutions": {
+        "lightningcss": "1.30.1"
+      }
+    }
+    ```
+  </Tab>
+  <Tab value="pnpm">
+    ```json title="package.json"
+    {
+      "pnpm": {
+        "overrides": {
+          "lightningcss": "1.30.1"
+        }
+      }
+    }
+    ```
+  </Tab>
+  <Tab value="bun">
+    ```json title="package.json"
+    {
+      "overrides": {
+        "lightningcss": "1.30.1"
+      }
+    }
+    ```
+  </Tab>
+</Tabs>
+
+<Callout type="warn">
+  If you don't pin the `lightningcss` version, you may encounter deserialization errors with respect to `global.css` when building your app.
+</Callout>
+
+### Step 7: Clear Cache and Restart
 
 ```bash
 npx expo start --clear