ویب ایپ میں سفید خالی صفحہ کیسے ٹھیک کریں

سفید خالی صفحہ تقریباً ہمیشہ دو میں سے ایک چیز کا مطلب ہوتا ہے: ایپ کا JavaScript کچھ بنانے سے پہلے کریش ہو گیا، یا JavaScript بالکل لوڈ ہی نہیں ہوا۔ براؤزر کنسول کھولیں (دائیں کلک → Inspect → Console) اور پہلی سرخ خرابی پڑھیں، پھر Network ٹیب میں ان فائلوں کو چیک کریں جو لوڈ نہیں ہوئیں۔ زیادہ تر وجوہات میں environment variable کی کمی، غلط base path، ایک بلڈ جو مکمل نہیں ہوا، یا ایک کمپوننٹ میں کریش شامل ہوتے ہیں۔

یہ گائیڈ React، Vue یا ایسے ہی فریم ورکس سے بنی سنگل پیج ایپس کے بارے میں ہے (AI بلڈرز سے بنی ایپس سمیت)، جہاں خالی صفحے سب سے زیادہ عام ہیں۔

صفحہ سفید کیوں ہے

جدید سنگل پیج ایپ (SPA) براؤزر کو تقریباً خالی HTML فائل بھیجتی ہے، کچھ ایسی:

<body>
  <div id="root"></div>
  <script type="module" src="/assets/index-a1b2c3.js"></script>
</body>

پھر JavaScript اس خالی div کے اندر پوری صفحہ بناتا ہے۔ اگر اسکرپٹ لوڈ نہ ہو، یا رینڈر سے پہلے خرابی پھینکے، تو div خالی رہتا ہے اور آپ کو سفید نظر آتا ہے۔ صفحہ کسی ظاہری طور پر "ٹوٹا" ہوا نہیں ہوتا؛ بس وہ کبھی بنایا ہی نہیں گیا۔

اسی لیے حل ہمیشہ صفحے کے بجائے ڈویلپر ٹولز سے شروع ہوتا ہے۔

مرحلہ 1: کنسول پڑھیں

ڈویلپر ٹولز کھولیں: صفحے پر دائیں کلک کر کے Inspect چنیں، یا F12 دبائیں (میک پر Cmd+Option+I)۔ Console ٹیب پر جائیں اور صفحہ ری لوڈ کریں۔

پہلی سرخ خرابی دیکھیں؛ بعد والی اکثر ضمنی اثرات ہوتی ہیں۔ جو وہ کہتی ہے وہی وجہ کی طرف اشارہ کرتی ہے:

فائل کا نام اور لائن نمبر سمیت پوری خرابی کا متن کاپی کریں۔ اگر آپ AI بلڈر استعمال کر رہے ہیں تو اسے سیدھا چیٹ میں چسپاں کریں۔

مرحلہ 2: چیک کریں کہ فائلیں لوڈ ہوئیں

Network ٹیب کھولیں، Disable cache پر نشان لگائیں، اور ری لوڈ کریں۔ .js اور .css فائلوں کی درخواستیں دیکھیں۔

• JavaScript فائل پر اسٹیٹس 404: صفحہ ایسی فائل مانگ رہا ہے جو سرور پر نہیں۔
• اسٹیٹس 200 مگر قسم text/html: سرور نے اسکرپٹ کے بجائے کوئی صفحہ (اکثر SPA فال بیک کی وجہ سے خود index.html) واپس کیا۔ بنیادی وجہ وہی ہے: فائل وہاں نہیں جہاں صفحہ اسے ڈھونڈ رہا ہے۔

عام وجوہات:

غلط base path۔ اگر ایپ example.com/app/ جیسے ذیلی فولڈر میں پیش ہو رہی ہے، مگر اسے /assets/... سے فائلیں لوڈ کرنے کے لیے بنایا گیا، تو ہر اسکرپٹ درخواست ناکام ہوگی۔ Vite میں یہ vite.config کا base آپشن ہے؛ Create React App میں homepage فیلڈ؛ Next.js میں basePath۔ یہ اس جگہ سے میل کھانا چاہیے جہاں ایپ اصل میں پیش ہو رہی ہے۔

