এই ডকুমেন্টটি আপনার জন্য সম্পূর্ণ টেকনিক্যাল ও ফাংশনাল গাইড। আপনি যদি পিএইচপি বা লারাভেল ব্যাকগ্রাউন্ডের হয়ে থাকেন, তবে এই ফাইলটি পড়লে নোড জেএস (Node.js) ও নেক্সট জেএস (Next.js)-এর নাড়িনক্ষত্র পানির মতো পরিষ্কার হয়ে যাবে। ক্লায়েন্ট বা কোনো সিনিয়র ডেভেলপার যেকোনো টেকনিক্যাল প্রশ্ন জিজ্ঞাসা করলে আপনি আত্মবিশ্বাসের সাথে উত্তর দিতে পারবেন।
এই প্রজেক্টটি একটি আধুনিক Headless eCommerce System। ঐতিহ্যবাহী মনোলিথিক ওয়ার্ডপ্রেসের মতো থিম দিয়ে সাইট লোড হয় না। ওয়ার্ডপ্রেস কেবল ব্যাকএন্ড ডাটাবেস ও সিএমএস হিসেবে থাকে, আর নেক্সট জেএস ফ্রন্টএন্ডে আল্ট্রা-ফাস্ট ইউজার ইন্টারফেস ডেলিভার করে।
WooCommerce + Rosée Belle Helper Plugin। প্রোডাক্ট, স্টক, অর্ডার, কুপন এবং হোমপেজের সেটিংস (ব্যানার, ক্যাটাগরি স্লাগ) এখান থেকেই ম্যানেজ হয়। এটি শুধু JSON API এক্সপোজ করে।
App Router + React 18 + TypeScript। এটি সার্ভার সাইড রেন্ডারিং (SSR) এবং ইনক্রিমেন্টাল স্ট্যাটিক রিজেনারেশন (ISR) দিয়ে সুপারফাস্ট ক্যাশড HTML জেনারেট করে।
Phusion Passenger দিয়ে Node.js রুট রান হয় server.js ফাইলের মাধ্যমে। স্ট্যাটিক ফাইলগুলো _next/static থেকে সরাসরি লাইটস্পিড ক্যাশে সার্ভ হয়।
প্রতি ৬০ সেকেন্ড পর পর ব্যাকগ্রাউন্ডে ডাটা রিভ্যালিডেট হয়। ওয়ার্ডপ্রেস যদি কিছুক্ষণের জন্য ডাউনও থাকে, সাইট কখনোই ক্র্যাশ করবে না; ক্যাশড ডাটা থেকে লাইভ থাকবে।
সহজ লারাভেল উদাহরণ:
• PHP যেমন একটি প্রোগ্রামিং ল্যাঙ্গুয়েজ এবং PHP-FPM / CLI যেমন রানটাইম ইঞ্জিন,
• তেমনি JavaScript হলো ল্যাঙ্গুয়েজ এবং Node.js হলো সেই জাভাস্ক্রিপ্ট রান করার সার্ভার ইঞ্জিন।
• আর পিএইচপিতে যেমন সম্পূর্ণ ফুল-স্ট্যাক ফ্রেমওয়ার্ক হলো Laravel, ঠিক তেমনি নোড জেএসের উপর তৈরি আল্ট্রা-মডার্ন ফ্রেমওয়ার্ক হলো Next.js!
| বৈশিষ্ট্য | Node.js (ইঞ্জিন) | Next.js (ফ্রেমওয়ার্ক) |
|---|---|---|
| কী এটা? | জাভাস্ক্রিপ্ট সার্ভার রানটাইম (যেমন: PHP) | রিঅ্যাক্ট ভিত্তিক ফুল-স্ট্যাক ফ্রেমওয়ার্ক (যেমন: Laravel) |
| রাউটিং | ম্যানুয়ালি কোড লিখে বানাতে হয় | ফাইল-বেসড রাউটিং (ফোল্ডার বানাইলেই অটোমেটিক রুট হয়ে যায়) |
| এসএসআর ও এসইও | নিজে কনফিগার করতে শত শত লাইন কোড লাগে | বিল্ট-ইন Server Components + ISR + মেটাডাটা অপ্টিমাইজেশন |
| আমাদের প্রজেক্টে ভূমিকা | আমাদের সার্ভারে কোডটিকে বাঁচিয়ে রাখে (ইভেন্ট লুপ) | ইউজার ইন্টারফেস, পেজ, কার্ট এবং এপিআই পরিচালনা করে |
সাধারণ ওয়ার্ডপ্রেসে হেড (ফ্রন্টএন্ড UI/Theme) এবং বডি (ডাটাবেস ও অ্যাডমিন) একসাথে জোড়া লাগানো থাকে। ফলে ওয়ার্ডপ্রেসের ভারি থিম, জেকোয়েরি এবং প্লাগইনের কারণে পেজ স্পিড কমে যায়।
হেডলেস সিস্টেমের মূল লজিক:
১. আমরা ওয়ার্ডপ্রেস থিম সম্পূর্ণ বর্জন করেছি।
২. ওয়ার্ডপ্রেস শুধু ব্যাকএন্ড ডাটাবেস ও স্টোরেজ হিসেবে থাকে (অ্যাডমিন শুধু অর্ডার দেখতে ও প্রোডাক্ট আপলোড করতে WP-Admin ব্যবহার করেন)।
৩. ফ্রন্টএন্ডে নেক্সট জেএস দিয়ে রিঅ্যাক্ট অ্যাপ্লিকেশন চলে, যা ওয়ার্ডপ্রেসের সাথে শুধুমাত্র লাইটওয়েট REST API / WPGraphQL দিয়ে যোগাযোগ করে।
cPanel ও LiteSpeed সার্ভারের নিয়ম:
সাধারণত Vercel বা নিজস্ব ভিপিএস-এ npm start দিলে একটি নির্দিষ্ট পোর্ট (যেমন 3000) লিসেন করে। কিন্তু cPanel এর CloudLinux / Phusion Passenger এনভায়রনমেন্টে পোর্ট ফিক্সড থাকে না; প্যাসেঞ্জার সার্ভার নিজে একটি ডায়নামিক পোর্ট বা ইউনিক্স সকেট ফাইল নির্ধারণ করে দেয় (process.env.PORT অথবা passenger.sock)।
server.js ব্যবহার করায় এটি cPanel Node.js সিলেক্টরের সাথে ১০০% কমপ্যাটিবল হয়ে স্বয়ংক্রিয়ভাবে বুট হতে পারে।
কখনোই না! এটি এই সিস্টেমের সবচেয়ে শক্তিশালী দিক (Resilient Architecture)।
আমাদের src/lib/wpgraphql.ts এবং src/lib/settings.ts ফাইলে Triple-Layer Fallback Mechanism কোড করা আছে:
ঐতিহ্যবাহী ওয়ার্ডপ্রেসে কার্ট কুকি ও ডাটাবেস সেশন ব্যবহার করে, যার কারণে সার্ভার স্লো হয়ে যায়।
আমাদের সিস্টেমে আধুনিক ক্লায়েন্ট-সাইড কার্ট আর্কিটেকচার:
• সম্পূর্ণ কার্ট পরিচালিত হয় CartContext.tsx এর মাধ্যমে রিঅ্যাক্ট স্টেট ও ব্রাউজারের localStorage-এ।
• ইউজার যখন পেজ রিলোড দেয় বা নতুন ট্যাবে যায়, ব্রাউজারের লোকালস্টোরেজ থেকে কার্ট আইটেম তাৎক্ষণিক পুনরুদ্ধার হয় (০ মিলিসেকেন্ডে)।
• সার্ভারে কোনো অতিরিক্ত রিকোয়েস্ট পাঠাতে হয় না, ফলে ট্রাফিক যত বাড়ুক সার্ভার কখনোই স্লো হয় না।
চেকআউট প্রক্রিয়াটি সর্বোচ্চ সিকিউরিটির সাথে সার্ভার-টু-সার্ভার রুট হ্যান্ডলারের মাধ্যমে সম্পন্ন হয়:
/checkout পেজে ফর্ম ফিলাপ করে "Order Confirm" এ চাপ দেয়।/api/checkout।/wp-json/wc/v3/orders)-এ অথেনটিকেটেড রিকোয়েস্ট পাঠায়।order_id রিটার্ন করে।/order-received/[order_id] পেজে রিডাইরেক্ট করে দেয়।.env.production ফাইলে এনক্রিপ্টেড থাকে।
লারাভেলের ক্যাশিংয়ের সাথে তুলনা: লারাভেলে আমরা যেমন Cache::remember('products', 60, ...) ব্যবহার করি, নেক্সট জেএসে তারই স্বয়ংক্রিয় পেজ-লেভেল রূপ হলো ISR।
যখন ফাইলে লেখা থাকে export const revalidate = 60;:
Next.js ফোল্ডার লক্ষ্য করুন: src/app/category/[slug]/page.tsx।
ব্র্যাকেট [slug] হলো নেক্সট জেএসের একটি Universal Wildcard Parameter।
/category/combo তে ঢুকবে, নেক্সট জেএস অটোমেটিক ধরে নেয় slug = "combo"।getProducts({ category: 'combo' })।Next.js 14-এ ডিফল্টভাবে সব কম্পোনেন্ট হলো Server Component।
| ফিচার | Server Component (যেমন: page.tsx) | Client Component (যেমন: 'use client') |
|---|---|---|
| কোথায় এক্সিকিউট হয়? | শুধুমাত্র সার্ভারে (Node.js এনভায়রনমেন্টে) | সার্ভারে প্রি-রেন্ডার হয় + ব্রাউজারে ইন্টারঅ্যাক্ট করে |
| ব্রাউজার বান্ডেল সাইজ | ০ কিলোবাইট জাভাস্ক্রিপ্ট ব্রাউজারে পাঠায় | রিঅ্যাক্ট জাভাস্ক্রিপ্ট কোড ব্রাউজারে যায় |
| কখন ব্যবহার করবেন? | ডাটা ফেচিং, এসইও মেটাডাটা, সিক্রেট কি হ্যান্ডলিং | useState, useEffect, ক্লিক ইভেন্ট, লোকালস্টোরেজ |
| লারাভেল তুলনা | খাঁটি Blade View ফাইল | Blade ফাইলের ভেতরে থাকা Vue/React উইজেট |
আমাদের ওয়ার্ডপ্রেস প্লাগইনটি (wp-plugin/rosee-belle-core) একটি কেন্দ্রীয় কন্ট্রোল প্যানেল হিসেবে কাজ করে।
প্লাগইনের মাধ্যমে অ্যাডমিন যা কন্ট্রোল করেন:
• হোমপেজ হিরো ব্যানার, টেক্সট, বাটন ও ইমেজ।
• "Shop by Category" এর আইটেম লিস্ট, সিরিয়াল ও থাম্বনেইল।
• "Shop by Concern" ও ফিচার্ড ব্র্যান্ড লিস্ট।
• হেডার ও ফুটারের হোয়াটসঅ্যাপ নম্বর, হেল্পলাইন ফোন, ইমেইল, ঠিকানা এবং কুইক লিঙ্কস।
প্লাগইনটি ওয়ার্ডপ্রেসে একটি পাবলিক REST রুট তৈরি করে: /wp-json/roseebelle/v1/settings। নেক্সট জেএস src/lib/settings.ts ফাইলের মাধ্যমে এই এপিআই থেকে JSON ফেচ করে সব পেজে রেন্ডার করে।
নেক্সট জেএসের গ্লোবাল রুট লেআউট ফাইলে (src/app/layout.tsx) হেডার ও ফুটার একবারই কল করা আছে:
যেহেতু লেআউট ফাইলে getStoreSettings() কল হয়, তাই অ্যাডমিন প্লাগইন থেকে ফোন নম্বর বা ব্যানার আপডেট করলে পুরো সাইটের হেডার ও ফুটারে স্বয়ংক্রিয়ভাবে তা আপডেট হয়ে যায়।
Next.js 14-এর বিল্ট-ইন Metadata API ব্যবহার করা হয়েছে:
src/app/product/[slug]/page.tsx) generateMetadata() ফাংশন রয়েছে। এটি প্রোডাক্টের নাম, মূল্য, ব্র্যান্ড এবং ছবি অনুযায়ী স্বয়ংক্রিয়ভাবে Google Meta Title, Description এবং Facebook Share Image (OpenGraph) তৈরি করে।<script type="application/ld+json">)।
সাধারণত নেক্সট জেএস বিল্ড ফাইল রাখে .next/static ফোল্ডারে।
কিন্তু cPanel এবং LiteSpeed ওয়েব সার্ভারের .htaccess ফাইলে একটি সিকিউরিটি কনফিগারেশন থাকে যা ডট (.) দিয়ে শুরু হওয়া ডিরেক্টরি সরাসরি ব্রাউজারে সার্ভ করতে বাধা দেয় বা 403 Forbidden দেয়।
copy-static.js স্ক্রিপ্টটি বিল্ডের পরপরই .next/static থেকে সব সিএসএস ও জাভাস্ক্রিপ্ট কপি করে _next/static ফোল্ডারে ডুপ্লিকেট করে দেয়। এর ফলে লাইটস্পিড ক্যাশে কোনো 404/403 ছাড়া লাইটস্পিড গতিতে স্ট্যাটিক ফাইল লোড হতে পারে।
প্রোডাক্টের সব হাই-রেজোলিউশন ইমেজ সরাসরি ওয়ার্ডপ্রেসের মিডিয়া লাইব্রেরি (https://roseebelle.com/wp-content/uploads/...) থেকে আসে।
পারফরম্যান্স ট্রিকস:
• আমরা ইমেজগুলোতে loading="lazy" এবং decoding="async" সেট করেছি যাতে স্ক্রিন স্ক্রল করার আগে ইমেজ লোড হয়ে নেটওয়ার্ক ব্লক না করে।
• কোনো ইমেজ যদি ওয়ার্ডপ্রেসে মিসিং থাকে বা ডিলিট হয়ে যায়, তবে ব্রাউজার যেন ভাঙা ছবি না দেখায় সেজন্য onError হ্যান্ডলার স্বয়ংক্রিয়ভাবে লোকাল প্লেসহোল্ডার ইমেজ (/images/placeholder.png) দেখিয়ে দেয়।
বাংলাদেশে ক্যাশ অন ডেলিভারিতে সবচেয়ে বড় সমস্যা হলো ভুয়া অর্ডার ও ডেলিভারি রিটার্ন। আমাদের চেকআউট পেজে একটি ইন-হাউজ ভেরিফিকেশন লজিক যুক্ত করা আছে:
/api/fraud-check কুরিয়ার বা অর্ডার হিস্ট্রি চেক করে কোনো অস্বাভাবিক অর্ডার প্যাটার্ন বা ব্লকলিস্টেড নম্বর আছে কিনা তা ফ্ল্যাগ করে।ই-কমার্সের প্রধান ভিত্তি হলো সঠিক মার্কেটিং ট্র্যাকিং। আমাদের প্রজেক্টে ডেডিকেটেড ট্র্যাকিং আর্কিটেকচার রয়েছে:
TrackViewItemList.tsx কম্পোনেন্ট ক্যাটাগরি বা ব্র্যান্ড পেজ ওপেন হওয়া মাত্রই GTM ডাটা-লেয়ারে ইভেন্ট পুশ করে।fbq('track', 'Purchase', ...)) ফায়ার হয়।pixel-config.js ফাইল দিয়ে পিক্সেল আইডি কনফিগার করা থাকে।
লারাভেলে যেমন একটি .env ফাইল থাকে, নেক্সট জেএসেও হুবহু একই নিয়ম:
NEXT_PUBLIC_ থাকে, শুধুমাত্র সেগুলিই ব্রাউজার দেখতে পায়। বাকি সবগুলো (যেমন WC_CONSUMER_SECRET) সার্ভার সাইডে সম্পূর্ণ সুরক্ষিত থাকে।
আমাদের তৈরি করা create-zip.ps1 স্ক্রিপ্ট পুরো কাজটিকে এক ক্লিকে নিয়ে এসেছে:
npm run build (এটি টাইপ চেক ও অপ্টিমাইজড বান্ডেল বানাবে)।powershell -ExecutionPolicy Bypass -File create-zip.ps1। এটি স্বয়ংক্রিয়ভাবে ecom next js.zip তৈরি করবে।nextjs/ বা পাবলিক ডিরেক্টরি) জিপ ফাইলটি আপলোড করে Extract করে দিন।tmp/restart.txt টাচ করুন)।Next.js App Router-এ রুট তৈরি করা পৃথিবীর সবচেয়ে সহজ কাজ। কোনো রাউটিং ফাইল এডিট করতে হয় না:
উদাহরণ: একটি `/about-us` পেজ বানাতে চাইলে:
১. src/app/ ফোল্ডারের ভেতর একটি নতুন ফোল্ডার বানান: src/app/about-us/
২. সেই ফোল্ডারে একটি ফাইল তৈরি করুন: page.tsx
৩. নিচের মতো কোড লিখুন:
সাথে সাথে ব্রাউজারে https://yourdomain.com/about-us কাজ করা শুরু করবে!
একজন লারাভেল ব্যাকগ্রাউন্ডের প্রোগ্রামারের জন্য নিচের ৩টি পয়েন্ট মনে রাখা জরুরি:
src/app/api/ রুটে রাখতে হবে।ভবিষ্যতে কোনো নতুন ডেভেলপার বা এআই এজেন্টকে দিয়ে কাজ করাতে গেলে তাকে নিচের ব্লকটি পড়তে বলুন। তাহলে সে পুরো সিস্টেমের ফাইল স্ট্রাকচার এক নিমিষে বুঝে ফেলবে এবং ভুল কোড করবে না: