From 5c3cdd2c4289cc452da4c688f43c7427c3d30623 Mon Sep 17 00:00:00 2001 From: RaffyLeong Date: Tue, 11 Nov 2025 23:32:35 +0800 Subject: [PATCH] docs: add comprehensive troubleshooting guide --- TROUBLESHOOTING.md | 40 ++++++++++++++++++++++++++++++++++++++++ 1 file changed, 40 insertions(+) create mode 100644 TROUBLESHOOTING.md diff --git a/TROUBLESHOOTING.md b/TROUBLESHOOTING.md new file mode 100644 index 00000000..f7b291f6 --- /dev/null +++ b/TROUBLESHOOTING.md @@ -0,0 +1,40 @@ +# Troubleshooting Guide + +## Common Installation Issues + +### App won't install on Windows 10 +**Problem**: Installation fails or gets blocked +**Solution**: +- Temporarily disable Windows Defender during installation +- Try downloading the installer directly from the releases page +- Run installer as Administrator + +### Dependencies fail to install +**Problem**: `yarn install` fails with errors +**Solution**: +- Clear node_modules: `rm -rf node_modules` +- Use legacy peer deps: `yarn install --legacy-peer-deps` +- Ensure you have Node.js 16+ installed + +## Common Runtime Errors + +### App crashes when visiting specific sites (like Twitter) +**Problem**: App crashes when navigating to certain websites +**Solution**: +- This is a known issue being worked on +- Temporary workaround: Avoid those specific sites in Responsively + +### Blank screen with Next.js applications +**Problem**: Shows blank screen when loading local Next.js apps +**Solution**: +- Use your local IP address instead of localhost +- Example: Use `http://192.168.0.100:3000` instead of `http://localhost:3000` + +## Performance Issues + +### App runs slowly with multiple devices +**Problem**: Performance degrades with many device previews +**Solution**: +- Reduce the number of simultaneous device previews +- Close other memory-intensive applications +- Restart the app periodically