Installation and Development Environment Configuration

In Quantum Metropolis, before an engineer can begin working on the city's systems, they must prepare their biometric quantum workstation. Similarly, as a Next.js developer, you must first configure your development environment. In this module, you will learn how to install and configure all the necessary tools for building applications in Next.js 16.

System Requirements

Before we begin the installation, make sure your computer meets the minimum requirements. Just as the quantum terminals in Quantum Metropolis require specific energy specifications, the Next.js environment needs appropriate software versions:

• Node.js - version 20.9 or newer (Next.js 16 no longer supports Node.js 18; the current LTS release is the best choice)
• TypeScript (optional) - version 5.1 or newer
• macOS, Windows (including WSL) or Linux
• Minimum 1GB RAM (recommended 4GB or more for larger projects)
• Code editor - recommended Visual Studio Code with React/Next.js extensions

Installing Node.js and npm

Node.js is like the quantum energy generator for your development environment - it powers all processes and tools.

Windows and macOS

1. Visit the official Node.js website
2. Download and install the latest LTS (Long Term Support) version
3. Verify the installation by opening a terminal and typing:

1node -v
2npm -v

You should see the version numbers for Node.js and npm (Node Package Manager).

Linux (Ubuntu/Debian)

1# Ubuntu 22.04/24.04 and Debian 12 repositories ship an old Node.js (12 or 18),
2# while Next.js 16 needs 20.9 or newer. Install the current LTS from NodeSource:
3curl -fsSL https://deb.nodesource.com/setup_24.x | sudo -E bash -
4sudo apt install nodejs

Managing Node.js Versions

For more advanced users, just as Quantum Metropolis engineers use virtualization systems to test different energy configurations, you can use tools to manage Node.js versions:

• nvm (Node Version Manager) for macOS/Linux
• nvm-windows for Windows

1# Installing nvm (macOS/Linux)
2curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.3/install.sh | bash
3
4# Installing a specific Node.js version
5nvm install 24
6nvm use 24

Installing a Code Editor

In Quantum Metropolis, holographic code editors are integrated with the engineers' neural implants. Fortunately, in our world, installing a good code editor on your computer is sufficient. Visual Studio Code is currently one of the most popular editors for Next.js developers.

1. Download and install Visual Studio Code
2. Install useful extensions:
   • ES7+ React/Redux/React-Native snippets - code templates
   • ESLint - static code analysis
   • Prettier - code formatting
   • Tailwind CSS IntelliSense (if you plan to use Tailwind CSS)
   • GitHub Copilot (optional) - AI assistant for developers

Creating a New Next.js Project

Now that you have the necessary tools installed, you can create your first Next.js 16 project. Vercel provides a convenient create-next-app tool that automatically configures the project with best practices.

1npx create-next-app@latest my-quantum-app

During installation, you will be asked to answer several configuration questions:

1Would you like to use the recommended Next.js defaults? No, customize settings
2Would you like to use TypeScript? Yes
3Which linter would you like to use? ESLint
4Would you like to use React Compiler? No
5Would you like to use Tailwind CSS? Yes
6Would you like your code inside a `src/` directory? Yes
7Would you like to use App Router? (recommended) Yes
8Would you like to customize the import alias (`@/*` by default)? No
9Would you like to include AGENTS.md to guide coding agents to write up-to-date Next.js code? Yes

In Next.js 16 the wizard starts by asking about the recommended defaults: the answer "Yes, use recommended defaults" selects TypeScript, ESLint, Tailwind CSS, App Router and an AGENTS.md file in one go. We choose "No, customize settings" because we also want to put our code in a src/ directory. We leave React Compiler, which memoizes components automatically, switched off for now, and AGENTS.md is a file with instructions for AI coding agents that points them to documentation matching your installed Next.js version.

We recommend answering "Yes" to most questions, especially those regarding TypeScript and App Router, which are key for modern Next.js 16 applications.

After installation is complete, navigate to the project directory and start the development server:

1cd my-quantum-app
2npm run dev

Your application should now be available at http://localhost:3000.

Alternative Installation Methods

Yarn

If you prefer to use Yarn instead of npm:

1npm install -g yarn
2yarn create next-app my-quantum-app

pnpm

PNPM is an alternative package manager that can save disk space:

1npm install -g pnpm
2pnpm create next-app my-quantum-app

TypeScript Configuration

TypeScript is like the security system in Quantum Metropolis - it prevents errors before they occur. Next.js has built-in TypeScript support, and the latest versions of create-next-app will configure it automatically. If you create a project manually, you can add TypeScript later:

1touch tsconfig.json
2npm run dev

Next.js will detect the tsconfig.json file, install the missing dependencies itself (typescript, @types/react, @types/node) and fill the file with the recommended configuration.

Next.js 16 Project Structure with App Router

After creating a new project, you will see the following directory structure:

