mlynch / nextjs-tailwind-ionic-capacitor-starter

A starting point for building an iOS, Android, and Progressive Web App with Tailwind CSS, React w/ Next.js, Ionic Framework, and Capacitor

Next.js + Tailwind CSS + Ionic Framework + Capacitor Mobile Starter

This repo is a conceptual starting point for building an iOS, Android, and Progressive Web App with Next.js, Tailwind CSS, Ionic Framework, and Capacitor.

Next.js handles the production React app experience, Tailwind can be used to style each page of your app, Ionic Framework provides the cross-platform system controls (navigation/transitions/tabs/etc.), and then Capacitor bundles all of it up and runs it on iOS, Android, and Web with full native access.

See this blog post for an overview of the stack and how it all works: https://dev.to/ionic/build-mobile-apps-with-tailwind-css-next-js-ionic-framework-and-capacitor-3kij

Usage

This project is a standard Next.js app, so the typical Next.js development process applies (npm run dev for browser-based development). However, there is one caveat: the app must be exported to deploy to iOS and Android, since it must run purely client-side. (more on Next.js export)

To build the app, run:

npm run build

All the client side files will be sent to the ./out/ directory. These files need to be copied to the native iOS and Android projects, and this is where Capacitor comes in:

npm run sync

Finally, use the following run commands to run the app on each platform:

npm run ios
npm run android

Livereload/Instant Refresh

To enable Livereload and Instant Refresh during development (when running npm run dev), find the IP address of your local interface (ex: 192.168.1.2) and port your Next.js server is running on, and then set the server url config value to point to it in capacitor.config.json:

{
  "server": {
    "url": "http://192.168.1.2:3000"
  }
}

Note: this configuration wil be easier in Capacitor 3 which recently went into beta.

API Routes

API Routes can be used but some minimal configuration is required. See this discussion for more information.

Caveats

One caveat with this project: Because the app must be able to run purely client-side and use Next.js's Export command, that means no Server Side Rendering in this code base. There is likely a way to SSR and a fully static Next.js app in tandem but it requires a Babel plugin or would involve a more elaborate monorepo setup with code sharing that is out of scope for this project.

Additionally, Next.js routing is not really used much in this app beyond a catch-all route to render the native app shell and engage the Ionic React Router. This is primarily because Next.js routing is not set up to enable native-style transitions and history state management like the kind Ionic uses.

What is Capacitor?

You can think of Capacitor as a sort of "electron for mobile" that runs standard web apps on iOS, Android, Desktop, and Web.

Capacitor provides access to Native APIs and a plugin system for building any native functionality your app needs.

Capacitor apps can also run in the browser as a Progressive Web App with the same code.

nextjs-tailwind-ionic-capacitor-starter's Issues

How to make the next/image work?

I'm trying to setup a Capacitor on a Next.js project. I cannot use the Next.js Image Optimization as whenever I export it I will see the error below. But in this repo, we can still use next/image normally. How can it be?

info  - No "exportPathMap" found in "/Users/iant1359/Develop/learn/capacitor-next/next.config.js". Generating map from "./pages"
Error: Image Optimization using Next.js' default loader is not compatible with `next export`.
  Possible solutions:
    - Use `next start` to run a server, which includes the Image Optimization API.
    - Configure `images.unoptimized = true` in `next.config.js` to disable the Image Optimization API.
  Read more: https://nextjs.org/docs/messages/export-image-api
    at /Users/iant1359/Develop/learn/capacitor-next/node_modules/next/dist/export/index.js:150:23
    at async Span.traceAsyncFn (/Users/iant1359/Develop/learn/capacitor-next/node_modules/next/dist/trace/trace.js:79:20)

Whats the point of using Next.js if I can’t use SSR?

Isn't it the same as using Ionic in React.js without Next.js? Or it has some benefits?

Ripple effect appears twice when click on a button on mobile

Don't know how to qualify this but it looks like a minor bug.

How to reproduce

• npm run dev
• open project in a Chrome-based browser (I tried Chromium and Opera)
• Switch to mobile preview in DevTools
• Click on an item in the list tab :

There are two ripples, one with primary color and the other in gray.

Nextjs pages router doesn't work

I have an app written in React && NextJs and after converting it to mobile app the pages with dynamic paths don't work.
I dropped SSR part but still NextJs's Router doesn't have correct path and query params

