Ionic Next.js Hello World

Ionic Next.js Hello World

This is a minimal Next.js starter template that demonstrates how to integrate the Ionic Framework into a React application, with two pages and client-side routing via next/link. Built as a sample application, it pairs the server-rendered capabilities of Next.js with the mobile UI components from Ionic.

What is the Ionic Next.js Hello World?

It is a sample application that combines Next.js with the Ionic Framework, showing how to set up a project where Ionic components work alongside Next.js pages. The template contains two pages: pages/index.js and pages/about.js, which handle the / and /about routes respectively. It also includes a "day" directory to illustrate that you can organize routes in subdirectories.

Key Features

• Two pages — The main index page serves the / route, and an about page serves the /about route, demonstrating basic file-based routing in Next.js.
• next/link navigation — Hyperlinks are created with the next/link component for universal routing, giving a single-page-app feel without a custom router.
• Ionic Framework integration — The app imports @ionic/react components so you can use Ionic's mobile-ready UI elements inside React.
• Custom Ionic build — Because the default @ionic/react package throws an HTMLElement error during server-side rendering, this example uses a local build of Ionic React 5.4.4 (from github.com/Yonom/ionic) by pointing package.json to a local tarball.
• Subdirectory routing — The presence of a "day" directory demonstrates that Next.js can serve routes from nested folders.
• One-click Vercel deployment — The repository includes a "Deploy with Vercel" button, letting you import and deploy the project directly from GitHub.

Who is it for?

• Next.js developers who want to add Ionic's mobile UI components to their projects without wrestling with SSR issues.
• Mobile-minded web developers who want a working reference for using Ionic with React and Next.js to build hybrid apps or responsive sites.
• Learners who want a small, readable codebase that shows how Ionic and Next.js can coexist in a single project.

What can you do with it?

• Prototype a mobile-first interface using the Ionic components available through @ionic/react inside a Next.js page.
• Learn how to debug SSR integration errors by following the package.json workaround shared in the README.
• Start a new project by cloning the template, then expanding the two-page structure to add your own routes and components.

How does it work?

The example relies on Next.js's file-based routing: a file named pages/index.js becomes the / route, and pages/about.js becomes the /about route. Navigation between them is handled by the Link component from next/link. To make Ionic work, the package.json is reconfigured to load a custom-built Ionic React tarball instead of the official npm release, avoiding the "HTMLElement is not defined" error that occurs during server-side rendering.

Pros and cons

Pros

• Simple two-page structure makes it easy to understand file-based routing.
• Demonstrates a working workaround for integrating Ionic with Next.js SSR.
• Deployable to Vercel in one click.

Cons

• Requires a custom build of Ionic React rather than the official npm package.
• As a hello world example, it focuses on the basics rather than advanced patterns.

FAQ

Why does the template use a custom build of Ionic React?

The official @ionic/react package causes a ReferenceError for HTMLElement when the page is rendered on the server, as shown in the README. The workaround is to use a patched build from github.com/Yonom/ionic, packaged as a local .tgz file, and reference it in package.json with "file:lib/ionic-react-5.4.4.tgz".

What routes are included?

The template includes two routes: the root / route from pages/index.js and the /about route from pages/about.js. It also has a "day" directory that can be used to create additional nested routes.

How do I deploy this to Vercel?

Use the "Deploy with Vercel" button in the README, or connect your GitHub repository to Vercel and choose the root directory. Since it is a standard Next.js project, Vercel's automatic configuration should work out of the box.