1my-quantum-app/
2├── node_modules/      # Installed dependencies
3├── public/            # Static files (images, fonts)
4├── src/               # Application source code
5│   ├── app/           # App Router directory
6│   │   ├── layout.tsx # Main layout
7│   │   ├── page.tsx   # Home page
8│   │   └── globals.css # Global styles (Tailwind CSS 4 is configured here too)
9├── AGENTS.md          # Guidance for AI coding agents
10├── CLAUDE.md          # Points to AGENTS.md
11├── eslint.config.mjs  # ESLint configuration (flat config format)
12├── next-env.d.ts      # Next.js types for TypeScript
13├── next.config.ts     # Next.js configuration
14├── package.json       # Dependencies and scripts
15├── postcss.config.mjs # PostCSS configuration (Tailwind CSS plugin)
16└── tsconfig.json      # TypeScript configuration

Compared with older versions, the tailwind.config.js file is gone: Tailwind CSS 4, which create-next-app installs, is configured directly in globals.css. ESLint uses the newer eslint.config.mjs format, and the Next.js configuration is created in TypeScript right away as next.config.ts.

ESLint Configuration

ESLint is like the air quality monitoring system in Quantum Metropolis - it maintains code cleanliness and quality. create-next-app creates a basic ESLint configuration in the eslint.config.mjs file (flat config format), and the npm run lint script simply runs the eslint command. Next.js 16 removed the old next lint command and no longer lints your code during next build, so you run the linter yourself. You can extend the configuration, for example with Prettier:

1npm install --save-dev eslint-config-prettier eslint-plugin-prettier

Then update the eslint.config.mjs file:

1// eslint.config.mjs
2import { defineConfig, globalIgnores } from 'eslint/config';
3import nextVitals from 'eslint-config-next/core-web-vitals';
4import nextTs from 'eslint-config-next/typescript';
5import prettierRecommended from 'eslint-plugin-prettier/recommended';
6
7const eslintConfig = defineConfig([
8  ...nextVitals,
9  ...nextTs,
10  {
11    rules: {
12      '@typescript-eslint/no-unused-vars': 'warn',
13    },
14  },
15  prettierRecommended,
16  globalIgnores(['.next/**', 'out/**', 'build/**', 'next-env.d.ts']),
17]);
18
19export default eslintConfig;

The eslint-plugin-prettier/recommended config turns on the prettier/prettier rule and switches off ESLint rules that would clash with Prettier's formatting, which is why it sits near the end of the list. Run the check for the whole project with npm run lint.

Prettier Configuration

Prettier is like the automatic space organization system in Quantum Metropolis - it maintains consistent code appearance. Create a .prettierrc file in the project directory:

1{
2  "semi": true,
3  "trailingComma": "all",
4  "singleQuote": true,
5  "printWidth": 80,
6  "tabWidth": 2
7}

VSCode Configuration for the Project

To fully integrate VS Code with your project, create a .vscode directory in the root of the project, and then a settings.json file inside:

1{
2  "editor.formatOnSave": true,
3  "editor.defaultFormatter": "esbenp.prettier-vscode",
4  "editor.codeActionsOnSave": {
5    "source.fixAll.eslint": true
6  },
7  "typescript.tsdk": "node_modules/typescript/lib",
8  "typescript.enablePromptUseWorkspaceTsdk": true
9}

Environment Variables Configuration

In Quantum Metropolis, every system has its special access parameters. In Next.js, we use environment variables to store sensitive information and environment-specific configurations. Create a .env.local file in the project root directory:

1# Example environment variables
2DATABASE_URL=your_database_url
3API_KEY=your_api_key
4NEXT_PUBLIC_API_URL=https://api.example.com

Variables with the NEXT_PUBLIC_ prefix will also be available in the browser.

Testing the Installation

To make sure everything works correctly, modify some code in the src/app/page.tsx file and see if the changes are visible in the browser. If so, your environment is correctly configured!

Common Issues and Solutions

Port Conflicts

If port 3000 is already in use, you can run Next.js on a different port:

1npm run dev -- -p 3001

Node.js Issues

If you encounter version compatibility errors, make sure you are using the required version:

1node -v
2# If the version is too old, update Node.js or use nvm

TypeScript Issues

If you encounter TypeScript errors, check if you have the appropriate types installed:

1npm install --save-dev @types/react @types/node

Advanced Configuration

For more advanced projects, just as advanced systems in Quantum Metropolis require additional configuration, you can customize your Next.js environment:

Adding Path Aliases

Modify tsconfig.json to add path aliases:

1{
2  "compilerOptions": {
3    "baseUrl": ".",
4    "paths": {
5      "@/components/*": ["src/components/*"],
6      "@/lib/*": ["src/lib/*"],
7      "@/styles/*": ["src/styles/*"],
8      "@/utils/*": ["src/utils/*"]
9    }
10  }
11}

Test Configuration

Add Jest and React Testing Library to the project:

1npm install --save-dev jest @testing-library/react @testing-library/jest-dom jest-environment-jsdom

Create a jest.config.js file:

1const nextJest = require('next/jest');
2
3const createJestConfig = nextJest({
4  dir: './',
5});
6
7const customJestConfig = {
8  setupFilesAfterSetup: ['<rootDir>/jest.setup.js'],
9  testEnvironment: 'jest-environment-jsdom',
10};
11
12module.exports = createJestConfig(customJestConfig);