Does Capacitor support NextJs Router?

Looking for maintainers

Hi, I'm no longer working on this project. If anyone is interested in taking it over and maintaining it let me know!

Update the dependencies

In the title ;)

@leog @nathanchapman

Capacitor V4 update

Error when opening iOS

I get the following error when running npx cap open ios

Showing Recent Errors Only
/path/to/nextjs-tailwind-ionic-capacitor-starter-main/ios/App/Pods/Target Support Files/Pods-App/Pods-App.debug.xcconfig: unable to open file (in target "App" in project "App")

Almogheed

اول مره ادخل هنا اريد مساعدة

Update for Capacitor v3

Now that version 3 is out, are there any plans to create a version of this repo with v3 instructions? There are several places the beta is mentioned.

Integration with Appflow

Thanks for the good example. Both Ionic and Capacitor are great products.
But I'm having trouble integrating it with Appflow. When installing Appflow SDK, react-scripts build is required, but it is not compatible with nextjs environment. Please let me know if there is any way. Can't I use nextjs and Appflow together?

Installation Appflow SDK : https://ionic.io/docs/appflow/quickstart/installation

Here's what I tried.

$ ionic deploy add \ 
--app-id="APPFLOW_APP_ID" \
--channel-name="Production" \
--update-method="auto"
[WARN] Live Updates plugin already added. Reconfiguring only.
> ionic deploy manifest
[OK] Appflow Deploy manifest written to ./build/pro-manifest.json!
> ionic capacitor sync
> react-scripts build

[INFO] Looks like react-scripts isn't installed in this project.
       
       This package is required for this command to work properly.

? Install react-scripts? No
[WARN] Not installing--here's how to install manually: npm i -D -E react-scripts

[ERROR] react-scripts is required for this command to work properly.

When react-scripts is installed, files not used by nextjs such as index.html are required.

next export and NextJS 13

So, yesterday, Next.js 13 was released with a first beta preview of React Server Components enabled by default. It's a big deal, and it appears that server and client integration is becoming even more entwined.

I'm curious whether we'll be able to use next export in the future to create Capacitor/Next.js projects the same way we do here. What would it mean if they stopped supporting next export? Is it even worth using Next.js 13 with Capacitor right now?

It would be fantastic if there was a blog post or an answer to this, as it determines whether it is still worthwhile to use Next.js or Capacitor to build our apps. 

I'm guessing it's relevant to this repository because you guys try to keep the packages up to date here. Thanks for reading this issue and I hope this is the right place to discuss this.

TailwindCSS Styles wont display on IOS preview

Hello!
I am very new at all of this and am trying to start my first project. However every time I launch the project in xcode the app looks like this:

My tailwindconfig looks like this:

module.exports = {
  purge: ['./pages/**/*.{js,ts,jsx,tsx}', './components/**/*.{js,ts,jsx,tsx}'],
  darkMode: 'media',
  theme: {
    extend: {},
  },
  variants: {
    extend: {},
  },
  plugins: [],
};

Other then the purging in the Tailwind config, nothing was changed.

Commands I executed:

npm run build
npm run export
npx cap copy
npx cap open ios

Is there anything else I need to do/modify. Please help me! Thank you.

A Typescript version of the project coming soon?

Hello,

Is a Typescript version coming out soon? The project is very cool, very practical. But no longer up to date on languages and dependencies, it could be super interesting to update it to be usable again.

I understand that new maintainers have been assigned to the project, could we have some visibility on the timeframe for the new version of the repository?

Thanks again for your work, you help a lot of people! Thank you very much!

setupConfig doesn't work

In this repo, i wan't set customized ionic config.
so i put below code, but it doesn't work.

setupConfig({
  mode: 'ios',
  swipeBackEnabled: true
});
getConfig();

1. at `_app.tsx`, in `useEffect` 2. at `AppShell.tsx`

how can this problem solve?

Auth0 Integration

I have been really enjoying the NextJS and Ionic integration. So far it's very fast and impressive to be able to leverage strengths of NextJS and one framework. The SSR and cross to native does seem to be the major obstacle to overcome. As an example, I am utilizing Auth0 and things work great on everything Web. However, callbacks and handoffs to the external API and back to the app seems to hold things back as Auth0 leverages the API in to accomplish this.

