Frequently Asked Questions About PedroTech Next.js 15 App Architecture Method
22 answers covering everything from basics to advanced usage.
// Basics
What is file-based routing in Next.js?
File-based routing is Next.js's system where the folder name inside /app defines the URL segment and a page.tsx file inside it defines the UI. There's no separate router configuration file — the folder structure IS the routing. For example, app/posts/page.tsx maps to /posts, and app/posts/[slug]/page.tsx maps to dynamic URLs like /posts/hello-world.
What does the 'use client' directive actually do?
Placing 'use client' at the very top of a file, before imports, converts the entire module into a client component. This enables React hooks like useState and useEffect, browser event handlers like onClick and onChange, and browser-only APIs. Without it, the file is a server component that renders only on the server and cannot use any of these features.
What are the reserved special filenames in Next.js 15?
Next.js reserves page.tsx (route UI), layout.tsx (wrapper), loading.tsx (loading state), error.tsx (error boundary), not-found.tsx (404 UI), and route.ts (API endpoint). Naming these files exactly IS the configuration — the framework triggers specific behaviour based on the filename. They are case and name sensitive, so page.js spelled differently won't work.
What is the difference between layout.tsx and page.tsx?
page.tsx defines the UI rendered when a user navigates to a specific route. layout.tsx defines a wrapper UI applied to all routes at its directory level and below, rendering its children where {children} appears. The root layout.tsx is mandatory and wraps the entire app; nested layouts wrap only their route segment, ideal for section-specific navbars or banners.
// How To
How do I create a dynamic route in Next.js 15?
Create a folder whose name is wrapped in square brackets, like app/users/[userId]/page.tsx. The value in the URL at that position becomes accessible via the params prop. In Next.js 15, params is a Promise, so destructure it with await: const { userId } = await params. Type it as Promise<{ userId: string }> in TypeScript.
How do I build a backend API endpoint in Next.js 15?
Create app/api/[endpoint-name]/route.ts and export named async functions for each HTTP method: GET, POST, PUT, DELETE. Return responses using NextResponse.json() imported from next/server. For POST requests, read the body with const data = await request.json(). The folder name becomes the endpoint path, mirroring file-based routing for pages.
How do I add a shared navbar across every page?
Render the navbar in app/layout.tsx, placed outside the {children} slot so it appears on every route automatically. Keep the Navbar component itself in a /components folder outside /app. Use Next.js's Link component from next/link for navigation links instead of plain anchor tags to enable fast client-side navigation without full page reloads.
How do I show a loading state while a page fetches data?
Add a loading.tsx file inside the route folder. Next.js automatically displays the component it exports while that route's data and UI are being fetched and rendered. This works with async server components — you don't need useState loading flags or conditional spinners. For errors, add error.tsx in the same folder as an error boundary.
How do I handle a page where fetched data comes back empty?
Import notFound from next/navigation and call it when your data is null or undefined, for example after fetching a post that doesn't exist. This programmatically renders your not-found.tsx page instead of crashing on missing properties. Always check for empty responses before rendering data properties — unhandled empty data is a common cause of broken UI.
// Troubleshooting
Why isn't my external image loading with the Image component?
Because the external hostname isn't whitelisted. Add an images.remotePatterns array to next.config.ts listing each external hostname you load images from. Without this, the next/image component silently fails to load external images with no obvious error. This is one required config change most beginner projects need when pulling images from a CMS or external API.
Why do I get an error using useState in my component?
Because you're using a React hook inside a server component, which is the default. Server components never execute on the client, so hooks like useState and useEffect break the app. The fix is to add 'use client' at the top of the file, or better, extract only the interactive part into a separate client component and import it into the server component.
Why isn't my metadata showing up in the page head?
Most likely because you exported the metadata constant from a client component. Metadata export only works in server components — files with 'use client' at the top cannot export metadata, and it fails silently. Move the metadata export to a server-component page.tsx or layout.tsx. Keep interactive logic in a nested client component so the page itself stays a server component.
Why does onClick not work in my Next.js component?
Because server components are never executed on the client, so browser event handlers like onClick, onChange, and onSubmit can't run. Add 'use client' to the top of the file to convert it into a client component, or extract the interactive element into its own client component. Server components should stay for static rendering and data fetching only.
Why am I getting an unexpected route from my components folder?
Because you placed a folder inside /app that Next.js is treating as a route segment. Every folder in /app is a potential URL segment. Move non-route folders like components, lib, and store to the project root outside /app. Only route folders with page.tsx and reserved files belong inside the app directory.
// Comparisons
How does async server component data fetching compare to useEffect fetching?
Async server component fetching runs on the server before the page is sent, so data arrives in the initial HTML with no loading flash, no useEffect, and no client bundle cost. useEffect fetching runs after the component mounts in the browser, causing a loading state and extra round trips. The server approach is faster, more SEO-friendly, and simpler for read-only data.
How does Next.js file-based routing compare to React Router?
Next.js file-based routing derives routes from your folder structure automatically, with no route config to maintain. React Router requires you to declare routes explicitly in code with Route components and paths. Next.js also bundles layouts, loading states, and error boundaries as reserved files, whereas React Router leaves those patterns for you to build manually.
Should I use API routes or server actions in Next.js 15?
This method focuses on API routes via route.ts, which are ideal when you need a real HTTP endpoint for client fetches, webhooks, or external consumers. Server actions are better for tightly coupled form mutations without a separate endpoint. If you're learning the core architecture or exposing endpoints beyond your own app, start with API routes as taught here.
// Advanced
When should I use a nested layout instead of the root layout?
Use a nested layout.tsx when a group of routes shares UI that shouldn't appear everywhere — like a dashboard sidebar or a products promotional banner. Place it inside that route folder so it wraps only that segment and its children. The root layout stays for truly global UI like the main navbar, footer, and the HTML document shell.
How do I mix a server component page with an interactive form?
Keep the page.tsx as an async server component that fetches initial data, then extract the form into a separate 'use client' component with useState and event handlers. Import the client form into the server page and pass the fetched data as props. The form's client-side POST can use a relative /api path since it runs in the browser.
What's the correct way to fetch my own API route from both server and client?
From a server component, prepend the absolute base URL from an environment variable: ${process.env.NEXT_URL}/api/endpoint. From a client component, use a relative path: /api/endpoint. The rule exists because server-side fetches have no browser origin to resolve relative paths against. Store NEXT_URL in .env.local, which is git-ignored by default.
Does the exported component name in page.tsx matter?
No — only the filename matters. Next.js maps the route based on the folder path and the page.tsx filename, not the name of the default-exported function inside it. You can name the function Home, Page, or anything else. This is a common source of confusion for developers coming from manual routing setups where component names drive navigation.
What Turbopack setting should I choose when scaffolding?
Enable Turbopack when running create-next-app for significantly faster local development builds. It's added via the --turbopack flag in your dev script. For most projects the recommended setup is TypeScript yes, ESLint yes, Tailwind yes, src directory no, App Router yes, Turbopack yes, and the default @ import alias. Using a dot as the project name scaffolds into the current folder.