ওয়েব অ্যাপের ফাঁকা সাদা পেজ কীভাবে ঠিক করবেন

ফাঁকা সাদা পেজ প্রায় সবসময় দুটির একটি বোঝায়: অ্যাপের JavaScript কিছু আঁকার আগেই ক্র্যাশ করেছে, অথবা JavaScript আদৌ লোড হয়নি। ব্রাউজারের কনসোল খুলুন (ডান ক্লিক → Inspect → Console) এবং প্রথম লাল ত্রুটিটি পড়ুন, তারপর Network ট্যাবে যেসব ফাইল লোড হয়নি সেগুলো দেখুন। বেশিরভাগ কারণ হলো একটি অনুপস্থিত এনভায়রনমেন্ট ভেরিয়েবল, ভুল বেস পাথ, শেষ না হওয়া বিল্ড, বা একটি কম্পোনেন্টের ক্র্যাশ।

এই গাইডটি React, Vue বা অনুরূপ ফ্রেমওয়ার্কে বানানো সিঙ্গেল-পেজ অ্যাপ (AI বিল্ডারে বানানো অ্যাপসহ) নিয়ে, যেখানে ফাঁকা পেজ সবচেয়ে বেশি দেখা যায়।

পেজ কেন সাদা থাকে

একটি আধুনিক সিঙ্গেল-পেজ অ্যাপ (SPA) ব্রাউজারে প্রায় ফাঁকা একটি HTML ফাইল পাঠায়, মোটামুটি এরকম:

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

এরপর JavaScript ওই ফাঁকা div-এর ভেতরে পুরো পেজ তৈরি করে। স্ক্রিপ্ট লোড না হলে, অথবা রেন্ডার করার আগেই ত্রুটি ছুঁড়লে, div ফাঁকা থেকে যায় আর আপনি সাদা দেখেন। পেজটি দৃশ্যমানভাবে "ভাঙা" নয়; এটি শুধু কখনো আঁকা হয়নি।

তাই ঠিক করার কাজ সবসময় ডেভেলপার টুলে শুরু হয়, পেজের ভেতরে নয়।

ধাপ ১: কনসোল পড়ুন

ডেভেলপার টুল খুলুন: পেজে ডান ক্লিক করে Inspect বাছুন, অথবা F12 চাপুন (ম্যাকে Cmd+Option+I)। Console ট্যাবে যান এবং পেজ রিলোড করুন।

প্রথম লাল ত্রুটিটি দেখুন; পরেরগুলো প্রায়ই পার্শ্বপ্রতিক্রিয়া। সেটি কী বলছে তাই কারণ নির্দেশ করে:

কনসোল বার্তা (সাধারণ শব্দচয়ন)	এর অর্থ	যাবেন
`Cannot read properties of undefined (reading '...')`	কোড এমন ডেটা আশা করেছিল যা ছিল না	ধাপ ৪
`... is not defined` / `... is not a function`	একটি অনুপস্থিত ইমপোর্ট, ভেরিয়েবল বা সেটিং	ধাপ ৪ বা ধাপ ৩
`Failed to load module script: Expected a JavaScript module script but the server responded with a MIME type of "text/html"`	একটি স্ক্রিপ্টের URL JavaScript-এর বদলে HTML পেজ ফেরত দিয়েছে	ধাপ ২
`Uncaught SyntaxError: Unexpected token '<'`	একই ব্যাপার: JavaScript আশা করা হয়েছিল, পেয়েছে HTML	ধাপ ২
`supabaseUrl is required`, `Missing API key`, বা এর মতো	একটি এনভায়রনমেন্ট ভেরিয়েবল খালি	ধাপ ৩
`Access to fetch ... has been blocked by CORS policy`	অন্য ডোমেইনে অনুরোধ ব্লক হয়েছে	দেখুন CORS ত্রুটি ঠিক করার উপায়
কোনো ত্রুটিই নেই	রেন্ডার কাজ করেছে কিন্তু কিছু দেখাচ্ছে না, অথবা CSS লুকিয়ে রেখেছে	ধাপ ৬