پرانا index.html۔ بلڈ ٹولز فائلوں کے نام میں مواد کا ہیش شامل کرتے ہیں، جیسے index-a1b2c3.js۔ نئے deploy کے بعد پرانی فائل ختم ہو جاتی ہے۔ اگر براؤزر یا CDN میں ابھی تک پرانا index.html کیش ہے تو وہ پرانی فائل مانگتا ہے اور کچھ نہیں ملتا۔ ہارڈ ری فریش (Cmd+Shift+R یا Ctrl+Shift+R) اس کی تصدیق کرتا ہے۔ طویل مدتی حل یہ ہے کہ index.html کو مختصر یا بغیر کیش ہیڈر کے ساتھ دیا جائے، جبکہ ہیش شدہ فائلیں طویل عرصے تک کیش ہوں۔

بلڈ مکمل نہیں ہوا یا deploy نہیں ہوا۔ اگر بلڈ ناکام ہوا تو ہوسٹ پرانا یا خالی آؤٹ پٹ فولڈر پیش کر رہا ہو سکتا ہے۔ بلڈ لاگ میں خرابیاں دیکھیں۔

غلط فولڈر شائع ہوا ہے۔ ہوسٹ کو بلڈ آؤٹ پٹ پیش کرنا چاہیے (عموماً dist یا build)، پروجیکٹ کا سورس فولڈر نہیں۔ سورس پیش کرنے سے ایسا index.html ملتا ہے جو /src/main.tsx کی طرف اشارہ کرتا ہے، جسے براؤزر نہیں چلا سکتے۔

مرحلہ 3: Environment variables چیک کریں

Frontend ایپس اکثر بلڈ کے وقت API URL یا پبلک key جیسی ترتیبات پڑھتی ہیں۔ اگر لائیو بلڈ پر کوئی variable غائب ہو تو createClient(undefined, undefined) جیسا کوڈ فوراً خرابی دیتا ہے، اور صفحہ سفید ہو جاتا ہے۔

یہ باتیں جاننا ضروری ہیں:

• Vite میں صرف VITE_ سے شروع ہونے والے variables براؤزر کوڈ میں دستیاب ہیں، جنہیں import.meta.env.VITE_NAME سے پڑھا جاتا ہے۔ Create React App میں یہ REACT_APP_ ہے؛ Next.js میں NEXT_PUBLIC_۔
• یہ قدریں ایپ بنانے کے وقت شامل ہو جاتی ہیں۔ بلڈ کے بعد variable شامل کرنے سے کچھ نہیں ہوتا جب تک آپ دوبارہ بلڈ اور deploy نہ کریں۔
• پیش نظارہ یا لوکل مشین پر .env فائل ہو سکتی ہے جو پروڈکشن بلڈ کے پاس نہیں ہوتی۔ ہوسٹ پر وہی variables سیٹ کریں۔
• ان prefixes والی ہر چیز عوامی JavaScript میں چلی جاتی ہے۔ وہاں صرف عوامی قدریں رکھیں، کبھی secret keys نہیں۔

ایک فوری ٹیسٹ: کنسول کی خرابی میں کسی ترتیب کے نام کے قریب undefined تلاش کریں، یا پوچھیں:

شائع شدہ ایپ خالی صفحہ دکھاتی ہے۔ frontend جو ہر environment variable پڑھتا ہے اس کی فہرست بنائیں، چیک کریں کہ لائیو بلڈ میں کون سی غائب یا خالی ہیں، اور جب کوئی غائب ہو تو خالی صفحے کے بجائے واضح خرابی کا پیغام دکھائیں۔

مرحلہ 4: کریش ٹھیک کریں

اگر کنسول میں عام JavaScript خرابی ہو تو کوڈ رینڈر کے دوران کریش ہوا۔ AI سے بنی ایپس میں عام وجوہات:

