upgrading-expo

Tổng quan về skill upgrading-expo

Skill upgrading-expo làm được gì

upgrading-expo là skill giúp bạn lập kế hoạch và triển khai nâng cấp Expo SDK với ít điểm mù hơn so với một prompt chung chung kiểu “làm sao để nâng cấp Expo?”. Skill này tập trung vào đúng phần việc thực tế: cập nhật các package cốt lõi, xử lý lệch phiên bản dependency, dọn cache cũ, và phát hiện các thay đổi dễ gây lỗi liên quan đến React, New Architecture, native tabs và các lộ trình thay thế expo-av.

Ai nên dùng upgrading-expo

upgrading-expo skill phù hợp nhất với lập trình viên frontend, team React Native và các AI agent đang bảo trì một ứng dụng Expo có sẵn. Skill này hữu ích nhất khi bạn đã có project và cần một lộ trình nâng cấp thực dụng, thay vì chỉ đọc tóm tắt release note.

Các trường hợp đặc biệt phù hợp:

• Nâng cấp giữa các phiên bản Expo SDK gần nhau
• Khắc phục lỗi cài đặt hoặc lỗi runtime sau khi chạy expo install --fix
• Di chuyển khỏi các package đã thay đổi hoặc bị tách ra như expo-av
• Kiểm tra xem các thay đổi theo từng SDK như React 19 hoặc Native Tabs có ảnh hưởng đến codebase của bạn hay không

Công việc thực sự người dùng cần giải quyết

Người đang cân nhắc upgrading-expo for Frontend Development thường muốn có câu trả lời nhanh cho ba câu hỏi:

1. Tôi nên chạy chuỗi lệnh nào trước?
2. Những breaking change nào có khả năng ảnh hưởng đến app của tôi?
3. Tôi nên kiểm tra file hoặc pattern nào trước khi mất thời gian debug lan man?

Skill này có giá trị vì nó gom các quyết định đó vào một nơi và gắn chúng với các tài liệu migration cụ thể.

Điểm khác biệt so với một prompt nâng cấp chung chung

Một prompt thông thường có thể chỉ gợi ý “nâng cấp Expo rồi chạy doctor”. upgrading-expo đi xa hơn bằng cách chỉ ra các chủ đề migration theo từng phiên bản ngay từ repository, bao gồm:

• Mặc định New Architecture trong SDK 53+
• Thay đổi React 19 trong SDK 54
• Thiết lập React Compiler trong SDK 54+
• Thay đổi API Native Tabs trong SDK 55
• Các hướng thay thế expo-av cho audio và video

Nhờ vậy, skill này phù hợp hơn cho công việc nâng cấp có mục tiêu rõ ràng so với một prompt xử lý sự cố React Native diện rộng.

Cần biết gì trước khi cài đặt

Skill này thiên về hướng dẫn hơn là tự động hóa. Nó không đi kèm script để tự quét repo của bạn. Giá trị của nó nằm ở quy trình nâng cấp đã được chọn lọc và các tài liệu tham chiếu mà bạn có thể áp dụng cho chính codebase của mình. Nếu bạn đang tìm một công cụ migrator kiểu bấm nút là chạy, đây không phải lựa chọn đó. Nếu bạn cần một checklist nâng cấp cô đọng, tín hiệu cao và có ví dụ migration cụ thể, đây là lựa chọn rất hợp.

Cách dùng skill upgrading-expo

Ngữ cảnh cài đặt cho upgrading-expo

Nếu môi trường AI của bạn hỗ trợ Skills, hãy cài repository Expo skills và gọi upgrading-expo từ đó. Cách dùng phổ biến là:

npx skills add https://github.com/expo/skills --skill upgrading-expo

Nếu toolchain của bạn dùng skill loader khác, hãy trỏ tới đường dẫn repo:
plugins/expo/skills/upgrading-expo

Bắt đầu từ đúng file trong repository

Để dùng upgrading-expo hiệu quả trong thực tế, hãy đọc theo thứ tự này:

1. SKILL.md
2. references/new-architecture.md
3. references/react-19.md
4. references/react-compiler.md
5. references/native-tabs.md
6. references/expo-av-to-audio.md
7. references/expo-av-to-video.md