ফাইলের নাম ও লাইন নম্বরসহ সম্পূর্ণ ত্রুটির বার্তা কপি করুন। AI বিল্ডার ব্যবহার করলে সরাসরি চ্যাটে পেস্ট করুন।

ধাপ ২: ফাইলগুলো লোড হয়েছে কি না দেখুন

Network ট্যাব খুলুন, Disable cache টিক দিন, এবং রিলোড করুন। .js ও .css ফাইলের রিকোয়েস্টগুলো দেখুন।

JavaScript ফাইলে স্ট্যাটাস 404: পেজ এমন একটি ফাইল চাইছে যা সার্ভারে নেই।
স্ট্যাটাস 200 কিন্তু টাইপ text/html: স্ক্রিপ্টের বদলে সার্ভার একটি পেজ ফেরত দিয়েছে (প্রায়ই index.html নিজেই, SPA ফলব্যাকের কারণে)। মূল কারণ একই: ফাইলটি পেজ যেখানে আশা করছে সেখানে নেই।

সাধারণ কারণগুলো:

ভুল বেস পাথ। অ্যাপটি যদি example.com/app/-এর মতো সাব-ফোল্ডারে পরিবেশিত হয়, কিন্তু বিল্ড করা হয়েছে /assets/... থেকে ফাইল লোড করার জন্য, তবে প্রতিটি স্ক্রিপ্ট রিকোয়েস্ট মিস হয়। Vite-এ এটি vite.config-এর base অপশন; Create React App-এ homepage ফিল্ড; Next.js-এ basePath। অ্যাপটি আসলে যেখানে পরিবেশিত হচ্ছে সেখানে মিলতে হবে।

পুরনো index.html। বিল্ড টুল ফাইলের নামে কনটেন্ট হ্যাশ দেয়, যেমন index-a1b2c3.js। নতুন ডিপ্লয়ের পর পুরনো ফাইল আর থাকে না। ব্রাউজার বা CDN যদি এখনো পুরনো index.html ক্যাশে রাখে, সে পুরনো ফাইল চায় এবং কিছুই পায় না। হার্ড রিফ্রেশ (Cmd+Shift+R বা Ctrl+Shift+R) এটি নিশ্চিত করে। দীর্ঘমেয়াদী সমাধান হলো index.html-কে একটি ছোট বা কোনো-ক্যাশ হেডারে পরিবেশন করা, আর হ্যাশ করা ফাইলগুলো দীর্ঘ সময় ক্যাশে রাখা।

বিল্ড শেষ হয়নি বা ডিপ্লয় হয়নি। বিল্ড ব্যর্থ হলে হোস্ট হয়তো একটি পুরনো বা খালি আউটপুট ফোল্ডার পরিবেশন করছে। বিল্ড লগে ত্রুটি দেখুন।

ভুল ফোল্ডার প্রকাশিত। হোস্টকে বিল্ড আউটপুট (সাধারণত dist বা build) পরিবেশন করতে হবে, প্রজেক্টের সোর্স ফোল্ডার নয়। সোর্স পরিবেশন করলে এমন index.html মেলে যা /src/main.tsx-এর দিকে নির্দেশ করে, যা ব্রাউজার চালাতে পারে না।

ধাপ ৩: এনভায়রনমেন্ট ভেরিয়েবল যাচাই করুন

ফ্রন্ট এন্ড অ্যাপ প্রায়ই বিল্ড সময়ে একটি API URL বা পাবলিক কী-এর মতো সেটিং পড়ে। লাইভ বিল্ডে কোনো ভেরিয়েবল না থাকলে createClient(undefined, undefined)-এর মতো কোড সঙ্গে সঙ্গে ত্রুটি ছোঁড়ে, আর পেজ সাদা হয়ে যায়।

জানা দরকারি বিষয়:

Vite-এ শুধু VITE_ দিয়ে শুরু হওয়া ভেরিয়েবল ব্রাউজারের কোডে পাওয়া যায়, import.meta.env.VITE_NAME হিসেবে পড়া হয়। Create React App-এ এটি REACT_APP_; Next.js-এ NEXT_PUBLIC_।
এই মানগুলো অ্যাপ বিল্ডের সময় ভেতরে বসে যায়। বিল্ডের পরে ভেরিয়েবল যোগ করলে আবার বিল্ড ও ডিপ্লয় না করা পর্যন্ত কিছু হয় না।
প্রিভিউ বা লোকাল মেশিনে একটি .env ফাইল থাকতে পারে যা প্রোডাকশন বিল্ডে নেই। হোস্টে একই ভেরিয়েবলগুলো সেট করুন।
এই প্রিফিক্সযুক্ত যেকোনো কিছু পাবলিক JavaScript-এ চলে যায়। শুধু পাবলিক মান সেখানে রাখুন, কখনো গোপন কী নয়।

একটি দ্রুত পরীক্ষা: কনসোল ত্রুটিতে কোনো সেটিংয়ের নামের পাশে undefined খুঁজুন, অথবা জিজ্ঞেস করুন:

প্রকাশিত অ্যাপে ফাঁকা পেজ দেখাচ্ছে। ফ্রন্ট এন্ডের পড়া প্রতিটি এনভায়রনমেন্ট ভেরিয়েবলের তালিকা দাও, লাইভ বিল্ডে কোনগুলো নেই বা খালি তা যাচাই করো, আর কোনো একটি না থাকলে পেজ ফাঁকা না দেখিয়ে একটি স্পষ্ট ত্রুটি বার্তা দেখাও।

ধাপ ৪: ক্র্যাশ ঠিক করুন

কনসোলে স্বাভাবিক একটি JavaScript ত্রুটি দেখালে রেন্ডার করার সময় কোড ক্র্যাশ করেছে। AI দিয়ে বানানো অ্যাপে সাধারণ কারণ:

ডেটা এখনো লোড হয়নি। user আসার আগেই একটি কম্পোনেন্ট user.name পড়ছে। সমাধান হলো লোডিং অবস্থা, অথবা optional chaining (user?.name)।
খালি ডেটা। নতুন অ্যাকাউন্টে কোনো রেকর্ড নেই, কিন্তু কোড ধরে নিচ্ছে তালিকায় অন্তত একটি আইটেম আছে।
অপ্রত্যাশিত ডেটার আকার। একটি API তালিকার বদলে একটি ত্রুটি অবজেক্ট ফেরত দিয়েছে, যা কোড আশা করেনি।
একটি অনুপস্থিত ইমপোর্ট, ফাইলের নাম বদলানো বা সরানোর পর।
সার্ভার-সাইড রেন্ডারিং-এ শুধু ব্রাউজারের API ব্যবহার, যেমন Next.js সার্ভার কম্পোনেন্টে window বা localStorage।

AI-কে সম্পূর্ণ ত্রুটি, পেজ, আর আপনি কোন অ্যাকাউন্টে লগইন ছিলেন তা দিন:

নতুন ব্যবহারকারীদের জন্য ড্যাশবোর্ড পেজ ফাঁকা। কনসোল: TypeError: Cannot read properties of undefined (reading 'map') ProjectList.tsx:18-এ। আমার অ্যাকাউন্টে প্রজেক্ট থাকায় এটি কাজ করে। খালি অ্যাকাউন্টে যেন "কোনো প্রজেক্ট নেই" দেখায় এমনভাবে ঠিক করো, আর প্রিভিউয়ে একটি নতুন অ্যাকাউন্ট দিয়ে যাচাই করো।

ধাপ ৫: একটি error boundary যোগ করুন

React-এ একটি ক্র্যাশিং কম্পোনেন্ট পুরো অ্যাপকে আনমাউন্ট করে দিতে পারে, তাই একটি ছোট বাগও পুরো ফাঁকা পেজ তৈরি করে। error boundary হলো এমন একটি কম্পোনেন্ট যা তার নিচের রেন্ডারিং ত্রুটি ধরে তার বদলে একটি ফলব্যাক দেখায়।