• ڈیٹا ابھی تک لوڈ نہیں ہوا۔ کوئی کمپوننٹ user آنے سے پہلے user.name پڑھتا ہے۔ حل لوڈنگ حالت ہے، یا optional chaining (user?.name)۔
• خالی ڈیٹا۔ نئے اکاؤنٹ میں کوئی ریکارڈ نہیں، اور کوڈ فرض کرتا ہے کہ فہرست میں کم از کم ایک آئٹم ہے۔
• غیر متوقع ڈیٹا کی ساخت۔ API نے وہ فہرست کے بجائے خرابی کا آبجیکٹ واپس کیا جس کی کوڈ کو توقع تھی۔
• غائب import کسی فائل کا نام یا جگہ بدلنے کے بعد۔
• صرف براؤزر والی API کو سرور سائیڈ رینڈرنگ میں استعمال کرنا، جیسے Next.js سرور کمپوننٹ میں window یا localStorage۔

AI کو پوری خرابی، صفحہ، اور یہ بتائیں کہ آپ کس اکاؤنٹ سے لاگ ان تھے:

Dashboard صفحہ نئے صارفین کے لیے خالی ہے۔ کنسول: TypeError: Cannot read properties of undefined (reading 'map') جو ProjectList.tsx:18 پر ہے۔ میرے اکاؤنٹ کے لیے کام کرتا ہے، جس میں پروجیکٹس ہیں۔ اسے ٹھیک کریں تاکہ خالی اکاؤنٹ "ابھی تک کوئی پروجیکٹ نہیں" دکھائے، اور پریویو میں ایک نیا اکاؤنٹ چیک کریں۔

مرحلہ 5: error boundary شامل کریں

React میں ایک کریش ہونے والا کمپوننٹ پوری ایپ کو ہٹا سکتا ہے، اسی لیے ایک چھوٹی سی بگ مکمل طور پر خالی صفحہ بنا دیتی ہے۔ error boundary ایک ایسا کمپوننٹ ہے جو اس کے نیچے کی رینڈرنگ خرابیاں پکڑتا ہے اور اس کے بجائے متبادل دکھاتا ہے۔

مرکزی راستوں کے گرد ایک error boundary شامل کریں جو "کچھ غلط ہو گیا" کے ساتھ Reload بٹن دکھائے، اور خرابی کو کنسول میں لاگ کرے۔ ہیڈر اور نیویگیشن اس کے باہر رکھیں تاکہ وہ پھر بھی رینڈر ہوں۔

یہ بگ ٹھیک نہیں کرتا، مگر زائرین خالی اسکرین کے بجائے پیغام دیکھتے ہیں، اور آپ دیکھ سکتے ہیں کہ کہاں ٹوٹا۔

مرحلہ 6: کوئی خرابی نہیں، پھر بھی خالی

اگر کنسول صاف ہو اور اسکرپٹس لوڈ ہو رہے ہوں:

• Elements ٹیب چیک کریں۔ کیا <div id="root"> کے اندر کچھ ہے؟ اگر ہاں، تو رینڈرنگ ہو رہی ہے مگر نظر نہیں آتی: سفید متن سفید پس منظر پر، opacity: 0، display: none، یا کوئی پوری اسکرین کا عنصر اسے ڈھانپ رہا ہو۔
• راؤٹر چیک کریں۔ اگر موجودہ URL سے کوئی راستہ مماثل نہ ہو اور "not found" راستہ نہ ہو تو کچھ راؤٹرز کچھ بھی رینڈر نہیں کرتے۔ ایک catch-all راستہ شامل کریں جو 404 صفحہ دکھائے۔
• Mount point چیک کریں۔ کوڈ کو ایسے عنصر میں mount ہونا چاہیے جو موجود ہو۔ اگر index.html میں id="app" ہے اور کوڈ root ڈھونڈتا ہے تو کچھ نہیں دکھے گا (اور React عموماً خرابی لاگ کرتا ہے)۔
• براؤزر ایکسٹینشن چیک کریں۔ پرائیویٹ ونڈو میں آزمائیں۔ ایڈ بلاکرز کبھی کبھی analytics یا ads جیسے ناموں والے اسکرپٹس روک دیتے ہیں۔

