A walkthrough of the most important files in your project — what each one does, why it exists, and when you will need to touch it.
When you open your project folder for the first time, you see dozens of files. Some have obvious names. Others look like they were named by someone who enjoys confusing people. What does tsconfig.json do? Why is there a file called .gitignore that starts with a dot? And what happens if you accidentally delete package.json?
This guide walks through the most important files in your project, explains what each one does in plain English, and tells you when (and when not) to touch them.
What it is: A JSON file at the root of your project that defines who your project is and what it needs.
What it contains:
The scripts section is one of the most useful parts. Instead of memorizing long commands, you run short, readable versions:
| Command | What It Does |
|---|---|
npm run dev |
Starts the development server on localhost:3000 |
npm run build |
Creates an optimized production build |
npm run lint |
Checks your code for problems |
npm run test:unit |
Runs your automated unit tests |
npm run test:e2e |
Runs end-to-end tests in a real browser |
npm run format |
Automatically formats all your code |
When you will touch it: Rarely by hand. When you install a new dependency (npm install some-library), npm updates package.json automatically. You might occasionally add a new script or update the project version.
Think of it as: The ingredients list and recipe card for your project. It tells anyone exactly what is needed and how to prepare it.
What it is: A Markdown file at the root of your project that explains what the project is and how to get started.
What it contains:
Why it matters: The README is the first thing anyone sees when they open your project — whether that is a collaborator, a developer you hired, or future you returning after a few months away. A good README answers the question "what is this, and how do I use it?" in under five minutes.
When you will touch it: Whenever you add a feature, change the setup process, or want to update the project description. Keep it current — an outdated README is worse than no README because it sends people down the wrong path.
Think of it as: The welcome sign and quick-start guide at the front door of your project. It sets expectations and points visitors in the right direction.
What it is: A CSS file at app/globals.css that defines the visual foundation of your entire application.
What it contains:
Why it matters: This single file controls the visual identity of your entire application. When a Button component uses bg-primary, it looks up the --primary color defined here. When a Card uses rounded-lg, the border radius comes from tokens defined here. Change a value in globals.css and it cascades through every component automatically.
A practical example: If you want to change your application's primary color from blue to green, you update the --primary token in this file. Every button, link, and accent element across your entire application updates to match — no need to find and change colors in dozens of separate files.
When you will touch it: When you want to customize your application's visual identity — colors, fonts, spacing, or theme. This is one of the first files to explore when you want to make the application feel like your brand.
Think of it as: The paint palette and specification sheet for your building. It defines the exact shades of paint, the type of wood, the size of tiles — and every room in the building references this master specification.
What they are: Two related files that manage environment-specific configuration.
.env.example is committed to Git and serves as a template. It lists every environment variable your project needs, with placeholder values and comments explaining each one..env.local is your personal configuration file. It contains your actual API keys, database URLs, and secrets. It is never committed to Git — the .gitignore file ensures it stays private.What they contain:
# .env.example (safe to share — placeholder values only)
NEXT_PUBLIC_SUPABASE_URL=your-supabase-url-here
NEXT_PUBLIC_SUPABASE_ANON_KEY=your-supabase-anon-key-here
STRIPE_SECRET_KEY=your-stripe-secret-key-here
The workflow:
.env.example to .env.localWhen you will touch them: Whenever you add a new third-party service, change API keys, or toggle feature flags. Always update .env.example when adding a new variable so others know it exists.
Think of them as: .env.example is the blank form that tells you what information is needed. .env.local is your filled-in form with the actual answers — kept in a locked drawer, not pinned to the bulletin board.
What it is: A file that tells Git which files and folders to not track. Anything listed here is invisible to version control.
What it typically excludes:
node_modules/ — the folder containing all downloaded dependencies (thousands of files that can be reinstalled with npm install).env.local — your local secrets and API keys.next/ — the build output folder generated by Next.jscoverage/ — test coverage reports.DS_Store (macOS) or Thumbs.db (Windows)Why it matters: Without .gitignore, you would accidentally commit tens of thousands of files from node_modules, expose your secret API keys in .env.local, and clutter your version history with generated files that change constantly.
When you will touch it: Rarely. The default .gitignore covers virtually everything you need. You might add an entry if you introduce a new tool that generates files you do not want tracked.
Think of it as: The "do not photograph" list for your project. Version control takes a snapshot of everything in your project folder — except the items on this list.
What it is: A configuration file that tells the TypeScript compiler how to check your code.
What it controls:
@/components/ instead of long relative paths like ../../../components/Why it matters: TypeScript catches entire categories of bugs before your code ever runs — calling a function with the wrong type of argument, accessing a property that might not exist, or forgetting to handle a null value. The tsconfig.json file determines how thorough those checks are.
When you will touch it: Almost never. The default configuration is well-tuned for this template. The most common reason to edit it is to add a new path alias if you create a new top-level directory.
Think of it as: The quality control standards manual for your factory. It defines how strictly every product is inspected before it leaves the production line.
What it is: The configuration file for Next.js — the framework that runs your application.
What it controls:
Why it matters: This file shapes how your application behaves at the infrastructure level. Security headers protect your users, image optimization makes your pages load faster, and redirects ensure old URLs still work when you reorganize your site.
When you will touch it: Occasionally. Common reasons include adding an external image domain (so Next.js can optimize images from that source), adjusting security headers, or enabling a new Next.js feature.
Think of it as: The building codes and zoning rules for your project. They operate behind the scenes, ensuring your structure meets safety standards and operates within the right parameters.
What it is: The configuration file for Tailwind CSS — your styling framework.
What it controls:
Why it matters: While globals.css defines your design tokens (the specific color values, spacing amounts, and so on), tailwind.config.ts tells Tailwind how to integrate those tokens into its utility class system and where to look for class usage.
When you will touch it: When you want to extend the design system with custom values, add a Tailwind plugin, or change which files are scanned for class names.
Think of it as: If globals.css is the paint palette, tailwind.config.ts is the instructions for the paint mixer — it tells the system how to turn those palette choices into ready-to-use paint cans.
What it is: The root layout component at app/[locale]/layout.tsx that wraps every page in your application.
What it contains:
<html> and <body> elements — the fundamental structure of every pageWhy it matters: The root layout is the frame that every page is painted inside. If you want something to appear on every page — a header, a footer, an analytics script, or a notification system — it goes here.
When you will touch it: When you want to add something that applies to every page (like a global notification banner), change the default font, or modify the application's metadata.
Think of it as: The building's shell — the walls, ceiling, foundation, and shared infrastructure (plumbing, electrical, HVAC) that every room benefits from. Individual pages are the rooms furnished inside this shell.
What it is: A file at the root of your project that runs code before any page or API route is reached.
What it does:
Why it matters: Middleware is your application's first line of defense. Before a page even begins to load, middleware can verify that the user is logged in, that the request is not malicious, and that the user is seeing the correct language version.
When you will touch it: When you add new protected routes, change authentication rules, or modify security policies. Changes to middleware affect every request, so they should be made carefully.
Think of it as: The front desk of a hotel. Before any guest reaches their room (page), they pass through the front desk, which checks their reservation (authentication), assigns their room (routing), and provides the house rules (security headers).
These files form a hierarchy that controls your application at different levels:
package.json defines what your project needs and how to run ittsconfig.json, next.config.ts, tailwind.config.ts) control how your tools behaveglobals.css defines your visual identitylayout.tsx provides the structural wrapper for every pagemiddleware.ts guards every request before it reaches your application.env.local provides the secrets and settings that make it all work together.gitignore ensures the right things are tracked and the right things are kept privateREADME.md explains all of the above to anyone who needs to understand your projectYou do not need to memorize every detail. What matters is knowing these files exist, what they control, and where to look when you need to change something. Bookmark this guide and return to it whenever you encounter a file you are not sure about.
package.json is your project's identity card — it lists dependencies, scripts, and metadata.globals.css defines your visual foundation — change a design token here and the entire application updates.README.md is the front door — keep it current so anyone can understand and set up your project..env.local holds secrets that must never be committed to Git; .env.example documents what secrets are needed.tsconfig.json, next.config.ts, tailwind.config.ts) rarely need changes but have a huge impact when they do.middleware.ts is the gatekeeper — it processes every request before your application sees it.layout.tsx is the root wrapper — anything that should appear on every page lives here.
It is not easy, but if you learn these ten simple things before you build, you will be ahead of most first-time builders and avoid the worst pitfalls.
Vibe coding means describing what you want in plain English and using AI to generate or edit code. Here is what it is, who it is for, and how to use it without hitting a wall.