Thứ tự này phản ánh các điểm nghẽn nâng cấp thường gặp nhất: thay đổi về kiến trúc và React trước, migration ở mức tính năng sau.

Dùng chuỗi nâng cấp cốt lõi trước

Luồng nâng cấp nền tảng của skill khá ngắn và rất đáng làm theo trước khi đi vào debug sâu hơn:

npx expo install expo@latest
npx expo install --fix
npx expo-doctor
npx expo export -p ios --clear
rm -rf node_modules .expo
watchman watch-del-all

Vì sao bước này quan trọng:

• expo@latest giúp căn chỉnh SDK
• --fix đồng bộ các phiên bản package do Expo quản lý
• expo-doctor phát hiện sớm các vấn đề tương thích
• xóa cache giúp loại bỏ trạng thái Metro/native cũ, vốn rất dễ bị nhầm là lỗi do nâng cấp

Nếu bạn dùng Linux hoặc không dùng Watchman, hãy điều chỉnh phần dọn dẹp cho phù hợp.

Biết khi nào nên dùng bản preview

Skill cũng đề cập đến các bản beta của Expo thông qua phiên bản .preview dưới @next. Điều này hữu ích nếu bạn đang kiểm tra một SDK sắp phát hành hoặc thử một bản sửa lỗi chưa có trong stable.

npx expo install expo@next --fix

Chỉ nên làm việc này khi bạn chủ đích muốn thử. Nâng cấp bằng bản preview không phải mặc định tốt cho ứng dụng production, trừ khi bạn đang chủ động đánh giá pre-release.

Cung cấp đúng đầu vào mà skill thực sự cần

Những prompt upgrading-expo guide tốt nhất luôn nêu rõ trạng thái hiện tại và trạng thái mục tiêu. Hãy cung cấp cho skill:

• phiên bản Expo SDK hiện tại
• package manager đang dùng
• bạn dùng Expo Go hay development builds
• bạn có chạy prebuild hay không
• các package quan trọng: expo-router, expo-av, react-native-reanimated, custom native modules
• lỗi hiện tại ở bước cài đặt, build hoặc runtime
• mọi lỗi riêng theo nền tảng trên iOS, Android hoặc web

Không có ngữ cảnh này thì đầu ra sẽ chỉ dừng ở mức chung chung.

Biến mục tiêu mơ hồ thành một prompt mạnh

Prompt yếu:

Upgrade my Expo app.

Prompt tốt hơn:

Use the upgrading-expo skill to move my app from Expo SDK 53 to 54. We use expo-router, expo-av, Reanimated, and development builds. After npx expo install --fix, expo-doctor reports dependency mismatches and our app fails on startup with video playback errors. Tell me the likely breaking changes, the commands to run in order, and the code areas I should inspect first.

Vì sao cách này hiệu quả:

• nêu rõ SDK nguồn và SDK đích
• liệt kê các package rủi ro cao
• yêu cầu đầu ra có ưu tiên, không phải lời khuyên chung chung

Đối chiếu app của bạn với các guide tham chiếu

Các tài liệu tham chiếu trong repository phát huy giá trị nhất khi bạn chủ động ghép chúng với bề mặt dependency của app:

• Dùng expo-av cho âm thanh hoặc ghi âm? Đọc references/expo-av-to-audio.md
• Dùng expo-av cho video? Đọc references/expo-av-to-video.md
• Nâng lên SDK 55 và có expo-router/unstable-native-tabs? Đọc references/native-tabs.md
• Chuyển sang SDK 53+ hoặc 54+ với native modules? Đọc references/new-architecture.md
• Đang ở SDK 54? Xem cả references/react-19.md và references/react-compiler.md

Đây chính là chỗ skill mang lại thêm giá trị thông tin hơn hẳn việc lướt repo qua loa.

Theo dõi các vùng nâng cấp rủi ro cao nhất

Trong thực tế, đây là các điểm vỡ thường gặp nhất mà skill chỉ ra:

• lệch phiên bản package sau khi tăng SDK
• không tương thích với New Architecture ở các native module cũ
• thay đổi trong thiết lập Reanimated, bao gồm react-native-worklets ở SDK 54+
• thay đổi API React 19 trong code app hoặc thư viện
• migration từ expo-av sang expo-audio và expo-video
• thay đổi UI ở tầng router trong Native Tabs

Nếu app của bạn dùng bất kỳ phần nào ở trên, hãy yêu cầu skill tạo checklist migration có mục tiêu rõ ràng thay vì một bản tóm tắt nâng cấp chung.

Dùng quy trình hai lượt

Một cách dùng upgrading-expo hiệu quả là:

1. Yêu cầu một kế hoạch nâng cấp dựa trên phiên bản và dependency của bạn
2. Chạy các lệnh
3. Gửi lại đúng lỗi đang gặp và yêu cầu một kế hoạch xử lý hẹp hơn

Skill này xử lý triage có cấu trúc tốt hơn nhiều khi bạn mang về đầu ra cụ thể từ expo-doctor, TypeScript, Metro hoặc native builds.

Kiểm tra các vấn đề kiểu release note mà skill đang ám chỉ

Checklist breaking changes của skill dẫn bạn đến các vùng cần rà soát thực tế:

• API bị loại bỏ
• đường dẫn import đã thay đổi
• thay đổi native module yêu cầu prebuild
• lỗi hồi quy ở camera, audio và video
• lỗi hồi quy ở navigation

Điều đó có nghĩa là phần review code của bạn không nên dừng ở package.json. Hãy tìm trong toàn bộ codebase các import và component bị ảnh hưởng trước khi chạy app.

Dùng cẩn thận với prebuild và native code

Nếu app của bạn dùng custom native modules hoặc config plugins, upgrading-expo skill vẫn hữu ích, nhưng hãy chuẩn bị cho việc phải làm thêm ngoài những gì markdown tham chiếu đề cập. Với các project kiểu này, hãy yêu cầu skill tách riêng:

• các tác vụ migration chỉ ở JS
• các tác vụ cần regenerate prebuild
• các bước kiểm tra tương thích dependency native

Việc tách này giúp giảm nhầm lẫn trong quá trình nâng cấp.

Câu hỏi thường gặp về skill upgrading-expo

upgrading-expo có phù hợp cho người mới bắt đầu không?

Có, nếu bạn đã có một project Expo và có thể chia sẻ các thông tin cơ bản của project. Đây không phải một hướng dẫn Expo toàn diện. Nó là guide tập trung vào nâng cấp, vì vậy người mới sẽ có kết quả tốt nhất khi cung cấp phiên bản SDK hiện tại, lỗi đang gặp và các dependency chính.

Ranh giới của upgrading-expo skill là gì?

Skill này hỗ trợ lập kế hoạch nâng cấp, sắp thứ tự lệnh cần chạy và chỉ ra các điểm migration rủi ro đã biết. Nó không tự động quét toàn bộ repo của bạn, cũng không thể đảm bảo tương thích cho mọi thư viện native bên thứ ba. Với các lỗi native sâu hơn, bạn vẫn có thể phải xem tài liệu riêng của package và các GitHub issues liên quan.

upgrading-expo khác gì so với chỉ hỏi một LLM nâng cấp Expo?

Khác biệt chính nằm ở tính chọn lọc. upgrading-expo skill định hướng mô hình đến các tài liệu migration riêng của Expo mà một prompt chung có thể bỏ sót, đặc biệt quanh expo-av, React 19, React Compiler, Native Tabs và hành vi của New Architecture.

Khi nào không nên dùng upgrading-expo?

Hãy bỏ qua nếu:

• bạn đang bắt đầu một app Expo hoàn toàn mới thay vì nâng cấp app hiện có
• vấn đề của bạn không liên quan đến nâng cấp SDK
• bạn cần một codemod tự động hoặc công cụ CLI migration
• điểm nghẽn chính của bạn là một thư viện native bên thứ ba cụ thể với quy trình migration riêng

upgrading-expo có hỗ trợ preview SDK không?

