Unit 1 · Module 5

The Root Level Files

package.json, .env, globals.css, tsconfig — what's in the lobby

The lobby, up close

The top level of your project isn't where the app lives — it's where the app is configured. Each file at the root has one specific job. Here's what you'll see, and what each one is for.

package.json — inventory and scripts

Every JavaScript project has a package.json at the root. It does two things.

First, it lists every external package your project depends on. Next.js itself. Your Supabase JS client. Date formatting libraries. Whatever you've installed via npm install. That list is called your dependencies.

Second, it holds scripts. Shortcuts for commands you run in your terminal. When you type npm run dev to start your local server, package.json is what defines what that command actually does underneath.

package.json (simplified)

{
  "scripts": {
    "dev": "next dev",
    "build": "next build",
    "start": "next start"
  },
  "dependencies": {
    "next": "^14.0.0",
    "react": "^18.2.0",
    "@supabase/supabase-js": "^2.39.0"
  }
}

The inventory part matters beyond just record-keeping. When someone else clones your project — or when Vercel builds it on their servers — they run npm install, which reads package.json to know exactly what to download. Without it, nobody could recreate your project environment.

You'll usually see a companion file called package-lock.json next to it. You never touch that one directly. It's automatically generated and locks in the exact versions of everything installed, so the project behaves the same way on every machine.

.env files — secrets that travel with environment

Your app needs certain values to function: your Supabase URL, your Supabase keys, API keys for third-party services. These are secret, and they're different depending on where the app is running — your local machine vs. Vercel's servers.

Instead of writing those values directly into your code, you put them in a .env file. Your code just says "go get the value called SUPABASE_URL" without hardcoding what that value actually is.

Same code. Different values depending on where it's running.

You'll see variations like .env.local and .env.production. .env.local is your personal local values. The .local suffix specifically means "never commit this, ever."

globals.css — one stylesheet for the whole app

globals.css is the one CSS file that applies to your entire app. Every page. Every component. Think of it as the baseline styling that everything inherits before any specific page or component adds its own styles on top.

You'll usually find:

It lives inside app/ because Next.js requires it to be imported from layout.tsx.

tsconfig.json — TypeScript's rulebook

This file tells TypeScript how strict to be, which files to check, and how to resolve import paths. The part you'll care about most is the paths section — that's what lets you write @/components/Button instead of ../../../components/Button everywhere.

You usually don't touch this file much once the project is set up. But when imports break mysteriously, this is the file to check.

manifest.json — for installable web apps

If your app can be installed on a phone's home screen like a native app, it has a manifest.json. It defines the name, icon, colors, and behavior for how the app appears when installed.

Most web apps don't need one. If yours does, it's sitting quietly at the root doing its job.

Configuration files you'll see but rarely open

You don't need to master these to be effective. You just need to know they exist and roughly what they're for.

The pattern

Root-level files configure the project. They don't run the app — they describe and govern it. When something breaks and the error mentions package versions, environment variables, or build settings, the root level is where you look.