Next.js
10. Nova Shop - An End-to-End Codebase Reading Guide
A document that ties every topic together (routing, RSC, actions, API, cache, auth) into a practical reading path through the Nova-online-shopping codebase.
On this page
- Table of Contents
- 1. Tech Stack & Env
- 2. The app/ Directory Tree
- 3. Code Reading Path (a Suggested 4-Day Plan)
- 4. Flow 1: Browsing the Catalog
- 5. Flow 2: Logging In
- 6. Flow 3: Adding to Cart & Cache
- 7. Flow 4: Stripe Checkout
- 8. Server vs Client - File Table
- 9. Docs vs Code Comparison (Gaps)
- 10. Hands-on Exercises
- 11. Learning Docs Index
10. Nova Shop - An End-to-End Codebase Reading Guide
A document that ties every topic together (routing, RSC, actions, API, cache, auth) into a practical code-reading path through Nova-online-shopping.
Read after: files 1–9. Use it as a "map" when onboarding onto the project.
Table of Contents
- Tech stack & env
- The
app/directory tree - Code reading path (a suggested 4-day plan)
- Flow 1: Browsing the catalog
- Flow 2: Logging in
- Flow 3: Adding to cart & cache
- Flow 4: Stripe checkout
- Server vs Client - file table
- Docs vs code comparison (gaps)
- Hands-on exercises
- Learning docs index
1. Tech Stack & Env
| Layer | Technology |
|---|---|
| UI | Next.js App Router, React, TypeScript, Tailwind |
| Auth | NextAuth v5 + JWT HttpOnly (NestJS) |
| Data | Server Components + Server Actions → NestJS REST |
| Payment | Stripe Checkout + Webhook |
| Backend | Outside this repo - NEXT_PUBLIC_EXTERNAL_API_URL |
env
NEXT_PUBLIC_EXTERNAL_API_URL=http://localhost:5000/api
AUTH_SECRET=...
STRIPE_SECRET_KEY=...
STRIPE_WEBHOOK_SECRET=...
GOOGLE_CLIENT_ID=...
NEXT_PUBLIC_APP_URL=http://localhost:3000
2. The app/ Directory Tree
text
app/
├── layout.tsx, page.tsx, error.tsx, global-error.tsx
├── providers.tsx
├── (shop)/
│ ├── layout.tsx → ShopShell
│ ├── products/page.tsx
│ ├── products/[slug]/page.tsx, productForm.tsx
│ ├── cart/page.tsx, cart-view.tsx
│ └── customers/page.tsx
├── login/page.tsx, login-form.tsx
├── checkout/success|cancel/page.tsx
└── api/
├── auth/[...nextauth]/route.ts
├── checkout/route.ts, checkout/cart/route.ts
└── stripe/webhook/route.ts
lib/
├── services/ products.ts, cart.ts, user.ts
├── api-client.ts, auth-tokens.ts, auth-constants.ts
├── revalidate-shop.ts, cache-tags.ts
├── actions.ts, product-filters.ts, checkout-sessions.ts
└── definitions.ts
Root: auth.ts, auth.config.ts, middleware.ts
3. Code Reading Path (a Suggested 4-Day Plan)
| Day | Read these files | Learn |
|---|---|---|
| 1 | middleware.ts, auth.config.ts, login/*, actions.ts | Auth gate |
| 2 | (shop)/products/page.tsx, product-filters.ts, services/products.ts | Routing + fetching |
| 3 | services/cart.ts, productForm.tsx, revalidate-shop.ts | Actions + cache |
| 4 | api/checkout/*, checkout-sessions.ts, cart-view.tsx | Stripe |
Each day, also read the matching doc file (1–5, 7–9).
4. Flow 1: Browsing the Catalog
Đang dựng diagram…
Read the files in this order:
middleware.ts → products/page.tsx → product-filters.ts → services/products.ts → api-client.ts
Docs: 1. App Router, 5. Data Fetching
5. Flow 2: Logging In
text
login-form → authenticate() → signIn("credentials")
→ authorize → POST /login
→ setAuthCookies
→ redirect /products
Google: Google provider → signIn callback → googleAuthAction → POST /google
Files: auth.ts, auth-tokens.ts, app/lib/actions.ts
Docs: 8. NextAuth v5, 9. JWT Dual Auth
6. Flow 3: Adding to Cart & Cache
text
productForm (client)
→ addToCart() [Server Action]
→ POST /cart/add
→ revalidateAfterCartChange() // tag + path + refresh
→ return CartSummary
→ syncCartBadge (localStorage)
Files: productForm.tsx, services/cart.ts, revalidate-shop.ts, cache-tags.ts
Docs: 3. Server Actions, 5. Data Fetching sections 8–9
7. Flow 4: Stripe Checkout
Buy Now
text
BuyNowButton → fetch POST /api/checkout
→ createProductCheckoutSession
→ window.location = session.url
Cart Checkout
text
cart-view → fetch POST /api/checkout/cart
→ getCartSummary() → createCartCheckoutSession
Webhook
text
Stripe → POST /api/stripe/webhook
→ constructEvent(raw body)
→ revalidateAfterCartChange({ refreshRoute: false })
Docs: 4. Route Handlers
8. Server vs Client - File Table
| Server (default) | Client ("use client") |
|---|---|
products/page.tsx | productForm.tsx |
cart/page.tsx (wrapper) | cart-view.tsx |
listProductsComponent | product-toolbar.tsx, search.tsx |
shop-shell.tsx (layout) | navbar.tsx |
BuyNowButton.tsx, login-form.tsx | |
providers.tsx wraps SessionProvider |
9. Docs vs Code Comparison (Gaps)
| Topic | Docs recommend | Nova today | Notes |
|---|---|---|---|
| Catalog cache | Public ISR | no-store when authenticated | Fine for a members-only shop |
| Navbar data | Server layout | Client getCart | Could be improved |
| Webhook → DB | Write to NestJS | console.log | TODO |
userId query | JWT claims | ?userId= cookie | Backend |
error.tsx | Per segment | ✅ Already present | |
| Dual jwt callback | Single file | Duplicated across auth + auth.config | Refactor |
Details: 0. Mapping & Best Practices
10. Hands-on Exercises
- Trace the cookie after login - DevTools Application.
- Delete
access_token, keeprefresh_token, reload/products- watch the/tokennetwork call. - Add a
brandfilter -product-filters.ts→getProductsparams. - Throw a test error - see the
products/error.tsxUI. - Test with the Stripe test card
4242 4242 4242 4242- check the webhook log.
11. Learning Docs Index
| # | File | Topic |
|---|---|---|
| 1 | App Router | URL, layout, searchParams |
| 2 | Server vs Client | RSC, composition |
| 3 | Server Actions | mutations |
| 4 | Route Handlers | Stripe, webhook |
| 5 | Data Fetching | cache, tag, refresh |
| 6 | Middleware | authorized |
| 7–9 | Auth | NextAuth + JWT |
| 0 | Mapping | Official docs vs Nova |
Home: README.md