Có. Skill lưu ý rằng các bản beta dùng hậu tố .preview và được cài từ @next. Điều này hữu ích để thử các thay đổi sắp tới, nhưng với nhu cầu nâng cấp thông thường thì stable vẫn là lựa chọn an toàn hơn.

upgrading-expo chỉ dành cho app managed workflow phải không?

Không. Skill này hữu ích cho cả app Expo managed lẫn app dựa trên prebuild, nhưng prebuild và custom native code sẽ làm tăng khả năng bạn phải thực hiện thêm các bước kiểm tra tương thích thủ công.

Cách cải thiện hiệu quả khi dùng skill upgrading-expo

Hãy nêu chính xác khoảng nâng cấp phiên bản

Cải thiện có giá trị nhất rất đơn giản: hãy nói rõ “từ SDK X lên SDK Y”, thay vì chỉ nói “upgrade Expo”. Phần lớn lời khuyên migration thay đổi đáng kể tùy vào việc bạn có đi qua SDK 53, 54 hay 55 hay không.

Nêu rõ bề mặt package có thể làm thay đổi câu trả lời

Để upgrading-expo cho kết quả tốt hơn, hãy đưa vào các package kích hoạt tài liệu tham chiếu:

• expo-av
• expo-router
• react-native-reanimated
• custom native modules
• bất kỳ package nào đang fail trong expo-doctor

Nhờ vậy, skill có thể đi từ checklist chung sang hướng dẫn sát với các điểm có khả năng ảnh hưởng thật sự.

Dán chẩn đoán thực tế, đừng diễn đạt lại chung chung

Không tốt:

build failed after upgrade

Tốt hơn:

npx expo-doctor says package versions are invalid, Metro reports unresolved import from expo-av, and iOS dev build fails after enabling New Architecture.

Log chính xác giúp skill phân biệt được lỗi lệch dependency với lỗi migration API.

Yêu cầu đầu ra theo mức độ ưu tiên

Một format yêu cầu rất hiệu quả là:

1. các lệnh cần chạy ngay
2. các lỗi có khả năng xảy ra, theo xác suất
3. các file/import cần tìm
4. các bước xác minh sau khi sửa

Cấu trúc này giúp upgrading-expo guide dễ triển khai hơn nhiều khi bạn đang bị áp lực thời gian.

Tách lỗi cài đặt khỏi migration ở mức code

Một kiểu thất bại rất phổ biến là trộn lẫn vấn đề cài package với thay đổi API trong source code. Hãy yêu cầu skill xử lý theo đúng thứ tự:

• căn chỉnh dependency
• đầu ra từ doctor
• reset cache
• migration trong source
• xác minh runtime

Cách này giúp giảm vòng lặp debug lòng vòng.

Yêu cầu các pattern tìm kiếm sát với codebase

Một trong những cách tốt nhất để cải thiện đầu ra của upgrading-expo skill là yêu cầu các mục tiêu tìm kiếm kiểu grep. Ví dụ:

Using the upgrading-expo skill, list the import paths, component names, and hooks I should search for to migrate from expo-av and to verify Native Tabs changes in SDK 55.

Cách này biến hướng dẫn tổng quát thành các tác vụ review code có thể làm ngay.

Xác minh các luồng rủi ro sau lượt đầu tiên

Sau lần nâng cấp đầu tiên, hãy kiểm tra cụ thể:

• phát âm thanh và ghi âm
• phát video
• điều hướng tab
• khởi động trên Expo Go so với dev build
• mọi màn hình dùng animation nặng hoặc native modules

Đây là những vùng dễ lộ ra vấn đề chuyển SDK nhất mà skill đã đề cập.

Lặp lại với prompt follow-up hẹp hơn

Đừng liên tục yêu cầu skill giải toàn bộ bài toán nâng cấp từ đầu. Ở prompt thứ hai, hãy thu hẹp phạm vi:

• “Focus only on React 19 changes in my shared UI package”
• “Focus only on expo-av video migration”
• “Focus only on New Architecture incompatibilities”

Phạm vi nhỏ hơn thường cho ra các bước khắc phục rõ ràng và chính xác hơn.