মূল রুটগুলোর চারপাশে একটি error boundary যোগ করো, যা "Something went wrong" আর একটি Reload বোতাম দেখায় এবং ত্রুটিটি কনসোলে লগ করে। হেডার ও নেভিগেশন বাইরে রাখো যাতে সেগুলো তবু রেন্ডার হয়।

এটি বাগ ঠিক করে না, কিন্তু দর্শকরা একটি বার্তা দেখেন ফাঁকা স্ক্রিনের বদলে, আর আপনি জানেন কোথায় ভেঙেছে।

ধাপ ৬: কোনো ত্রুটি নেই, তবু ফাঁকা

কনসোল পরিষ্কার থাকলে এবং স্ক্রিপ্ট লোড হলে:

Elements ট্যাব দেখুন। <div id="root">-এর ভেতরে কনটেন্ট আছে কি? থাকলে রেন্ডার হচ্ছে কিন্তু অদৃশ্য: সাদার ওপর সাদা লেখা, opacity: 0, display: none, অথবা পুরো স্ক্রিন ঢেকে রাখা একটি উপাদান।
রাউটার দেখুন। বর্তমান URL-এর সঙ্গে কোনো রুট না মিললে এবং কোনো "not found" রুট না থাকলে কিছু রাউটার কিছুই রেন্ডার করে না। একটি catch-all রুট যোগ করুন যা 404 পেজ দেখায়।
মাউন্ট পয়েন্ট দেখুন। কোড এমন একটি উপাদানে মাউন্ট করতে হবে যা আছে। index.html-এ id="app" থাকলে কিন্তু কোড root খুঁজলে কিছুই দেখা যাবে না (এবং React সাধারণত একটি ত্রুটি লগ করে)।
ব্রাউজার এক্সটেনশন দেখুন। একটি প্রাইভেট উইন্ডোতে চেষ্টা করুন। অ্যাড ব্লকার মাঝেমধ্যে analytics বা ads-এর মতো নামের স্ক্রিপ্ট ব্লক করে।

শুধু পেজ রিফ্রেশ করার পরই ফাঁকা?

হোম পেজ কাজ করলেও /dashboard রিফ্রেশ করলে ফাঁকা পেজ বা 404 দেখালে, সার্ভার জানে না অ্যাপ রুটের জন্য index.html পাঠাতে হবে। এটি রাউটিং ফলব্যাকের সমস্যা, যা ডিপ্লয়ের পর 404 এরর কীভাবে ঠিক করবেন-এ আলোচিত।

সাধারণ ভুলগুলো

প্রথম ত্রুটির বদলে শেষটি পড়া। প্রথম লাল লাইনটিই সাধারণত কারণ।
বিল্ড না করে এনভায়রনমেন্ট ভেরিয়েবল সেট করা। ফ্রন্ট এন্ডের ভেরিয়েবল বিল্ড সময়ে স্থির হয়ে যায়।
শুধু নিজের অ্যাকাউন্ট দিয়ে পরীক্ষা করা। খালি অ্যাকাউন্টের ক্র্যাশ ফাঁকা পেজের সবচেয়ে সাধারণ কারণগুলোর একটি।
ডিপ্লয় কাজ করেছে ধরে নেওয়া। কোড ডিবাগ করার আগে বিল্ড লগ দেখুন।
সবকিছুর জন্য ব্রাউজার ক্যাশকে দোষ দেওয়া। হার্ড রিফ্রেশ সেটি কয়েক সেকেন্ডে বাদ দেয়; পেজ তবু ফাঁকা থাকলে কারণ অন্য কিছু।

Mythex-এ ফাঁকা পেজ

