diff --git a/.github/ISSUE_TEMPLATE/BUG_REPORT.yml b/.github/ISSUE_TEMPLATE/BUG_REPORT.yml index b489dbe17..bdcf5e2be 100644 --- a/.github/ISSUE_TEMPLATE/BUG_REPORT.yml +++ b/.github/ISSUE_TEMPLATE/BUG_REPORT.yml @@ -87,5 +87,7 @@ body: options: - label: I am using Expo - label: I am using Nitrogen (nitro-codegen) + - label: I have read and followed the [Troubleshooting Guide](https://nitro.margelo.com/troubleshooting). + required: true - label: I searched for [similar issues in this repository](https://github.com/mrousavy/nitro/issues) and found none. required: true diff --git a/.github/ISSUE_TEMPLATE/BUILD_ERROR.yml b/.github/ISSUE_TEMPLATE/BUILD_ERROR.yml index 1a494b807..abcc927af 100644 --- a/.github/ISSUE_TEMPLATE/BUILD_ERROR.yml +++ b/.github/ISSUE_TEMPLATE/BUILD_ERROR.yml @@ -92,5 +92,7 @@ body: options: - label: I am using Expo - label: I am using Nitrogen (nitro-codegen) + - label: I have read and followed the [Troubleshooting Guide](https://nitro.margelo.com/troubleshooting). + required: true - label: I searched for [similar issues in this repository](https://github.com/mrousavy/nitro/issues) and found none. required: true diff --git a/.github/ISSUE_TEMPLATE/NITROGEN_ERROR.yml b/.github/ISSUE_TEMPLATE/NITROGEN_ERROR.yml index 273329464..96518621e 100644 --- a/.github/ISSUE_TEMPLATE/NITROGEN_ERROR.yml +++ b/.github/ISSUE_TEMPLATE/NITROGEN_ERROR.yml @@ -66,5 +66,7 @@ body: label: Additional information description: Please check all the boxes that apply options: + - label: I have read and followed the [Troubleshooting Guide](https://nitro.margelo.com/troubleshooting). + required: true - label: I searched for [similar issues in this repository](https://github.com/mrousavy/nitro/issues) and found none. required: true diff --git a/docs/docs/troubleshooting.md b/docs/docs/troubleshooting.md new file mode 100644 index 000000000..7c7e95afd --- /dev/null +++ b/docs/docs/troubleshooting.md @@ -0,0 +1,94 @@ +--- +--- + +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + +# Troubleshooting + +This guide helps you troubleshoot issues in Nitro and should give you enough context to open a well-formed issue, even if you're not a native developer. + +## Minimum requirements + +First, make sure you meet the minimum requirements for Nitro: + + + + - react-native 0.75 or higher + - Xcode 16 or higher + + + - react-native 0.75 or higher + - `compileSdkVersion` 34 or higher + + + +## Build error + +If your app fails to build after installing Nitro or a library powered by Nitro, make sure to post full build logs: + + + + + 1. Build the app with Xcode. + 2. When the build fails in Xcode, open the "Report Navigator" tab from within the left sidebar: + + Report Navigator tab in Xcode + + 3. Then, find the most recent build attempt and click on "Build": + + Last build report in Xcode + + 4. Scroll through the build report and find the step(s) that failed to build. They usually have a ❌ icon on the left. Click on the parent item's hamburger menu on the right to open the full logs: + + Error line in the build report + + 5. Scroll down through the build logs (the long part is just the command invocation) to find the actual error messages: + + Bottom of error logs + + 6. Copy those bottom logs only (not the build command invocation above) and create a GitHub issue with that. + + + + + 1. Build the app with Android Studio. + 2. When the build fails in Android Studio, open the "Build" tab from within the bottom left sidebar: + + Build tab in Android Studio + + 3. Find the top-most entry in the Build window (which contains full unfiltered logs) and click it: + + Build tab in Android Studio + + 4. Copy those full logs and paste them in the GitHub issue (or serve via pastebin). Make sure they actually contain the **error** message and not just something like "BUILD FAILED in 7s" (which is what most people post): + + Build logs in Android Studio + + + + +## Runtime error + +If your app crashes at runtime, make sure to inspect the native logs. + + + + + 1. Run your app through Xcode + 2. If the app hits an unhandled error, it should pause in Xcode. Share the line it stopped in, and also the call-stack (stacktrace) on the left side. + 3. If the app didn't pause, then it might have been a handled error - in this case just check the Xcode logs at the bottom: + + Bottom of runtime logs + + + + + 1. Run your app through Android Studio by using the Debug button (🪲) + 2. If the app hits an unhandled error, it should pause in Android Studio. Share the line it stopped in, and also the call-stack (stacktrace) on the bottom window. + 3. If the app didn't pause, then it might have been a handled error - in this case just check the Android Logcat logs at the bottom: + + Bottom of runtime logs + + + diff --git a/docs/sidebars.ts b/docs/sidebars.ts index a8ac27783..6478b2b40 100644 --- a/docs/sidebars.ts +++ b/docs/sidebars.ts @@ -46,6 +46,7 @@ const sidebars: SidebarsConfig = { 'entry-point', 'comparison', 'for-users', + 'troubleshooting', ], }; diff --git a/docs/static/img/troubleshoot-android-1.png b/docs/static/img/troubleshoot-android-1.png new file mode 100644 index 000000000..8a809e2e1 Binary files /dev/null and b/docs/static/img/troubleshoot-android-1.png differ diff --git a/docs/static/img/troubleshoot-android-2.png b/docs/static/img/troubleshoot-android-2.png new file mode 100644 index 000000000..8446e0d95 Binary files /dev/null and b/docs/static/img/troubleshoot-android-2.png differ diff --git a/docs/static/img/troubleshoot-android-3.png b/docs/static/img/troubleshoot-android-3.png new file mode 100644 index 000000000..69af993a0 Binary files /dev/null and b/docs/static/img/troubleshoot-android-3.png differ diff --git a/docs/static/img/troubleshoot-android-logs.png b/docs/static/img/troubleshoot-android-logs.png new file mode 100644 index 000000000..2bd9d0688 Binary files /dev/null and b/docs/static/img/troubleshoot-android-logs.png differ diff --git a/docs/static/img/troubleshoot-xcode-1.png b/docs/static/img/troubleshoot-xcode-1.png new file mode 100644 index 000000000..8a52d1691 Binary files /dev/null and b/docs/static/img/troubleshoot-xcode-1.png differ diff --git a/docs/static/img/troubleshoot-xcode-2.png b/docs/static/img/troubleshoot-xcode-2.png new file mode 100644 index 000000000..eed697b9f Binary files /dev/null and b/docs/static/img/troubleshoot-xcode-2.png differ diff --git a/docs/static/img/troubleshoot-xcode-3.png b/docs/static/img/troubleshoot-xcode-3.png new file mode 100644 index 000000000..3913308b8 Binary files /dev/null and b/docs/static/img/troubleshoot-xcode-3.png differ diff --git a/docs/static/img/troubleshoot-xcode-4.png b/docs/static/img/troubleshoot-xcode-4.png new file mode 100644 index 000000000..2bfe2cf13 Binary files /dev/null and b/docs/static/img/troubleshoot-xcode-4.png differ diff --git a/docs/static/img/troubleshoot-xcode-logs.png b/docs/static/img/troubleshoot-xcode-logs.png new file mode 100644 index 000000000..fc753cae0 Binary files /dev/null and b/docs/static/img/troubleshoot-xcode-logs.png differ