In our last session, we explored the fundamental question: "What is Next.js?". We learned that it's a popular React framework designed to build modern, performant web applications, offering features like server-side rendering and static site generation out of the box. Now that we have a solid understanding of *why* Next.js exists, it's time to get our hands dirty and learn *how* to set up our very own Next.js project. This lesson will guide you through the initial steps of creating a new Next.js application, laying the groundwork for all the exciting features we'll explore later. ## Prerequisites *You don't need:* * Any prior experience with Next.js * Deep knowledge of advanced React concepts *Here's what you do need:* * A basic understanding of HTML, CSS, and JavaScript * Familiarity with React fundamentals (components, props, state) * Node.js and npm (or yarn/pnpm) installed on your machine ## What is Setting up your First Next.js App? Setting up your first Next.js app is the foundational process of creating a new, blank Next.js project that's ready for you to start building upon. It involves using specific command-line tools to generate a project structure with all the necessary configurations and dependencies pre-installed. This process is crucial because it automates the often tedious and error-prone task of manually configuring a web project, allowing you to focus immediately on writing code for your application's features. Skipping this step and trying to manually assemble a Next.js project from scratch would be like trying to build a car by forging the metal yourself; it's possible but incredibly inefficient and prone to failure. When you properly set up a Next.js app, you gain a pre-defined file structure that guides your development and a working development server that allows you to see your changes in real-time. If this initial setup is done incorrectly, or if critical configuration files are missing or misconfigured, your application might fail to build, run, or deploy properly, leading to frustrating debugging sessions and delayed project timelines. For example, incorrect dependency installations or missing foundational files can prevent the development server from starting, leaving you with an unresponsive application before you've even written a single line of your own code. ## How Setting up your First Next.js App Actually Works The primary mechanism for setting up a new Next.js application is the `create-next-app` command-line interface (CLI) tool. This is an officially supported utility provided by the Next.js team that acts like a project generator, scaffolding a new Next.js project with sensible defaults and essential configurations. When you run `create-next-app`, it interactively asks you a few questions about your desired setup (like whether to use TypeScript, ESLint, Tailwind CSS, etc.) and then automatically downloads the necessary packages, creates the required directories and files, and sets up a basic project structure. It’s designed to get you from zero to a running development server as quickly and smoothly as possible. ### Using `create-next-app` The `create-next-app` CLI is your entry point into the Next.js ecosystem. It’s a Node.js package that you execute using `npx` (which comes bundled with npm version 5.2+), `yarn create`, or `pnpm create`. This command initializes a new directory and populates it with a starter Next.js project. The interactive prompts allow you to customize the initial setup, making it flexible for different project needs. For instance, you can choose to include features like TypeScript for type safety, ESLint for code linting, or Tailwind CSS for utility-first styling. Here's the basic command to create a new Next.js app: ```bash npx create-next-app@latest my-next-app ``` When you run this command, `my-next-app` will be the name of the directory created for your project. The `@latest` ensures you're using the most recent stable version of `create-next-app`. The CLI will then guide you through a series of questions: * **Would you like to use TypeScript?** (Yes/No) - TypeScript adds static typing to JavaScript, catching errors early. * **Would you like to use ESLint?** (Yes/No) - ESLint helps enforce code quality and identify potential problems. * **Would you like to use Tailwind CSS?** (Yes/No) - Tailwind CSS is a popular utility-first CSS framework for rapid styling. * **Would you like to use `src/` directory?** (Yes/No) - Organizes your application code within a `src` folder. * **Would you like to use App Router? (recommended)** (Yes/No) - The App Router is the newer, recommended routing system in Next.js. * **Would you like to customize the default import alias?** (Yes/No) - Allows you to set up custom import paths (e.g., `@/components` instead of `../../components`). [TIP: Choosing the right options during `create-next-app` can save you a lot of configuration headaches later. For beginners, it's generally recommended to say 'Yes' to TypeScript, ESLint, and the App Router if you want to follow modern Next.js conventions. ask Sage: "What are the core benefits of using TypeScript with Next.js?"] Once you've answered these questions, `create-next-app` will perform the following actions: 1. **Create a new directory** with the name you provided (e.g., `my-next-app`). 2. **Download and install** all the necessary dependencies for Next.js, React, and any other chosen configurations (like TypeScript, ESLint, etc.) using your package manager (npm, yarn, or pnpm). 3. **Generate essential project files and folders**, including configuration files and a basic `pages` or `app` directory for your application's routes. 4. **Initialize a Git repository** if you have Git installed, making it easy to start version controlling your project. After the process completes, you'll be instructed to `cd` into your new project directory and run the development server. ### The Project Structure When `create-next-app` finishes, it creates a structured directory that forms the backbone of your Next.js application. While the exact structure can vary slightly based on your choices (especially regarding the App Router vs. Pages Router, and the `src/` directory), a typical modern Next.js project will look something like this: ``` my-next-app/ ├── .next/ # Built output (generated during build, not for manual editing) ├── node_modules/ # All project dependencies ├── public/ # Static assets like images and fonts │ └── favicon.ico ├── src/ # Application source code (if chosen) │ ├── app/ # App Router files │ │ ├── layout.tsx # Root layout for the application │ │ └── page.tsx # The homepage component │ ├── components/ # Reusable UI components │ │ └── Button.tsx │ └── styles/ # Global styles or CSS modules │ └── globals.css ├── .eslintrc.json # ESLint configuration ├── .gitignore # Specifies intentionally untracked files that Git should ignore ├── next-env.d.ts # TypeScript environment declarations ├── next.config.js # Next.js configuration file ├── package.json # Project metadata and dependencies ├── README.md # Project description ├── tailwind.config.ts # Tailwind CSS configuration (if chosen) └── tsconfig.json # TypeScript configuration ``` Let's break down some of the key files and directories you'll immediately encounter: * **`.next/`**: This directory is automatically generated when you build your Next.js application. It contains all the optimized code, static assets, and serverless functions that Next.js produces for deployment. **You should never manually edit files within this directory.** * **`node_modules/`**: This is where all your project's dependencies (external JavaScript libraries and packages) are installed by npm, yarn, or pnpm. It’s usually quite large and is also not meant for manual editing. * **`public/`**: Files placed in this directory are served statically from the root of your application. For example, if you place an image `logo.png` in `public/`, you can access it at `/logo.png` in your browser. This is perfect for static assets like images, fonts, or `robots.txt` files. * **`src/app/`** (or `pages/` if you chose the older Pages Router): This is where the core of your application's user interface lives. * **App Router (`src/app/`)**: This newer routing system is built around file-system conventions. Files like `page.tsx` define routes. For example, `src/app/about/page.tsx` would correspond to the `/about` route. The `layout.tsx` file at any level defines the UI that wraps its children. * **Pages Router (`pages/`)**: The older system where each file directly maps to a route. For example, `pages/index.js` is the homepage (`/`), and `pages/about.js` is the `/about` page. * **`src/components/`**: While not automatically created by `create-next-app` by default, it's a common convention to place your reusable React components here. * **`.eslintrc.json`**: Configuration file for ESLint, a linter that helps maintain code quality and consistency. * **`.gitignore`**: A file that tells Git which files and directories to ignore (e.g., `node_modules/`, `.next/`). * **`next.config.js`**: This is the primary configuration file for your Next.js application. Here, you can customize how Next.js builds and serves your app, set up redirects, configure image optimization, and more. * **`package.json`**: This file lists your project's dependencies, scripts (like `dev`, `build`, `start`), and other metadata. * **`README.md`**: A markdown file for project documentation, typically including instructions on how to set up and run the project. * **`tailwind.config.ts`** (if Tailwind CSS is chosen): Configuration for Tailwind CSS, allowing you to customize its behavior, colors, fonts, etc. * **`tsconfig.json`** (if TypeScript is chosen): Configuration for the TypeScript compiler. [NOTE: The App Router and Pages Router are two different paradigms for routing in Next.js. The App Router is the latest and recommended approach for new projects, offering features like Server Components and improved data fetching patterns. Understanding this distinction is key to navigating Next.js documentation and examples. ask Sage: "What are Server Components and how do they differ from Client Components?"] ```mermaid flowchart TD user["User Request"] --> browser["Browser"]; browser --> dev_server["Next.js Dev Server"]; dev_server --> filesystem["File System (pages/ or app/)"]; filesystem --> code["React Components"]; code --> html["HTML Output"]; html --> browser; dev_server -->|Live Reload| browser; ``` The diagram above illustrates a simplified flow when you're developing. A user's request comes in, is handled by the Next.js development server, which reads your code from the file system (e.g., `app/page.tsx`), renders it into HTML, and sends it back to the browser. The development server also watches for file changes and automatically reloads the browser. ### Development Server A crucial part of setting up your Next.js app is running its development server. This server is optimized for a fast development experience. When you run `npm run dev` (or `yarn dev`, `pnpm dev`), Next.js starts a local server, typically at `http://localhost:3000`. This server offers several benefits: * **Hot Module Replacement (HMR)**: When you save changes to your code, the development server automatically updates the application in your browser without requiring a full page refresh. This significantly speeds up the development cycle. * **Error Overlays**: If there are errors in your code, the development server displays them directly in the browser with helpful information, making it easier to pinpoint and fix issues. * **Fast Refresh**: A refined version of HMR specifically for React components, preserving component state when possible during updates. To start the development server, navigate to your project's root directory in your terminal and run: ```bash npm run dev ``` This command is defined in your `package.json` file and is a shortcut to run the `next dev` command. [TIP: Always run `npm run dev` in your project's root directory. If you're in a subdirectory and try to run it, it will likely fail because it won't be able to find the Next.js configuration and scripts. ask Sage: "What's the difference between `next dev` and `next start`?"] ## Worked Example Let's walk through creating a simple Next.js application using `create-next-app` with common choices. **Step 1: Create the Project** Open your terminal and run the following command. We'll name our project `my-first-next-app`. ```bash npx create-next-app@latest my-first-next-app ``` **Step 2: Respond to Prompts** You'll be prompted with questions. Here's a common set of answers for a beginner project: * **Would you like to use TypeScript?** `y` (Yes) * **Would you like to use ESLint?** `y` (Yes) * **Would you like to use Tailwind CSS?** `y` (Yes) * **Would you like to use `src/` directory?** `y` (Yes) * **Would you like to use App Router? (recommended)** `y` (Yes) * **Would you like to customize the default import alias?** `n` (No, for now) The CLI will then install dependencies. This might take a few minutes. **Step 3: Navigate and Run the Development Server** Once the installation is complete, change into your new project directory and start the development server: ```bash cd my-first-next-app npm run dev ``` Your browser should automatically open to `http://localhost:3000`, displaying the default Next.js welcome page. **Step 4: Modify the Homepage** Now, let's make a small change to the homepage. Open your project in your preferred code editor. Since we chose the `src/` directory and the App Router, navigate to `src/app/page.tsx`. Replace the entire content of `src/app/page.tsx` with the following: ```typescript // src/app/page.tsx // Import necessary React hooks or components if needed (not for this simple example) // import React from 'react'; export default function HomePage() { return (

Get started by editing src/app/page.tsx

By{' '}

Welcome to My First Next.js App!

This is a custom message for our new application.

); } ``` **Explanation of the `page.tsx` code:** * We're defining a functional component `HomePage`. * The `return` statement contains JSX, which looks like HTML but is JavaScript. * We're using Tailwind CSS classes (like `flex`, `min-h-screen`, `p-24`, `bg-gray-900`, `text-white`) for styling, as we opted in during setup. * The `` tags point to assets in the `public/` directory (e.g., `/vercel.svg`, `/next.svg`). * We've added a custom heading and paragraph to personalize the page. **Step 5: Observe the Changes** Save the `page.tsx` file. Your browser should automatically refresh, and you'll see the updated content with your custom message and styling. **Failure Case: Forgetting to Install Dependencies** Imagine you ran `npx create-next-app my-app` but then immediately tried to run `npm run dev` without letting the dependencies install. **Broken Code (Conceptual):** If you were to run `npm run dev` before `npm install` (or `yarn install`, `pnpm install`), you would see errors like: ``` Error: Can't find module 'react' or 'next' ``` or ``` Command 'next' not found. ``` **Corrected Code:** You must ensure all dependencies are installed. After running `npx create-next-app my-app`, you would always run: ```bash cd my-app npm install # Or yarn install / pnpm install npm run dev ``` This ensures that all the necessary libraries (like React, Next.js itself, and others) are downloaded into your `node_modules` folder, making them available for your project to use. [NOTE: The `create-next-app` command automatically runs the install process for you. The "failure case" above is more about understanding what happens if you were to manually delete `node_modules/` and forget to reinstall. ask Sage: "What's the role of the `package-lock.json` or `yarn.lock` file?"] ## Common Mistakes & How to Avoid Them ### 1. Running `create-next-app` in an existing directory **Why it happens:** Developers sometimes try to initialize a Next.js project inside a folder that already contains unrelated files or even another project. `create-next-app` expects to create a new, dedicated folder for the project. **Broken Example:** ```bash # Assuming you are already inside a folder named 'my-project' with existing files cd my-project npx create-next-app . # Using '.' to initialize in the current directory ``` **Outcome:** This will likely lead to errors as `create-next-app` tries to create files that might already exist or conflict with the current directory's structure. It's not designed to merge with existing projects. **Corrected Example:** Always create a new, empty directory for your Next.js app, or ensure the directory you specify is empty. ```bash # Create a new, empty directory and then initialize Next.js inside it mkdir my-new-next-app cd my-new-next-app npx create-next-app . # Now '.' refers to the newly created, empty directory ``` Or, more commonly: ```bash npx create-next-app my-new-next-app # Specify a new directory name cd my-new-next-app ``` ### 2. Not installing dependencies after `create-next-app` (less common with modern `npx`) **Why it happens:** Older versions of `create-next-app` or manual interventions might require an explicit dependency installation step. While `npx create-next-app@latest` typically handles this automatically now, it's a good concept to understand. If `create-next-app` fails midway or if you manually remove `node_modules`, you'll need to reinstall. **Broken Example:** ```bash npx create-next-app my-app cd my-app # Forgot to run npm install, or it failed silently npm run dev ``` **Outcome:** Errors like `Error: Can't find module 'react'` or `Command 'next' not found.` because the necessary packages are not present in `node_modules`. **Corrected Example:** Always ensure dependencies are installed. The `create-next-app` command usually does this, but if you ever encounter missing modules: ```bash cd my-app npm install # Or yarn install / pnpm install npm run dev ``` ### 3. Misunderstanding the App Router vs. Pages Router during setup **Why it happens:** New developers might not grasp the implications of choosing between the App Router and the Pages Router during the initial setup, leading to confusion later when following tutorials or documentation that targets a different router system. **Broken Example:** A developer learns from a tutorial that uses the Pages Router (`pages/` directory) but set up their project with the App Router (`app/` directory). They then try to replicate the tutorial's file structure or logic directly, leading to errors because the conventions are different. **Corrected Example:** Be aware of which router system you chose during setup. If you are starting a new project, it's recommended to use the **App Router** as it's the future of Next.js. If you encounter older tutorials, be mindful that they might be using the Pages Router and adapt their concepts accordingly. ## Best Practices * **Always use `npx create-next-app@latest`**: This ensures you're using the most up-to-date version of the project initializer, which includes the latest features, bug fixes, and security patches. * **Choose your router system wisely**: For new projects, opt for the **App Router** unless you have a specific reason or constraint (like working on a legacy project or needing a very specific feature only available in Pages Router). The App Router is the direction Next.js is heading. * **Use the `src/` directory for larger projects**: While optional, organizing your application code within a `src/` folder can help keep your project root cleaner and improve code organization as your application grows. * **Understand the purpose of `next.config.js`**: This is your primary tool for customizing Next.js behavior. Familiarize yourself with its options for image optimization, redirects, environment variables, and more, as you'll likely need to edit it as your project evolves. * **Start the development server with `npm run dev`**: This command provides the best development experience with features like Hot Module Replacement (HMR) and Fast Refresh, allowing for rapid iteration. ## Key Takeaways * You now understand that `create-next-app` is the standard tool for scaffolding new Next.js projects. * You can identify the essential files and directories generated by `create-next-app` and understand their general purpose. * You know how to start the Next.js development server and why it's crucial for a smooth development workflow. * You can differentiate between the App Router and the Pages Router and understand the recommendation for new projects. * You are aware of common pitfalls during project setup, such as incorrect directory initialization or missing dependencies. * You know the importance of using the latest version of `create-next-app` for optimal features and security. [REFLECT: What part of Setting up your First Next.js App clicked for you, and what still feels fuzzy?] ## What's Next Now that we have a Next.js project set up and know how to run it, we're ready to dive deeper into how Next.js handles pages and navigates between them in the upcoming lesson on Pages and Routing.

Next.js Fundamentals

Introduction to Next.js

Pages and Routing

Data Fetching in Next.js

Styling and Components

Deployment and Beyond

Build a Full-Stack Blog with Next.js

E-commerce Product Listing Page