How to Add Next.js to an Existing React Project
Add Next.js to an existing React app by installing the framework, adding scripts, and creating an app directory.
To add Next.js to an existing React project, install the framework package, add the dev and build scripts, and create an app directory with a root layout and a home page. Your React components stay as they are and move into the new structure one page at a time. The process takes a few minutes and keeps every component you already wrote.
Start by installing the packages:
bashnpm install next@latest react@latest react-dom@latestNext.js is a package like any other, so it lands in node_modules next to react and react-dom. The App Router bundles its own React build internally, but you still declare those two packages so your editor and tooling know the versions. Add these scripts to your package.json:
json"scripts": {
"dev": "next dev",
"build": "next build",
"start": "next start"
}The dev script starts the development server, build produces an optimized production bundle, and start serves that bundle. Replace any scripts left over from a previous bundler, because Next.js manages compilation itself.
Create the app directory
Next.js reads routes from an app folder, so create that folder at the project root. Inside it, two files are enough to get a working page: a root layout and a home page. The folder name matters, because the router treats app as the root of every route.
App.tsx// app/layout.tsx
export default function RootLayout({ children }: { children: React.ReactNode }) {
return (
<html lang="en">
<body>{children}</body>
</html>
);
}The root layout is required and must contain the html and body tags, because it is the outer shell of every page in the app.
App.tsx// app/page.tsx
export default function HomePage() {
return <h1>Hello from Next.js</h1>;
}This page is served at the root URL, /. Add more folders and page files the same way, and each one becomes a route at its folder's path.
Run the server
bashnpm run devOpen http://localhost:3000 and the home page appears. Move your existing React components into the app directory, importing them from their new locations, and each page file becomes a route.
Most of your component code stays exactly the same. What changes is the shell around it: the old HTML entry point, the bundler config, and any client-side router are replaced by Next.js, so you can delete those files after the move.
The most common mistake is running the old dev command instead of npm run dev. If the page still looks like the old bundler output, check that the scripts in package.json point to next and that the app folder exists at the project root.
Add TypeScript
If the project is still JavaScript, rename one file to a TypeScript extension and restart the server. Next.js installs TypeScript and generates a tsconfig.json on the next run, so no manual configuration is required. This step is optional, and plain JavaScript projects work as they are.
bashmv app/page.js app/page.tsx
npm run devComponents written in plain JavaScript still work alongside TypeScript files, so you can convert the project gradually.
If you are coming from a bundler-based setup, the move is similar but has a codemod to help. See Migrating from Vite to Next.js or Migrating from Create React App to Next.js.
Rune AI
Key Insights
- Install next, react, and react-dom to add the framework.
- Add dev, build, and start scripts to package.json.
- Create an app directory with a root layout and a page.
- Start the dev server and visit localhost:3000.
- TypeScript support is added by renaming a file to .tsx.
Powered by Rune AIFrequently Asked Questions
Do I have to rewrite my React components?
Does my React version matter?
Will my Vite or CRA config carry over?
Conclusion
Adding Next.js to an existing React project is mostly a matter of installing the package, adding scripts, and creating an app directory with a root layout and a home page. Your components move over as they are.
More in this topic
`generateMetadata` Explained with Real Examples
What generateMetadata does, when it runs, and how to use it for real routes: awaited params, deduplicated data fetching, extending parent metadata, and returning a 404 from metadata.
Canonical URLs in Next.js: `metadataBase`, `alternates.canonical`, and Dynamic Pages
How canonical URLs work in the Next.js App Router: setting metadataBase once, writing alternates.canonical per route, handling dynamic segments, and what happens when the base URL is missing.
Open Graph and Twitter Card Metadata in Next.js
How to write Open Graph and Twitter card metadata in the Next.js App Router: the openGraph and twitter fields, automatic card defaults, article tags, and image merge rules.