https://auth0.com/docs/quickstart/native/ionic-react/01-login

Yet - wondering if leveraging some of their Ionic React and native callbacks could help. Does anyone have any advise on how to cross to native with Auth0 and NextJS using Ionic?

Thanks in advance.

No transition when navigating from Lists to ListDetail

Thnx for this repo! I saw an issue where navigating from Lists to a ListDetail page causes a refresh.

Convert this repo to Template repository

I think this would be easier to use as a starter kit
https://docs.github.com/en/repositories/creating-and-managing-repositories/creating-a-template-repository

https://docs.github.com/en/repositories/creating-and-managing-repositories/creating-a-repository-from-a-template

examples (just random, from first google results):
https://github.com/fastly/compute-starter-kit-javascript-default
https://github.com/textbook/starter-kit

Errors while trying to run android application

Hello. I am trying to use this project to bootstrap an android application. It runs perfectly fine on web, but trying to build and run it on android brings the following error:

✔ Copying web assets from out to android/app/src/main/assets/public in 251.37ms
✔ Creating capacitor.config.json in android/app/src/main/assets in 5.13ms
⠧ copy android [info] Inlining sourcemaps
✔ copy android in 413.24ms
✔ Updating Android plugins in 45.72ms
[info] Found 1 Capacitor plugin for android:
       @capacitor/[email protected]
✔ update android in 236.16ms
[error] native-run failed with errors
        
        ERR_UNSUITABLE_API_INSTALLATION: No suitable API installation found. Use --sdk-info to reveal missing packages
        and other issues.
        1: undefined
        
        More details for this errors may be available online:
        https://github.com/ionic-team/native-run/wiki/Android-Errors

Can anyone help me with this? I really need it. Thank you.
Also, I think this project is really amazing, and I would love to use it more.

Router/navigation support

If using Next.js and building both an iOS/Android app and a web app/PWA, you'll need both support for Next.js routing and also quality client-side routing.

This way you can serve up any valid page by navigating directly to it on the web (say, /about), complete with static rendering and possibly even SSR, but also navigate to an about page client-side complete with transitions and quality native experience users expect.

I wanted to document what I think the best approach here is which is @creativiii's hybrid next/local approach (see his post on this: https://ironeko.com/posts/animating-page-transitions-in-nextjs-for-capacitor?ref=last_articles)

App Shell

The core idea is that every page serves up an <AppShell> component that is essentially all of the Nav, Menu, Tabs, and PageStack needed to build the actual client app experience:

Client-side routing

Then, instead of using Next.js for actual client-side navigation, we will use a simple client-side router like Wouter: https://github.com/molefrog/wouter

This will handle the "local, client-side" navigation and transitions, but won't handle any "server-side" requests at all.

Handling Deeplinks

Most apps will want to handle universal links, but the way those URLs are handled is quite different from a product web server and a mobile app which is not running a web server.

