Starting a new web project can feel overwhelming. However, tools like Next.js and HeroUI make the process smooth. In this tutorial, you will create a starter project using both. By the end, you’ll have a working, stylish app.
What You’ll Build
You will create a simple and clean web page. The app will use:
- Next.js for server-side rendering and routing.
- HeroUI (Previously NextUI) for styling and UI components.
- TypeScript for strong typing and a better development experience.
By the end, you’ll have a styled page with reusable components.
Prerequisites
Before you start, make sure you have:
- Node.js (version 18 or later)
- npm or yarn
- Basic knowledge of JavaScript and React
- A code editor like VS Code
Step 1: Create a New Next.js App
Install Node.js from the website.
https://nodejs.org/en
Open VS Code(Visual Studio Code)
Click “File,” and then open the folder.
1. Create a new folder.
2. Open it.
Click “Terminal” and then New Terminal.
Run the following command on the terminal to bootstrap a new Next.js project with TypeScript:
npx heroui-cli@latest init -t app
This command creates a new folder next-app-template.
On the terminal, navigate to the directory:
cd next-app-template
Install command
next-app-template> npm install
npm i @heroui/react framer-motion
Step 2: Run the App
Start the development server:
npm run dev
Open your browser and go to http://localhost:3000.
You should see the default Next.js welcome page.
For Windows
When you get an error message.
npm : File C:\Users\...\AppData\Roaming\npm\npm.ps1 cannot be loaded because running scripts is disabled on this system. For more information, see about_Execution_Policies at https:/go.microsoft.com/fwlink/?LinkID=135170.
At line:1 char:1
+ npm -version
+ ~~~
+ CategoryInfo : SecurityError: (:) [], PSSecurityException
+ FullyQualifiedErrorId : UnauthorizedAccess1. Open PowerShell as Administrator
Right-click the PowerShell icon and select “Run as administrator.” This is important because you’ll need elevated privileges to change the execution policy.
2. Run the following command:
Set-ExecutionPolicy RemoteSigned -Scope CurrentUser
3. Confirm the change:
PowerShell will likely ask you to confirm the change. Type A (for Yes to All) or Y (for Yes) and press Enter.
4. Try your npm command again:
In the same PowerShell window, try running npm -version again. It should work this time.
> [email protected] dev > next dev --turbopack ▲ Next.js 15.0.4 (Turbopack) - Local: http://localhost:3000 ✓ Starting... ✓ Ready in 3s ○ Compiling / ... ✓ Compiled / in 6.5s
Step 3: Use the Navbar in Your Page
Open app/navbar/page.tsx. Import and use your new component:
"use client";
import {Navbar, NavbarBrand, NavbarContent, NavbarItem, Link, Button} from "@heroui/react";
export const AcmeLogo = () => {
return (
<svg fill="none" height="36" viewBox="0 0 32 32" width="36">
<path
clipRule="evenodd"
d="M17.6482 10.1305L15.8785 7.02583L7.02979 22.5499H10.5278L17.6482 10.1305ZM19.8798 14.0457L18.11 17.1983L19.394 19.4511H16.8453L15.1056 22.5499H24.7272L19.8798 14.0457Z"
fill="currentColor"
fillRule="evenodd"
/>
</svg>
);
};
export default function App() {
return (
<Navbar>
<NavbarBrand>
<AcmeLogo />
<p className="font-bold text-inherit">ACME</p>
</NavbarBrand>
<NavbarContent className="hidden sm:flex gap-4" justify="center">
<NavbarItem>
<Link color="foreground" href="#">
Features
</Link>
</NavbarItem>
<NavbarItem isActive>
<Link aria-current="page" href="#">
Customers
</Link>
</NavbarItem>
<NavbarItem>
<Link color="foreground" href="#">
Integrations
</Link>
</NavbarItem>
</NavbarContent>
<NavbarContent justify="end">
<NavbarItem className="hidden lg:flex">
<Link href="#">Login</Link>
</NavbarItem>
<NavbarItem>
<Button as={Link} color="primary" href="#" variant="flat">
Sign Up
</Button>
</NavbarItem>
</NavbarContent>
</Navbar>
);
}Save and reload the page. You’ll see a clean navbar and content area.
http://localhost:3000/navbar
Step 4: Add a Custom 404 Page (Optional)
To improve user experience, add a custom 404 page.
Create src/app/not-found.tsx With this content:
export default function Custom404() {
return (
<div className="min-h-screen flex items-center justify-center text-center">
<h1 className="text-4xl font-bold">404 - Page Not Found</h1>
</div>
);
}Users will see a better message if they visit a broken link.
Creating Routes in Subdirectories
- Each directory needs
page.tsxto define the content for that route segment.
your-project-name/ ├── app/ │ ├── layout.tsx # Root layout for your application │ ├── page.tsx # Home page │ ├── not-found.tsx # Custom 404 page (as discussed) │ ├── providers.tsx # To wrap the app with NextThemesProvider and HeroUIProvider │ └── ... # Other route files ├── public/ │ ├── favicon.ico │ └── ... # Other static assets ├── styles/ │ └── global.css # Global styles ├── package.json ├── tsconfig.json # (If you're using TypeScript) ├── components ├── config └── ... # Other configuration files
Conclusion
In this tutorial, you created a modern web app using Next.js, HeroUI, and TypeScript. You learned how to set up the project, add components, apply styles, and customize themes. With reusable components and strong typing, your code is clean and maintainable. HeroUI simplified the UI design process, while TypeScript helped catch errors early. You also explored how to deploy the app with Vercel. This stack offers speed, flexibility, and a great developer experience. Now you’re ready to build responsive, elegant interfaces faster. Explore features like routing, API routes, and advanced theming to take your app even further.
This article was originally published on Medium.