کیا صرف صفحہ ری فریش کرنے کے بعد خالی ہوتا ہے؟

اگر ہوم پیج کام کرتا ہے مگر /dashboard ری فریش کرنے پر خالی صفحہ یا 404 دکھتا ہے، تو سرور کو معلوم نہیں کہ ایپ کے راستوں کے لیے index.html کیسے بھیجے۔ یہ روٹنگ فال بیک کا مسئلہ ہے، جس پر deploy کے بعد 404 غلطیاں کیسے ٹھیک کریں میں بات کی گئی ہے۔

عام غلطیاں

• پہلی کے بجائے آخری خرابی پڑھنا۔ پہلی سرخ لائن عموماً اصل وجہ ہوتی ہے۔
• بلڈ دوبارہ کیے بغیر environment variables سیٹ کرنا۔ frontend variables بلڈ کے وقت طے ہو جاتے ہیں۔
• صرف اپنے اکاؤنٹ سے ٹیسٹ کرنا۔ خالی اکاؤنٹ کے کریش خالی صفحوں کی سب سے عام وجوہات میں سے ایک ہیں۔
• یہ فرض کرنا کہ deploy کامیاب ہوا۔ کوڈ ڈیبگ کرنے سے پہلے بلڈ لاگ چیک کریں۔
• ہر چیز کا الزام براؤزر کیش پر ڈالنا۔ ہارڈ ری فریش سیکنڈوں میں اسے رد کر دیتا ہے؛ اگر پھر بھی صفحہ خالی ہے تو مسئلہ کچھ اور ہے۔

Mythex میں خالی صفحے

اگر Preview خالی ہو تو پہلے چیک کریں کہ ایپ چل رہی ہے (Code → terminal کھولیں)، پھر Mythex سے درست سرور شروع کرنے کو کہیں، پیش نظارہ ٹول بار میں Refresh کلک کریں، یا /fix استعمال کریں۔ شائع شدہ URL خالی ہو تو دستاویزات تجویز کرتی ہیں کہ ایک منٹ انتظار کریں اور ہارڈ ری فریش کریں، شائع کرنے سے پہلے تصدیق کریں کہ env vars اور ڈیٹا بیس سیٹ ہو چکے ہیں، اور اپنی ہوسٹنگ کی حد چیک کریں۔ یاد رکھیں کہ شائع شدہ ایپ ایک snapshot ہے: کچھ ٹھیک کرنے کے بعد دوبارہ شائع کریں۔ اگر کسی تبدیلی سے یہ ہوا تو آخری درست جواب پر Revert to this point پروجیکٹ کو پیچھے لے جاتا ہے۔ دستاویزات میں Troubleshooting اور Publish troubleshooting دیکھیں، اور عمومی گائیڈ AI سے بنی ایپ کی ڈیبگنگ۔

سفید صفحے کی چیک لسٹ

• کنسول میں پہلی سرخ خرابی پڑھی
• Network ٹیب میں .js/.css فائلیں چیک کیں جو 404 دیں یا HTML واپس کریں
• base path اس جگہ سے میل کھاتا ہے جہاں ایپ پیش ہو رہی ہے
• بلڈ مکمل ہوا، اور شائع ہونے والا بلڈ آؤٹ پٹ فولڈر درست ہے
• لائیو بلڈ پر تمام frontend environment variables سیٹ ہیں، پھر دوبارہ بلڈ کیا
• کریش ٹھیک کیا، بشمول خالی اور نئے اکاؤنٹس کے لیے
• error boundary موجود ہے تاکہ مستقبل کے کریش پیغام دکھائیں
• نامعلوم URLs کے لیے catch-all راستہ
• ہارڈ ری فریش اور پرائیویٹ ونڈو میں ٹیسٹ کیا

سوالات