Thus, the app will need to handle deeplinks (https://capacitorjs.com/docs/guides/deep-links) and process each request. If it detects that there is an in-app handler for that URL, it will navigate client-side to that page. If not, it will let the browser handle the URL.

Example page

This is an example of what the Next.js page code would contain:

import AppShell from '../components/AppShell';
import Home from '../components/pages/Home';

export default function Index() {
  return <AppShell page={Home} />;
}

usePage hook

Then, each page component can use the usePage hook to configure app shell related values, such as the title of the page, icons for the tabs, and other values

const Home = ({ selected }) => {
  usePage({
    title: 'Home',
  });

  return (
    ...
  )
}

Tasks

• Abstract away page structure into AppShell component
• Test/integrate client-side router like Wouter
• Build simple navigation transitions
• Verify static/SSR support along with client-side routing

Dark mode in browser not in apk

Hi,

in my browser or android emulator per default i have the dark mod but not in the apk why ?

Emulator :

APK :

Hydration error

When navigating to a specific page using routerLink, everything goes well. When manually refreshing the page, I get an Hydration error. How do I solve this issue?

The error:

The content of the page, where the Hydration error occurs:

import {
  IonBackButton,
  IonButton,
  IonButtons,
  IonContent,
  IonHeader,
  IonPage,
  IonTitle,
  IonToolbar,
} from '@ionic/react';
import React from 'react';

export default function Schedule(): React.JSX.Element {
  return (
    <>
      <IonPage>
        <IonHeader>
          <IonToolbar color="light">
            <IonButtons slot="start">
              <IonBackButton defaultHref="/"></IonBackButton>
            </IonButtons>
            <IonTitle>Schedule</IonTitle>
            <IonButtons slot="end">
              <IonButton routerLink="/booking/create">Create</IonButton>
            </IonButtons>
          </IonToolbar>
        </IonHeader>
        <IonContent className="ion-padding" color="light" role="feed">
          <h2>Lorem ipsum</h2>
          <p className="medium grey">Dolor sit amet.</p>
        </IonContent>
      </IonPage>
    </>
  );
}

Images not showing in iOS

I have confirmed the images are showing in standard web build, but none of the images are showing in iOS simulator (the 3 blog images and author image). This is my first time playing with Capacitor and Ionic so it's possible I've missed a standard setting somewhere to enable images but haven't found anything in the docs. Any help to "enable" the images would be much appreciated. Thanks!

404 issue with _next/static/chunks/*.js

@mlynch
It appears that the capacitorjs cannot recall script files located in this path when the folder depth is greater than 3. How can i solve this problem when i distribute it to Android?

Getting error when doing capacitor sync for ios

ionic-team/capacitor#5798

Ideally changing ios/App/Podfile to remove the offending lines that would fix the issue.

Android Studio doesn't work - white screen

When I deploy to android studio it gives a white screen like this https://gyazo.com/7798fe638051a550a0df0f7d42e8a153

---

Spent time looking into this and I hypothesize it could have to do with the nextjs build/export not working by itself (can't just run index.html, have to spin up a server)?

This is the console when I open index.html on the /out/: https://gyazo.com/e021579caf3c4914ed109f80edf5407f
^npm run dev works & if I run the build with http-server works too

Note: no changes were made to the repo & ran the correct commands (npm run build, npm run export, npx cap copy, npx cap open android)

New app router errors

With new app routing navigating by url dosent work and give error.

It partially works if I change like this, but still give an error,

Does anybody how to fix it?

SEO and static HTML?

It would be great if these two things would be clarified in the README since most people are after combination of Ionic + NextJS because of SEO and static hosting:

1. Is the PWA crawlable by search engines?
2. Can the exported version be hosted as static HTML?

Add a license file

Howdy! I was just wondering if you would consider adding a license to the repo so I know whether or not I can use this code in my projects.

Thanks!

Error while building Android - gradle

Getting this error msg: /home/{user}/nextjs-tailwind-ionic-capacitor-starter/capacitor-cordova-android-plugins/cordova.variables.gradle' as it does not exist.

Does nextjs + capacitor support API routes on IOS

Basically what it says on the tin....

I wanted to find out but it seems like no one really knows. Hopefully some of the folk visiting this repo know. Cheers!

I am interested in figuring out a SSR solution. Can we discuss here?

I wanted to open a discussion if there are any ideas about creating an SSR solution that works on the web.

From my understanding the main issue with SSR in Ionic is the routing in Next JS uses a folder structure where Ionic is using its version of React Router to do transitions. The pages directory is where Next looks for where to go and also what to SSR.

The solution in this repo has been to not use the page directory other than for a single pointer to the AppShell which would have all the React Router stuff.

I could vaguely imagine a solution where we could still use the pages directory and each page has a conditional logic to decide if it shows an App directory with IonRoutes (mobile) or loads the component directly, possibly passing SSR data along (web). If the component needs to fetch data, it can see if it was loaded with data already from the server. If not, then fetch the data clientside. And finally, new routes can be done with a custom useRouter hook that takes handles useIonRoute and Next's useRouter.

For now, I wouldn't account for the new Next App directory cause that's more complexity.

I can fiddle around with it and produce a repo at some point if there's interest. But I just want to see if maybe people already have a solution, or have suggestions or improvements for this proposal.

CSS not working on ios build

Using getStaticProps

Is there a way to use getStaticProps with this? I want to generate my pages statically using an API but as far as I can tell this will only work with nextjs if the pages I am generating via slugs are within the /pages directory with the [] syntax. Do you know an easy way I could accomplish this keeping the same structure you have or how it might need to be modified?

Thanks lot!

Unsplash images are not showing on Android

Unsplash images are not showing on Android. On the browser works fine but building and exporting the app for Android is not showing the images because is getting the URL.

D/InputMethodManager: startInputInner - Id : 0
D/Capacitor: Handling local request: http://localhost/_next/static/chunks/framework-9b5d6ec4444c80fa.js
D/Capacitor: Handling local request: http://localhost/_next/static/chunks/main-f8fa0ccd6fd7cd8a.js
D/Capacitor: Handling local request: http://localhost/_next/static/chunks/pages/_app-aa083d9be419673c.js
D/Capacitor: Handling local request: http://localhost/_next/static/chunks/pages/index-b66aa8961d88c178.js
D/Capacitor: Handling local request: http://localhost/_next/static/6U466ftwKTYJF493z9tiP/_buildManifest.js
D/Capacitor: Handling local request: http://localhost/_next/static/6U466ftwKTYJF493z9tiP/_ssgManifest.js
D/Capacitor: Handling local request: http://localhost/_next/static/chunks/34fce5f1.bef0fa3d8439f59e.js
D/Capacitor: Handling local request: http://localhost/_next/static/chunks/718.47e85776f93458d8.js
D/Capacitor: Handling local request: http://localhost/_next/static/chunks/968.1d6014add1dad642.js
D/Capacitor: Handling local request: http://localhost/favicon.ico
D/Capacitor: Handling local request: http://localhost/_next/static/chunks/990.b5c55a40fcc26f6b.js
D/Capacitor: Handling local request: http://localhost/_next/image?url=https%3A%2F%2Fimages.unsplash.com%2Fphoto-1610235554447-41505d7962f8%3Fixid%3DMXwxMjA3fDB8MHxwaG90by1wYWdlfHx8fGVufDB8fHw%253D%26ixlib%3Drb-1.2.1%26auto%3Dformat%26fit%3Dcrop%26w%3D882%26q%3D80&w=828&q=75
D/Capacitor: Handling local request: http://localhost/_next/image?url=%2Fimg%2Fmax.jpg&w=828&q=75
D/Capacitor: Handling local request: http://localhost/_next/image?url=https%3A%2F%2Fimages.unsplash.com%2Fphoto-1610212594948-370947a3ba0b%3Fixid%3DMXwxMjA3fDB8MHxwaG90by1wYWdlfHx8fGVufDB8fHw%253D%26ixlib%3Drb-1.2.1%26auto%3Dformat%26fit%3Dcrop%26w%3D934%26q%3D80&w=828&q=75
D/Capacitor: Handling local request: http://localhost/_next/static/chunks/823.5d5644b559a8593e.js
D/Capacitor: Handling local request: http://localhost/_next/static/chunks/78.46dcf55d1ff46d94.js
D/Capacitor: Handling local request: http://localhost/_next/static/chunks/544.1be07b82b4f34332.js
I/ViewRootImpl@cf65327[MainActivity]: ViewPostIme pointer 0
I/ViewRootImpl@cf65327[MainActivity]: ViewPostIme pointer 1

Native navigation with NextJs 14

I tried to test this source built by Nexjs 14 and the native navigation back will close the app instead of go back previous page. Anyone have the same problem please give me the solution. Thank you so much

Local Storage or Database Options? Prisma support?

I'm moving my current app to React (Next.js) and looking for Cordova alternatives and stumbled upon this repo. The only thing it's missing is some sort of local storage options. Would this be able to work with Prisma so I could use SQLite for local storage on mobile apps?

Error: Invalid hook call

When I try to start the app (with 0 modification to the repo), it shows this error - & I checked that it's neither #1 or #3:

Error: Invalid hook call. Hooks can only be called inside of the body of a function component. This could happen for one of the following reasons:
1. You might have mismatching versions of React and the renderer (such as React DOM)
2. You might be breaking the Rules of Hooks
3. You might have more than one copy of React in the same app
See https://reactjs.org/link/invalid-hook-call for tips about how to debug and fix this problem.

Can electron be compatible?

Hello, first of all, thank you for the good template!
Is it possible to export nextjs for electron? 👀
It is quite impressive that this template uses capacitorjs.

How about supporting mobile and PC at the both time?