Then create a jest.setup.js file:

1import '@testing-library/jest-dom';

Summary

Congratulations! Just like an engineer in Quantum Metropolis who completed their workstation configuration, you now have a fully configured development environment for Next.js 16. Your holographic terminals (code editor) are ready, the quantum reactor (Node.js) is running, and the security systems (TypeScript, ESLint) are active.

In the next lesson, we will learn more about project initialization and available starters that will help you start working on specific types of applications more quickly.

1<!DOCTYPE html>
2<html lang="en">
3<head>
4  <meta charset="UTF-8">
5  <title>Virtual DOM - Metropolis Quantum</title>
6  <style>
7    body {
8      font-family: 'Courier New', monospace;
9      background: linear-gradient(135deg, #0f0f23 0%, #1a1a2e 100%);
10      color: #64ffda;
11      padding: 20px;
12      margin: 0;
13    }
14    .container {
15      max-width: 800px;
16      margin: 0 auto;
17      background: rgba(255, 255, 255, 0.1);
18      padding: 20px;
19      border-radius: 10px;
20      border: 1px solid #64ffda;
21    }
22    h1 {
23      color: #64ffda;
24      text-align: center;
25    }
26    .comparison {
27      display: grid;
28      grid-template-columns: 1fr 1fr;
29      gap: 20px;
30      margin-top: 20px;
31    }
32    .method {
33      background: rgba(0, 0, 0, 0.5);
34      padding: 15px;
35      border-radius: 8px;
36      border: 2px solid #448aff;
37    }
38    .method h3 {
39      color: #448aff;
40      margin-top: 0;
41    }
42    .demo-box {
43      background: rgba(100, 255, 218, 0.1);
44      padding: 10px;
45      border-radius: 5px;
46      margin: 10px 0;
47      border: 1px solid #64ffda;
48    }
49    button {
50      background: linear-gradient(45deg, #7c4dff, #e91e63);
51      color: white;
52      border: none;
53      padding: 10px 20px;
54      border-radius: 5px;
55      cursor: pointer;
56      font-weight: bold;
57      margin: 5px;
58    }
59    button:hover {
60      transform: scale(1.05);
61      box-shadow: 0 5px 15px rgba(124, 77, 255, 0.4);
62    }
63  </style>
64</head>
65<body>
66  <div class="container">
67    <h1>Virtual DOM vs Real DOM</h1>
68
69    <div class="comparison">
70      <div class="method">
71        <h3>Traditional DOM Manipulation</h3>
72        <div id="traditional-demo" class="demo-box">
73          Counter: <span id="trad-count">0</span>
74        </div>
75        <button onclick="traditionalUpdate()">Update (Slow)</button>
76        <p>Every change → Full page re-render</p>
77      </div>
78
79      <div class="method">
80        <h3>Virtual DOM (React Way)</h3>
81        <div id="virtual-demo" class="demo-box">
82          Counter: <span id="virt-count">0</span>
83        </div>
84        <button onclick="virtualUpdate()">Update (Fast)</button>
85        <p>Change → Diff → Only necessary updates</p>
86      </div>
87    </div>
88
89    <div style="margin-top: 30px; background: rgba(124, 77, 255, 0.2); padding: 15px; border-radius: 8px;">
90      <h3>How does Virtual DOM work?</h3>
91      <ol style="line-height: 1.8;">
92        <li>React creates a virtual representation of the DOM in memory</li>
93        <li>On state change - creates a new Virtual DOM</li>
94        <li>Compares (diffing) old with new Virtual DOM</li>
95        <li>Updates only changed parts in the real DOM</li>
96        <li>Result: Faster and more efficient applications!</li>
97      </ol>
98    </div>
99  </div>
100
101  <script>
102    let tradCount = 0;
103    let virtCount = 0;
104
105    // Traditional DOM - slower method
106    function traditionalUpdate() {
107      tradCount++;
108      console.log("Traditional update - entire element is re-rendered");
109      document.getElementById('trad-count').textContent = tradCount;
110      // Simulation of slower operation
111      document.getElementById('traditional-demo').style.background = 'rgba(244, 67, 54, 0.3)';
112      setTimeout(() => {
113        document.getElementById('traditional-demo').style.background = 'rgba(100, 255, 218, 0.1)';
114      }, 200);
115    }
116
117    // Virtual DOM simulation - faster method
118    function virtualUpdate() {
119      virtCount++;
120      console.log("Virtual DOM update - only necessary changes");
121      document.getElementById('virt-count').textContent = virtCount;
122      // Simulation of faster operation
123      document.getElementById('virtual-demo').style.background = 'rgba(76, 175, 80, 0.3)';
124      setTimeout(() => {
125        document.getElementById('virtual-demo').style.background = 'rgba(100, 255, 218, 0.1)';
126      }, 100);
127    }
128
129    console.log("Virtual DOM Demo - Metropolis Quantum");
130    console.log("Click the buttons to see the difference in action!");
131  </script>
132</body>
133</html>