Preview ফাঁকা থাকলে আগে নিশ্চিত হন অ্যাপ চলছে (Code → terminal খুলুন), তারপর Mythex-কে সঠিক সার্ভার চালু করতে বলুন, প্রিভিউ টুলবারের Refresh ক্লিক করুন, অথবা /fix ব্যবহার করুন। প্রকাশিত URL ফাঁকা হলে ডকস পরামর্শ দেয় এক মিনিট অপেক্ষা করতে ও হার্ড-রিফ্রেশ দিতে, প্রকাশের আগে এনভায়রনমেন্ট ভেরিয়েবল ও ডেটাবেস ঠিকভাবে সেট হয়েছে কি না নিশ্চিত হতে, আর আপনার হোস্টিং সীমা যাচাই করতে। মনে রাখবেন প্রকাশিত অ্যাপ একটি স্ন্যাপশট: কিছু ঠিক করার পর আবার প্রকাশ করুন। কোনো পরিবর্তন এটি ঘটিয়ে থাকলে শেষ ভালো উত্তরের Revert to this point প্রজেক্টটি আগের অবস্থায় ফিরিয়ে দেয়। ডকসে দেখুন সমস্যা সমাধান এবং প্রকাশের সমস্যা সমাধান, আর সাধারণভাবে AI দিয়ে বানানো অ্যাপের ডিবাগ করা গাইডটি।

ফাঁকা পেজ চেকলিস্ট

কনসোলের প্রথম লাল ত্রুটিটি পড়া হয়েছে
Network ট্যাবে 404 হওয়া বা HTML ফেরত দেওয়া .js/.css ফাইল দেখা হয়েছে
বেস পাথ যেখানে অ্যাপ পরিবেশিত হচ্ছে তার সঙ্গে মেলে
বিল্ড শেষ হয়েছে, এবং প্রকাশিত ফোল্ডার বিল্ড আউটপুটের
লাইভ বিল্ডে সব ফ্রন্ট এন্ড এনভায়রনমেন্ট ভেরিয়েবল সেট, তারপর পুনরায় বিল্ড
ক্র্যাশ ঠিক হয়েছে, খালি ও নতুন অ্যাকাউন্টসহ
ভবিষ্যৎ ক্র্যাশ যেন বার্তা দেখায় সেজন্য error boundary আছে
অজানা URL-এর জন্য catch-all রুট আছে
হার্ড রিফ্রেশ ও একটি প্রাইভেট উইন্ডোতে পরীক্ষা করা হয়েছে

প্রশ্নোত্তর

আমার React অ্যাপ কেন ফাঁকা সাদা পেজ দেখায়?

সাধারণত কিছু আঁকার আগেই JavaScript ক্র্যাশ করেছে, অথবা JavaScript ফাইলটি আদৌ লোড হয়নি। ব্রাউজারের কনসোল খুলুন: সেখানে লাল একটি ত্রুটি বলে দেবে কোনটি, আর কোন ফাইলের কোন লাইনে ঘটেছে।

লোকালে অ্যাপ ঠিক চলে, কিন্তু ডিপ্লয়ের পর ফাঁকা পেজ দেখায় কেন?

সবচেয়ে সাধারণ কারণ হলো লাইভ বিল্ডের জন্য কখনো সেট না হওয়া এনভায়রনমেন্ট ভেরিয়েবল, ভুল পাথ থেকে JavaScript ও CSS ফাইল চাওয়া (বেস পাথের অমিল), আর পুরনো ক্যাশ করা index.html যা আর নেই এমন ফাইলের দিকে নির্দেশ করে।

'Failed to load module script' মানে কী?

ব্রাউজার একটি JavaScript ফাইল চেয়েছিল, কিন্তু তার বদলে একটি HTML পেজ পেয়েছে, সাধারণত সাইটের index.html বা একটি ত্রুটির পেজ। ফাইলের পাথ ভুল অথবা সার্ভারে ফাইলটি নেই, তাই বিল্ড আউটপুট ও অ্যাপের বেস পাথ সেটিং যাচাই করুন।

একটি বাগ যেন পুরো পেজকে ফাঁকা না করে, তা কীভাবে আটকাব?

একটি error boundary যোগ করুন। React-এ error boundary হলো এমন একটি কম্পোনেন্ট যা তার নিচের অংশের রেন্ডারিং ত্রুটি ধরে সবকিছু আনমাউন্ট করার বদলে একটি ফলব্যাক বার্তা দেখায়।