This page aims to succinctly mention things to watch out for when building your Nuxt-powered Ionic application, particularly for those familiar with regular Nuxt and Vue applications.

Pages and Navigation

  • Avoid using <NuxtPage>, <NuxtLayout> or <NuxtLink>. These are currently not integrated with this module.

Instead, Ionic expects <ion-router-outlet> to show the route component, and useIonRouter() or the router-link property on any ion- component to change page.

<template>  <ion-app>    <ion-router-outlet />  </ion-app></template>
  • The root element of every page must always be <ion-page>.

This is required by Ionic to set up page transitions and stack navigation. Each view that is navigated to using the router must include an component.

  • When navigating from a tabbed route to a non-tabbed route, route.params from the auto-imported useRoute() will always be an empty object.

A current workaround is to import { useRoute } from 'vue-router';.

Lifecycle Hooks

Ionic handles lifecycle events slightly differently to Vue, as it persists some components in the DOM when Vue would usually unmount them.

This means the various mounted hooks, e.g. onBeforeMount, may not be called when you would expect them to.

To help with this, Ionic has added extra lifecycle hooks which behave how you may have expected the mounted hooks to behave.

Because of this, some expected functionality from Nuxt or other modules may not work or may require changes to get functioning:

  • The composable useHead() will not work out of the box.
    See our cookbook page for how to continue using useHead()
  • Certain Vue Router components should not be used.
    This includes <keep-alive>, <transition>, and <router-view> - read more here.

No serverside rendering

  • The application code cannot contain any serverside rendering.

When targeting iOS or Android devices, the build must be able to run completely on the clientside. We discuss solutions for if you're targeting both web and device here.