Project Structure

Because of this rule you can safely colocate components, styles and tests inside route folders: anything that is not page.tsx or route.ts is never exposed as a URL.

Dynamic routes and folder conventions

Square brackets in a folder name capture part of the URL as a parameter. In recent releases params is passed as a Promise, so you await it.

// app/blog/[slug]/page.tsx  ->  /blog/hello-world
export default async function PostPage({
  params,
}: {
  params: Promise<{ slug: string }>;
}) {
  const { slug } = await params;
  return <h1>Post: {slug}</h1>;
}

The folder naming conventions are:

• [slug]: a single dynamic segment
• [...slug]: a catch-all segment that matches several levels (/docs/a/b/c)
• [[...slug]]: an optional catch-all that also matches the URL without parameters
• (marketing): a route group in parentheses. It does not appear in the URL and is used to split layouts or organize files
• _components: a private folder starting with an underscore, excluded from routing entirely

next.config.ts

Framework configuration lives in next.config.ts (or .js, .mjs) at the project root. Writing it in TypeScript gives you autocompletion for every option.

// next.config.ts
import type { NextConfig } from "next";

const nextConfig: NextConfig = {
  images: {
    remotePatterns: [{ protocol: "https", hostname: "images.example.com" }],
  },
  async redirects() {
    return [{ source: "/old-blog/:slug", destination: "/blog/:slug", permanent: true }];
  },
};

export default nextConfig;

Import aliases and environment variables

The paths setting in tsconfig.json maps @/ to the project root (or src), so you can write import { db } from "@/lib/db" instead of long relative paths. create-next-app configures this alias by default.

Environment variables are loaded from files such as .env, .env.local, .env.development and .env.production. Secrets usually go in .env.local, which should not be committed.

# .env.local
DATABASE_URL=postgres://user:pass@localhost:5432/app
NEXT_PUBLIC_SITE_NAME=My App

Only variables whose names start with NEXT_PUBLIC_ are included in browser code. Everything else is readable on the server only, so never give that prefix to secrets such as database URLs or API keys.

Metadata files

The app directory also supports conventional files for search engines and social sharing. Dropping in favicon.ico, icon.png or opengraph-image.png generates the matching tags automatically, while robots.ts and sitemap.ts produce their content from code.

// app/sitemap.ts
import type { MetadataRoute } from "next";

export default function sitemap(): MetadataRoute.Sitemap {
  return [
    { url: "https://example.com", lastModified: new Date() },
    { url: "https://example.com/about", lastModified: new Date() },
  ];
}

Summary

• URLs follow the folder structure of app, and a route is public only when it has a page.tsx or route.ts.
• Special files such as layout, loading, error and not-found divide up the UI responsibilities.
• Folder conventions like [slug], (group) and _private handle dynamic URLs and organization.
• Keep framework settings in next.config.ts and secrets in .env.local, and prefix only browser-safe values with NEXT_PUBLIC_.