# Introduction

`@nuxtjs/ionic` provides a batteries-included, zero-config needed, Ionic integration for Nuxt.

Supercharge your Ionic apps with the power of Nuxt, giving you the tremendous development experience you're used to
when using Nuxt for web.

Follow the installation guide to get going immediately, or continue reading to find out more about what this module provides.

::callout{color="info" icon="i-lucide-info"}
Get started with our 

[Installation guide](https://ionic.nuxtjs.org/get-started/installation)

.
::

## What is Ionic?

[The Ionic SDK](https://ionicframework.com/){rel=""nofollow""} is an open-source UI toolkit for building modern, cross-platform mobile apps from a single codebase. It deeply integrates with Vue for a delightful mobile dev experience.

::callout{color="info" icon="i-lucide-info"}
Read the 

[Ionic documentation for Vue](https://ionicframework.com/docs/vue/overview){rel=""nofollow""}

 to learn more about Vue development with Ionic.
::

## Features

This module attempts to get you going with Nuxt + Ionic quickly, providing sane defaults for ionic and helpful components and utilities. The configuration file can still customize and override its default behaviors and provide full customisation of ionic.

::list{type="success"}
- **Ionic router integration:** continue defining routes based on the structure of your `~/pages` directory and using page-level utilities such as `definePageMeta()`.
- **Auto-imports**: Ionic components, composables and icons are all [auto-imported](https://nuxt.com/docs/guide/concepts/auto-imports){rel=""nofollow""} for ease of use.
- **Helpful components and utilities**: This module provides components and utilities to accomplish common tasks more easily.
- **Pre-render routes**
- **Mobile meta tags**
- **Capacitor integration**: works out-of-the-box with [Capacitor](https://capacitorjs.com/){rel=""nofollow""} for shipping to native platforms like iOS and Android.
::

::callout{color="info" icon="i-lucide-info"}
Read more about 

[our features](https://ionic.nuxtjs.org/overview)

.
::

## Cookbook

Our cookbook documentation provides common use-cases with code examples to get you going as fast as possible. And if you create something useful, come back and submit a PR to have it added to our cookbook.

::callout{color="info" icon="i-lucide-info"}
Discover common recipes in 

[our cookbook](https://ionic.nuxtjs.org/cookbook)

.
::


# Installation

## Prerequisites

- A fresh or existing Nuxt project
- [Nuxt's prerequisites](https://nuxt.com/docs/getting-started/installation#prerequisites){rel=""nofollow""}
- [Ionic's environment setup](https://ionicframework.com/docs/intro/environment){rel=""nofollow""}
- [Capacitor's enviroment setup](https://capacitorjs.com/docs/getting-started/environment-setup){rel=""nofollow""} if using iOS or Android

## Installation

::steps{level="3"}
### Add module

Add `@nuxtjs/ionic` to your project's dev dependencies:

```bash [Terminal]
npx nuxi@latest module add ionic
```

### Nuxt Module

Next, add the module to your Nuxt configuration in `nuxt.config.ts`.

```js [nuxt.config.ts]
export default defineNuxtConfig({
  modules: ['@nuxtjs/ionic'],
  ssr: false,
})
```

  :::callout{color="warning" icon="i-lucide-alert-triangle"}
  If deploying to iOS or Android, be aware the app must be able to run completely client-side. We recommend setting 

  `ssr: false`

   in your nuxt config. Find out more in 

  [deploying to both web and device](https://ionic.nuxtjs.org/cookbook/web-and-device)

  .
  :::

Finally, either remove your `app.vue` file or [replace it with a custom one](https://ionic.nuxtjs.org/cookbook/customising-app-vue).

### Development Server

Now you'll be able to start your Nuxt app in development mode as usual:

  :::code-group
  ```bash [yarn]
  yarn dev -o
  ```

  ```bash [npm]
  npm run dev -- -o
  ```

  ```bash [pnpm]
  pnpm dev -o
  ```
  :::

  :::callout{.font-bold color="success" icon="i-lucide-check-circle"}
  Well done! A browser window should automatically open for 

  <http://localhost:3000>{rel=""nofollow""}

  .
  :::

  :::callout{color="info" icon="i-lucide-info"}
  The first time you start a Nuxt project with 

  `@nuxtjs/ionic`

   enabled, a 

  `ionic.config.json`

   file will be created if it doesn't already exist.
  :::
::


# Configuration

### Module Config

This module exposes three keys for configuration: `integrations`, `css` and `config`:

```js [nuxt.config.ts]
export default defineNuxtConfig({
  modules: ['@nuxtjs/ionic'],
  ionic: {
    integrations: {
      //
    },
    css: {
      //
    },
    config: {
      //
    }
  },
})
```

#### `integrations`

Integrations control which other modules this module should enable and setup from the list below. Disabling them allows you to remove them, or gives you the option to set them up yourself.

- **meta**:br Default: `true`:br
  Disable to take full control of meta tags.
- **router**:br Default: `true`:br
  Disable to configure Ionic Router yourself.
- **icons**:br Default: `true`:br
  Disable to stop icons from being auto-imported.

#### `css`

Configure which Ionic stylesheets are automatically added to your application. For more information about
these stylesheets, [see the Ionic Documentation for Stylesheets](https://ionicframework.com/docs/layout/global-stylesheets){rel="&#x22;nofollow&#x22;"}.

- **core**:br Default: `true`:br
  Disable to import these CSS files manually:
  - `@ionic/vue/css/core.css`
- **basic**:br Default: `true`:br
  Disable to import these CSS files manually:
  - `@ionic/vue/css/normalize.css`
  - `@ionic/vue/css/structure.css`
  - `@ionic/vue/css/typography.css`
- **utilities**:br Default: `false`:br
  Enable to add extra Ionic CSS utilities:
  - `@ionic/vue/css/padding.css`
  - `@ionic/vue/css/float-elements.css`
  - `@ionic/vue/css/text-alignment.css`
  - `@ionic/vue/css/text-transformation.css`
  - `@ionic/vue/css/flex-utils.css`
  - `@ionic/vue/css/display.css`

#### `config`

Configure Ionic components globally across your app, such as app mode, tab button layout, etc. For example:

```js [nuxt.config.ts]
export default defineNuxtConfig({
  ionic: {
    config: {
      rippleEffect: false,
      mode: 'md',
      // ...
    },
  },
})
```

::callout{color="info" icon="i-lucide-info"}
Please see the 

[Ionic Config Options](https://ionicframework.com/docs/vue/config#config-options){rel=""nofollow""}

 for available keys, values
and examples of how they work.
::

### Capacitor Config

Capacitor is configured via the `capacitor.config.ts` file - this is only required if you are targeting native devices such as iOS or Android.

::callout{color="info" icon="i-lucide-info"}
Please see the 

[Capacitor Config docs](https://capacitorjs.com/docs/config){rel=""nofollow""}

 for more information.
::


# Enabling Capacitor

[Capacitor](https://capacitorjs.com/){rel="&#x22;nofollow&#x22;"} is a powerful tool for shipping to native platforms like iOS and Android, separate from or alongside your web app.

The good news is that it's installed by default with `@nuxtjs/ionic`. You just need to enable it in your ionic app, and choose what platforms you want to support.

> The Ionic CLI is available via `npx` or can be installed globally with `npm install -g @ionic/cli` or `yarn global add @ionic/cli` or `pnpm add -g @ionic/cli`.

::code-group
```bash [npx]
npx @ionic/cli integrations enable capacitor
npx @ionic/cli capacitor add ios
npx @ionic/cli capacitor add android
```

```bash [npm]
# ionic config set -g npmClient npm

ionic integrations enable capacitor
ionic capacitor add ios
ionic capacitor add android
```

```bash [yarn]
ionic config set -g npmClient yarn

ionic integrations enable capacitor
ionic capacitor add ios
ionic capacitor add android
```

```bash [pnpm]
ionic config set -g npmClient pnpm

ionic integrations enable capacitor
ionic capacitor add ios
ionic capacitor add android
```
::

::callout{color="info" icon="i-lucide-info"}
Read more about 

[creating for iOS and Android here](https://ionic.nuxtjs.org/cookbook/creating-ios-android-apps)

.
::

#### Run on iOS or Android

Once an Android or iOS project is added with Capacitor, you can run your app on an iOS or Android emulator.

::callout
Android Studio and SDK (for Android projects) or XCode (for iOS projects) are required to use the 

`npx cap open`

 or 

`npx cap run`

 command. See the 

[Capacitor Environment Setup docs](https://capacitorjs.com/docs/getting-started/environment-setup){rel=""nofollow""}

 for details.
::

To build, sync, and run your app:

1. Create a web build with `npx nuxt generate` or `npx nuxt build`.
2. Run `npx cap sync` to update your Capacitor project directories with your latest app build.
3. Run `npx cap run android` or `npx cap run ios` to run the app from the command line using an installed device **OR**
4. *(Optional)* Run `npx cap open android` or `npx cap open ios` to open the project in Android Studio or XCode, respectively.

> Remember to run `npx cap sync` after every new build to ensure your Android and/or iOS project is up-to-date.

::callout{color="info" icon="i-lucide-info"}
Read more about 

[local development for iOS and Android here](https://ionic.nuxtjs.org/cookbook/local-development)

.
::


# Watchouts

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

::list{type="warning"}
- 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.

```vue [app.vue]
<template>
  <ion-app>
    <ion-router-outlet />
  </ion-app>
</template>
```

::list{type="warning"}
- 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 `<ion-page>` component.

::list{type="warning"}
- 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';`.

::callout{color="info" icon="i-lucide-info"}
Read more 

[about routing here](https://ionic.nuxtjs.org/overview/routing)

.
::

## 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.

::callout{color="info" icon="i-lucide-info"}
Read about the 

[Ionic Vue lifecycle hooks here](https://ionicframework.com/docs/vue/lifecycle){rel=""nofollow""}

.
::

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

::list{type="warning"}
- **The composable `useHead()` will not work out of the box**. :br
  See [our cookbook page](https://ionic.nuxtjs.org/cookbook/page-metadata) for how to continue using `useHead()`
- **Certain Vue Router components should not be used**. :br
  This includes `<keep-alive>`, `<transition>`, and `<router-view>` - [read more here](https://ionicframework.com/docs/vue/lifecycle#how-ionic-framework-handles-the-life-of-a-page){rel=""nofollow""}.
::

## No serverside rendering

::list{type="warning"}
- 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](https://ionic.nuxtjs.org/cookbook/web-and-device).

::callout{color="info" icon="i-lucide-info"}
Learn more about 

[building for native devices here](https://ionic.nuxtjs.org/cookbook/creating-ios-android-apps)

.
::


# Routing

By default, this module sets up the Ionic Router, or `IonRouter`. This router is built on top of `vue-router`, but with some changed functionality specifically for making it work better for mobile applications.

::list{type="success"}
- Enables [non-linear routing](https://ionicframework.com/docs/vue/navigation#non-linear-routing){rel=""nofollow""}, e.g. for application tabs
- Separate navigation stacks for each tab of your application
- Rich page transitions out-of-the-box, appropriate for mobile
- Simple API for custom animations and direction control when navigating via links
::

## Pages

Just like regular Nuxt, you can start building your Ionic application by creating routes within the `~/pages` directory. Every Vue file inside this directory will generate a route that displays the contents of the file. Read more about [Nuxt file-based routing](https://nuxt.com/docs/getting-started/routing){rel="&#x22;nofollow&#x22;"} here.

::list{type="warning"}
- The root component of every page must always be the `<ion-page>` component.
::

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 `<ion-page>` component.

```vue [~/pages/home.vue]
<template>
  <ion-page>
    <ion-header>
      <ion-toolbar>
        <ion-title>Home</ion-title>
      </ion-toolbar>
    </ion-header>
    <ion-content class="ion-padding">Hello World</ion-content>
  </ion-page>
</template>
```

::callout{color="info" icon="i-lucide-info"}
Read more about 

[`<ion-page>` here](https://ionicframework.com/docs/vue/navigation#ionpage){rel=""nofollow""}

.
::

### Defining page meta

Nuxt utilities like `definePageMeta` are fully functional. However, you should avoid using `<NuxtPage>` or `<NuxtLayout>` as these will not function correctly, due to Ionic requiring an `<ion-router-outlet>` instead.

::callout{color="info" icon="i-lucide-info"}
Read more about 

[`definePageMeta` here](https://nuxt.com/docs/api/utils/define-page-meta){rel=""nofollow""}

.
::

### Define a root alias if there's no index.vue page

Usually applications with tab bars will not have a `~/pages/index.vue` file, as it's not needed. However, this will mean opening the app will return a 404, e.g. on localhost:3000.

To solve this, if you do not have a `~/pages/index.vue` file in your project, you should add the following code to the page that you want to be displayed on your app's root page:

```ts [pages/tabs.vue]
definePageMeta({
  alias: ['/'],
})
```

It will now be used as the root path, and will be routed to by default when visiting e.g. localhost:3000.

## Navigation

Navigation can be done in several ways, using the `IonRouter` or certain `ion-` components.

::callout{color="info" icon="i-lucide-info"}
Read about navigation in 

[Ionic's Vue Navigation docs](https://ionicframework.com/docs/vue/navigation){rel=""nofollow""}

.
::

### IonRouter

To access the router, use the composable `useIonRouter()`. This should always be used instead of the regular `useRouter()` (which is auto-imported from `vue-router` by Nuxt). This ensures the benefits of the Ion Router are always provided.

This module auto-imports `useIonRouter()` so it should be available automatically. If this is disabled, you can import it from `@ionic/vue`.

It is best used when you wish to control navigation programmatically and have full control over the page transitions.

```vue
<script setup lang="ts">
import { customAnimation } from '~/animations/customAnimation';

const router = useIonRouter();

const goHome = () => router.push('/home');
const goBack = () => router.back();
const replaceRoute = () => router.replace({ name: 'newRoute' })
const customAnimatedNavigation = () => router.navigate('/page2', 'forward', 'replace', customAnimation);
</script>
```

::callout{color="info" icon="i-lucide-info"}
Read more about 

[`useIonRouter() here`](https://ionicframework.com/docs/vue/navigation#navigating-using-useionrouter){rel=""nofollow""}

.
::

### Navigating with Components

All Ionic components expose a `router-link` attribute. When set, the router will navigate to the specified route when the component is clicked. It accepts strings as well as named routes.

`router-direction` and `router-animation` are also available for further control.

It's best used when simple routing is required, without any programmatic logic before or after.

```vue
<template>
  <ion-button router-link="{ name: 'myPage' }">Click Me</ion-button>
  <ion-button 
    router-link="/page2" 
    router-direction="back" 
    :router-animation="myAnimation"
  >
    Click Me
  </ion-button>
</template>
```

::callout{color="info" icon="i-lucide-info"}
Read about 

[using the `router-link` attribute here](https://ionicframework.com/docs/vue/navigation#navigating-using-router-link){rel=""nofollow""}

.
::

::callout{color="warning" icon="i-lucide-alert-triangle"}
Avoid using 

`<NuxtLink>`

 for now as it currently is not integrated with the Ionic Router.
::

## Route Parameters

When accessing route parameters, `useRoute()` should continue to be used, just like regular Nuxt.

```vue [pages/posts/[id}.vue]
<script setup lang="ts">
const route = useRoute()

// When accessing /posts/1, route.params.id will be 1
console.log(route.params.id)
</script>
```

::callout{color="info" icon="i-lucide-info"}
Read more about 

[Nuxt route parmeters here](https://nuxt.com/docs/getting-started/routing#route-parameters){rel=""nofollow""}

.
::

## Route Middleware

Nuxt's Route Middleware is also integrated and available, just like regular Nuxt.

::code-group
```ts [middleware/auth.ts]
export default defineNuxtRouteMiddleware((to, from) => {
  // isAuthenticated() is an example method verifying if a user is authenticated
  if (isAuthenticated() === false) {
    return showLoginModal(); // showLoginModal() is an example of opening a modal flow for authentication
  }
})
```

```html [pages/tabs/feed.vue]
<script setup lang="ts">
definePageMeta({
  middleware: 'auth'
})
</script>

<template>
  <h1>Welcome to your feed</h1>
</template>
```
::

::callout{color="info" icon="i-lucide-info"}
Read more about 

[Nuxt route middleware here](https://nuxt.com/docs/getting-started/routing#route-middleware){rel=""nofollow""}

.
::


# Theming

Ionic provides many css variables with which their components derive css styles. These variables can be overridden to customise the theme of your app.

In its most simple form, you can create a `~/assets/css/ionic.css` file and add it to the `css` property in your `nuxt.config.ts` file. You can then add css variables that you'd like to override within this file, under the `:root` selector:

::code-group
```css [assets/css/ionic.css]
:root {
  --ion-color-primary: #57e389;
  --ion-color-primary-rgb: 87, 227, 137;
  --ion-color-primary-contrast: #000000;
  --ion-color-primary-contrast-rgb: 0, 0, 0;
  --ion-color-primary-shade: #4dc879;
  --ion-color-primary-tint: #68e695;

  /* And so on... */
}
```

```ts [nuxt.config.ts]
export default defineNuxtConfig({
  css: ['~/assets/css/ionic.css'],
})
```
::

To learn more about theming and which variables to override, check out Ionic's [official theming documentation](https://ionicframework.com/docs/theming/basics){rel="&#x22;nofollow&#x22;"}.


# Ionic Auto-Imports

Ionic provides various components and helper functions for use in your application.

This module automatically auto-imports them throughout your app, so you do not need to import them manually.

::callout{color="info" icon="i-lucide-info"}
Read more about 

[how component auto-imports work](https://v3.nuxtjs.org/guide/directory-structure/components#components-directory){rel=""nofollow""}

.
::

## Ionic Components

All Ionic Vue components should be auto-imported throughout your app. Although your IDE should be aware of these components everywhere, they are not globally registered and are only imported within the components that use them.

For a list of all Ionic Vue components, please refer to the ionic component documentation: <https://ionicframework.com/docs/components>{rel="&#x22;nofollow&#x22;"}

::callout{color="info" icon="i-lucide-info"}
If you find a component that isn't being auto-imported, please 

[open an issue](https://github.com/nuxt-modules/ionic/issues/new/choose){rel=""nofollow""}

 or 

[a pull request](https://github.com/nuxt-modules/ionic/compare){rel=""nofollow""}

.
::

## Ionic Helper Functions

A number of Ionic hooks/composables are also imported by Nuxt via auto-imports within your app:

- [`getPlatforms`](https://ionicframework.com/docs/vue/platform#getplatforms){rel="&#x22;nofollow&#x22;"}
- [`isPlatform`](https://ionicframework.com/docs/vue/platform#isplatform){rel="&#x22;nofollow&#x22;"}
- [`menuController`](https://ionicframework.com/docs/api/menu){rel="&#x22;nofollow&#x22;"}
- [`onIonViewWillEnter`](https://ionicframework.com/docs/vue/lifecycle#ionic-framework-lifecycle-methods){rel="&#x22;nofollow&#x22;"}
- [`onIonViewDidEnter`](https://ionicframework.com/docs/vue/lifecycle#ionic-framework-lifecycle-methods){rel="&#x22;nofollow&#x22;"}
- [`onIonViewWillLeave`](https://ionicframework.com/docs/vue/lifecycle#ionic-framework-lifecycle-methods){rel="&#x22;nofollow&#x22;"}
- [`onIonViewDidLeave`](https://ionicframework.com/docs/vue/lifecycle#ionic-framework-lifecycle-methods){rel="&#x22;nofollow&#x22;"}
- [`useBackButton`](https://ionicframework.com/docs/vue/utility-functions#hardware-back-button){rel="&#x22;nofollow&#x22;"}
- [`useKeyboard`](https://ionicframework.com/docs/vue/utility-functions#keyboard){rel="&#x22;nofollow&#x22;"}
- [`useIonRouter`](https://ionicframework.com/docs/vue/utility-functions#router){rel="&#x22;nofollow&#x22;"}
- [`createAnimation`](https://ionicframework.com/docs/utilities/animations){rel="&#x22;nofollow&#x22;"}
- [`createGesture`](https://ionicframework.com/docs/utilities/gestures){rel="&#x22;nofollow&#x22;"}
- [`getTimeGivenProgression`](https://github.com/ionic-team/ionic-framework/blob/main/core/src/utils/animation/cubic-bezier.ts#L20){rel="&#x22;nofollow&#x22;"}
- [`iosTransitionAnimation`](https://github.com/ionic-team/ionic-framework/blob/main/core/src/utils/transition/ios.transition.ts#L267){rel="&#x22;nofollow&#x22;"}
- [`mdTransitionAnimation`](https://github.com/ionic-team/ionic-framework/blob/main/core/src/utils/transition/md.transition.ts#L6){rel="&#x22;nofollow&#x22;"}

::callout{color="info" icon="i-lucide-info"}
Read more about these 

[helper functions in Ionic's docs](https://ionicframework.com/docs/){rel=""nofollow""}

.
::


# Module Utilities

This modules aims to provide a few components and helpers for an easier and more seamless integration of Ionic's composables or functions in your app. We currently have the one `IonAnimation` component.

## Components

### `IonAnimation` component

This component makes using Ionic's `createAnimation` easier. It matches the majority of props directly to the usual Ionic animation object, to make adoption easier.

For more information, see [official Ionic docs](https://ionicframework.com/docs/utilities/animations){rel="&#x22;nofollow&#x22;"} or check out the [playground examples](https://github.com/nuxt-modules/ionic/blob/main/playground/pages/tabs/tab4.vue){rel="&#x22;nofollow&#x22;"}

You can see how it replaces usage of the regular [`createAnimation`](https://ionicframework.com/docs/utilities/animations#installation){rel="&#x22;nofollow&#x22;"} function in the code example below:

::code-group
```vue [IonAnimation]
<template>
  <IonAnimation
    :duration="3000"
    :iterations="Infinity"
    :keyframes="[
      { offset: 0, background: 'red' },
      { offset: 0.72, background: 'var(--background)' },
      { offset: 1, background: 'green' },
    ]"
    playOnMount
  >
    <!-- Content to animate -->
  </IonAnimation>
</template>
```

```vue [Manual usage]
<script setup lang="ts">
// Template ref of your element
const squareRef = ref()

// Your animation object
const animation = createAnimation()
  .addElement(squareRef.value)
  .duration(3000)
  .iterations(Infinity)
  .keyframes([
    { offset: 0, background: 'red' },
    { offset: 0.72, background: 'var(--background)' },
    { offset: 1, background: 'green' },
  ])

onMounted(() => {
  animation.play()
})
</script>
```
::

::callout{color="info" icon="i-lucide-info"}
Currently component doesn't support grouped and chained animations. For that usage we still recommend using 

`createAnimation`

 by itself
::


# Icons

Icons are auto-imported from [`ionicons/icons`](https://github.com/ionic-team/ionicons){rel="&#x22;nofollow&#x22;"} by default, following the pattern of camel case naming with `ionicons` in front of the original icon name, that you can find on the [official ionicons website](https://ionic.io/ionicons){rel="&#x22;nofollow&#x22;"}.

::code-group
```vue [Auto-imported icons]
<template>
  <ion-icon :icon="ioniconsImage"></ion-icon>
  <ion-icon :md="ioniconsSquareSharp" :ios="ioniconsTriangleOutline"></ion-icon>
</template>
```

```vue [Manual imports]
<script setup lang="ts">
import { image, squareSharp, triangleOutline } from 'ionicons/icons'
</script>

<template>
  <ion-icon :icon="image"></ion-icon>
  <ion-icon :md="squareSharp" :ios="triangleOutline"></ion-icon>
</template>
```
::

You can opt-out of auto-importing icons by setting the `integrations.icons` module options in your `nuxt.config.ts` to `false`.

```js
export default defineNuxtConfig({
  ionic: {
    integrations: {
      icons: false,
    },
  },
})
```


# Deployment

## Web

Deployment on the web is the same as any Nuxt project. You can find more information for this in Nuxt's deployment documentation.

::callout{color="info" icon="i-lucide-info"}
Read more about 

[deploying to the web](https://nuxt.com/docs/getting-started/deployment){rel=""nofollow""}

.
::

## iOS and Android

For iOS and Android, it's a little more involved. We recommend looking at the deployment documentation from Ionic for these platforms:

### iOS

<https://ionicframework.com/docs/deployment/app-store>{rel="&#x22;nofollow&#x22;"}

### Android

<https://ionicframework.com/docs/deployment/play-store>{rel="&#x22;nofollow&#x22;"}


# Customising app.vue

This module provides a default `app.vue` file for when one is not otherwise provided by your app.

If you need to customize this `app.vue` file, you can create a new one in your project's source directory, based off the default:

```vue [app.vue]
<template>
  <ion-app>
    <ion-router-outlet />
  </ion-app>
</template>
```

This module will then stop providing one, so that your project's `app.vue` is used instead.

## Necessary ion tags

It's necessary that `<ion-app>` and `<ion-router-outlet>` are provided in your `app.vue` for Ionic to function.

`<ion-app>` is the container element of Ionic - there should be only one per project - and is required for certain behaviours to work. Please see the [Ionic ion-app documentation](https://ionicframework.com/docs/api/app){rel="&#x22;nofollow&#x22;"} for more info.

Equally, `<ion-router-outlet>` provides a mounting point for the route component. In regular Nuxt applications,
this would be `<NuxtPage />`, but as Ionic Router is handling our routing we must use the `<ion-router-outlet>`.

::callout{color="warning" icon="i-lucide-alert-triangle"}
Remember that app.vue acts as the main component of your Nuxt application. Anything you add to it (JS and CSS) will be global and included in every page. Read more about app.vue 

[in the Nuxt app.vue docs](https://nuxt.com/docs/guide/directory-structure/app){rel=""nofollow""}

.
::


# Local Development

::callout{color="info" icon="i-lucide-info"}
You may find the Ionic docs on developing 

[for iOS](https://ionicframework.com/docs/developing/ios){rel=""nofollow""}

 and 

[for Android](https://ionicframework.com/docs/developing/android){rel=""nofollow""}

 helpful before continuing.
::

When using Ionic just for the web, local development is as easy as running the `dev` script provided by Nuxt:

::code-group
```bash [yarn]
yarn dev -o
```

```bash [npm]
npm run dev -- -o
```

```bash [pnpm]
pnpm dev -o
```
::

But when working with iOS and Android, we're required to sync our built project to XCode and Android Studio, [using `npx cap sync`](https://capacitorjs.com/docs/cli/commands/sync){rel="&#x22;nofollow&#x22;"}.

This manual process can be tedious, but capacitor provides a way to livereload in development mode. This allows you to test on a native device or a device simulator and maintain the hot module replacement or livereload functionality that you enjoy already with Nuxt on the web.

## Native device or simulator

First, ensure your Nuxt development build is created and the development server is running:

::code-group
```bash [yarn]
yarn dev -o
```

```bash [npm]
npm run dev -- -o
```

```bash [pnpm]
pnpm dev -o
```
::

Then, in a separate tab, [sync the build](https://ionicframework.com/docs/cli/commands/capacitor-sync){rel="&#x22;nofollow&#x22;"} to ios or android, based on the device you wish to run it on (or both). This copies the web build and capacitor configuration file into the native platform project, then updates the native plugins referenced in `package.json`, and installs any discovered capacitor or cordova plugins.

::code-group
```bash [ios]
npx @ionic/cli capacitor sync ios --no-build
```

```bash [android]
npx @ionic/cli capacitor sync android --no-build
```
::

Then to deploy this to a native device or device simulator with livereload, you can [ask Capacitor to run the build](https://ionicframework.com/docs/cli/commands/capacitor-run){rel="&#x22;nofollow&#x22;"}. Ensure your native device is plugged in so that it displays in your list.

::code-group
```bash [ios]
npx @ionic/cli capacitor run ios --livereload-url=http://${LIP}:3000  --external --mode development
```

```bash [android]
npx @ionic/cli capacitor run android --livereload-url=http://${LIP}:3000  --external --mode development
```
::

The app will then open on the chosen native device or device simulator.

## Automating on-device dev

We recommend putting this into a script in `scripts/` that you can run more easily via `yarn run` or `pnpm run`. For example:

::code-group
```bash [scripts/android.sh]
#!/bin/bash
LIP=$(ipconfig getifaddr en0)

echo "🍦 Starting local development to android device - ensure local dev server is running already"
echo "🏗️ Type checking and building for development..."
pnpm run build:dev
echo "🔃 Capacitor installation, podfile installation, sync and copy to app distribution folders..."
npx @ionic/cli capacitor sync android --no-build
echo "🏃 Select an Android device to run the build at local ip address ${LIP} on..."
eval "npx @ionic/cli capacitor run android --livereload-url=http://${LIP}:3000  --external --mode development"
```

```bash [scripts/ios.sh]
#!/bin/bash
LIP=$(ipconfig getifaddr en0)

echo "🍦 Starting local development to ios device - ensure local dev server is running already"
echo "🏗️ Type checking and building for development..."
pnpm run build:dev
echo "🔃 Capacitor installation, podfile installation, sync and copy to app distribution folders..."
npx @ionic/cli capacitor sync ios --no-build
echo "🏃 Select an iOS device to run the build at local ip address ${LIP} on..."
eval "npx @ionic/cli capacitor run ios --livereload-url=http://${LIP}:3000  --external --mode development"
```
::

```json [package.json]
{
  "scripts": {
    "android": "bash ./scripts/android.sh",
    "ios": "bash ./scripts/ios.sh"
  }
}
```

::code-group
```bash [yarn]
yarn ios
yarn android
```

```bash [npm]
npm run ios
npm run android
```

```bash [pnpm]
pnpm run ios
pnpm run android
```
::

::callout{color="warning" icon="i-lucide-alert-triangle"}
If you're having trouble with this step, please check the Ionic guides for 

[deploying to iOS](https://ionicframework.com/docs/developing/ios){rel=""nofollow""}

 and 

[deploying to android](https://ionicframework.com/docs/developing/android){rel=""nofollow""}

 for more information.
::


# App Tabs

It's common for mobile apps to come with tabs at the bottom of the screen. These tabs act as separate routing stacks, so should remember where they were when a user navigates away and back to a tab.

Ionic provides several components to provide App Tabs out of the box, with a deep integration with the Ionic Router for them.

::callout{color="info" icon="i-lucide-info"}
Read more about 

[Ionic's `ion-tabs` here](https://ionicframework.com/docs/api/tabs){rel=""nofollow""}

.
::

## Setup an application with tabs

> See the example in [the playground](https://github.com/nuxt-modules/ionic/blob/main/playground){rel="&#x22;nofollow&#x22;"} for a working demo of an app with tabs.

Tabs require a main tab component, and then child components to be rendered in the tab view.

Your file structure should look like this:

```text [pages/ directory]
pages/
--| tabs.vue
--| tabs/
----| tab1.vue
----| tab2.vue
----| tab3.vue
----| tab4.vue
```

These tabs should then have a similar code structure as shown below. Remember, all pages must start with an `ion-page` component.

::code-group
```vue [pages/tabs.vue]
<template>
  <ion-page>
    <ion-content>
      <ion-tabs>
        <ion-router-outlet />
        
        <ion-tab-bar slot="bottom">
          <ion-tab-button tab="tab1" href="/tabs/tab1">
            <ion-icon :icon="ioniconsHomeOutline" />
            <ion-label>Tab 1</ion-label>
          </ion-tab-button>

          <ion-tab-button tab="tab2" href="/tabs/tab2">
            <ion-icon :icon="ioniconsImagesOutline" />
            <ion-label>Photos</ion-label>
          </ion-tab-button>

          <ion-tab-button tab="tab3" href="/tabs/tab3">
            <ion-icon :icon="ioniconsBulbOutline" />
            <ion-label>Tab 3</ion-label>
          </ion-tab-button>

          <ion-tab-button tab="tab4" href="/tabs/tab4">
            <ion-icon :icon="ioniconsAccessibilityOutline" />
            <ion-label>Animation examples</ion-label>
          </ion-tab-button>
        </ion-tab-bar>
      </ion-tabs>
    </ion-content>
  </ion-page>
</template>
```

```vue [pages/tabs/tab1.vue]
<template>
  <ion-page>
    <ion-header>
      <ion-toolbar>
        <ion-title>Tab 1</ion-title>
      </ion-toolbar>
    </ion-header>
    <ion-content>
      Tab 1 content
    </ion-content>
  </ion-page>
</template>
```

```vue [pages/tabs/tab2.vue]
<template>
  <ion-page>
    <ion-header>
      <ion-toolbar>
        <ion-title>Tab 2</ion-title>
      </ion-toolbar>
    </ion-header>
    <ion-content>
      Tab 2 content
    </ion-content>
  </ion-page>
</template>
```
::

All pages that should show inside these tabs must be **sibling routes** of these initial tab views, but with the name of the tab in its prefix.

The simplest way to manage this is for all pages being within this `pages/tabs/` directory, with a directory per tab, like so:

```text [pages/ directory]
pages/
--| tabs.vue
--| tabs/
----| tab1/
------| index.vue
------| a-page.vue
----| tab2/
------| index.vue
----| tab3/
------| index.vue
----| tab4.vue
------| index.vue
------| another-page.vue
```

If a particular tab only has one route component, you don't explicitly need the directory for it with the index.vue inside
of it, but we find it's a neater approach this way.

Using these directories avoids the routes becoming children routes of the tab by accident. The following folder structure is incorrect and would result in children routes, which IonRouter will not serve correctly:

::list{type="danger"}
- An example of incorrect routing (do not copy):
::

```text [pages/ directory]
pages/
--| tabs.vue
--| tabs/
----| tab1.vue
----| tab1/
------| a-page.vue
----| tab2.vue
----| tab3.vue
----| tab4.vue
----| tab4/
------| another-page.vue
```

::callout{color="success" icon="i-lucide-check-circle"}
Ionic provides an article on 

[best practices for using tabs in your application](https://ionicframework.com/docs/vue/navigation#working-with-tabs){rel=""nofollow""}

.
::

## Routing to pages that shouldn't be displayed in the tabs

If you'd like to surface a page on-top of the tabs, rather than inside one of them, you can include the page component outside
of the tabs directory.

```text [pages/ directory]
pages/
--| tabs.vue
--| tabs/
----| tab1/
------| index.vue
------| a-page.vue
----| tab2/
------| index.vue
--| settings.vue
```

::list{type="danger"}
- 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';`.
::

## Reusing views across tabs

Some apps may require showing the same component in different tabs. For instance, Spotify will allow you to view an album from both the Home and the Search tab.

To best accomplish this with Nuxt's file-based routing, create the routes using vue components in `pages/tabs`, and have them include the same component.

::code-group
```text [pages/ directory]
pages/
--| tabs.vue
--| tabs/
----| home/
------| index.vue
------| album-[id].vue
----| search/
------| index.vue
------| album.vue
----| library/
------| index.vue
```

```vue [pages/home/album-{id}.vue] {0} [pages/home/album-.vue]
<template>
  <SingleAlbumView />
</template>
```

```vue [pages/search/album-{id}.vue] {0} [pages/search/album-.vue]
<template>
  <SingleAlbumView />
</template>
```
::

::callout{color="info" icon="i-lucide-info"}
Read more about 

[reusing views across tabs in the Ionic docs](https://ionicframework.com/docs/vue/navigation#switching-between-tabs){rel=""nofollow""}

.
::


# useHead / Page Meta

::callout{color="warning" icon="i-lucide-alert-triangle"}
⚠️ This page is a stub and needs further information.
::

The composable `useHead()` will not work out of the box.

Please see this issue for reference: <https://github.com/nuxt-modules/ionic/issues/6>{rel="&#x22;nofollow&#x22;"}

Also see the documentation for use-head: <https://nuxt.com/docs/api/composables/use-head>{rel="&#x22;nofollow&#x22;"}


# iOS and Android Apps

::callout{color="warning" icon="i-lucide-alert-triangle"}
⚠️ This page is a stub and needs further information.
::

When building for iOS and Android, we recommend setting `ssr: false` in your nuxt config

```js [nuxt.config.ts]
export default defineNuxtConfig({
  modules: ['@nuxtjs/ionic'],
  ssr: false,
})
```

Also see:

- <https://ionicframework.com/docs/developing/ios>{rel="&#x22;nofollow&#x22;"}
- <https://ionicframework.com/docs/developing/android>{rel="&#x22;nofollow&#x22;"}
- <https://ionicframework.com/docs/deployment/app-store>{rel="&#x22;nofollow&#x22;"}
- <https://ionicframework.com/docs/deployment/play-store>{rel="&#x22;nofollow&#x22;"}

Please also see our page on (building for both Web and Device together)(/cookbook/web-and-device)


# Web And Device

Here we talk a little about some differences in deploying to native devices over the web, and what is required from the codebase to do so. We then explore some potential solutions to solve these issues.

## Building for native devices

One main caveat of building for native devices is that the final build needs to be able to run completely
clientside. Another is that deploying a new build requires submitting to the app stores and being manually reviewed and approved.

This makes building for devices more cumbersome than deploying to the web, and means the following must be followed when deploying:

::list{type="danger"}
- **No serverside rendering in the codebase**:br
  As the build must be able to run completely clientside, we cannot have serverside rendering in the codebase.
- **Generating new builds are not quickly deployed**:br
  A common paradigm on the web is to use serverside generation to build an app from stable data, then push the bundle to the web. This is then re-generated based on CMS changes or other triggers to ensure a static site that can stay up-to-date. :br As deploying to the app stores is much slower than to the web, this approach likely will not work anymore.
::

This means, in the codebase that will be deployed to the devices, we recommend using `ssr: false`, and not using serverside rendering at all.

If serverside rendering is required on the web, the simplest solution is to create two Nuxt projects: one targeting the web with SSR/SSG, and one targeting devices.

## Further Solutions

Having two completely separate codebases to target web and device is a little cumbersome, so there are some potential solutions you could explore.

These solutions are outside of the scope of this module, but are provided as guidance on improving your own DX in these cases. We'd love to hear about if you implement these successfully.

### A single codebase

It may be possible to have a single codebase with both SSR and a fully static application in-tandem, with code-switching based on configuration. E.G. when building for the web, setting `ssr: true`, and when building for devices, setting `ssr: false`.

You may need further wrapping around other SSR-aware code and utilities, such as `useAsyncData()`.

### A monorepo

You would likely be able to reduce the burden of two separate Nuxt apps by utilising a monorepo. The majority of your shared code could exist within a core package, while having two Nuxt apps, one to target Web with `ssr: true` and one to target devices with `ssr: false`.

A possible directory structure for this may look like:

```text
- apps
  - nuxt-web
    - ...
    - nuxt.config.ts
  - nuxt-device
    - ...
    - nuxt.config.ts
- packages
  - core
    - components
    - composables
    - ...
```


# Live Updates

Live Updates, also known as Over-the-Air (OTA) or hot code updates, are a way to push updates to your Android or iOS app without going through the app store review process. This is particularly useful for bug fixes or minor updates that don't require a full app release.

There are several providers that offer live update services, including:

- [Capawesome Cloud](https://cloud.capawesome.io/){rel="&#x22;nofollow&#x22;"}
- [CodePush (standalone)](https://github.com/microsoft/code-push-server){rel="&#x22;nofollow&#x22;"}

## Capawesome Cloud

This guide demonstrates how to implement live updates using Capawesome Cloud.

### Installation

To enable Live Updates with Capawesome Cloud, you need to install the `@capawesome/capacitor-live-update` plugin:

```bash
npm install --save @capawesome/capacitor-live-update
```

After that, you need to sync the changes with your native projects:

```bash
npx cap sync
```

### Configuration

Next, you need to configure the plugin to work with [Capawesome Cloud](https://cloud.capawesome.io/){rel="&#x22;nofollow&#x22;"}.

#### App ID

In order for your app to identify itself to Capawesome Cloud, you need to set the `appId` in your `capacitor.config` file. For this, you need to create an app on the [Capawesome Cloud Console](https://console.cloud.capawesome.io/){rel="&#x22;nofollow&#x22;"} and get the App ID.

```json
{
  "plugins": {
    "LiveUpdate": {
      "appId": "00000000-0000-0000-0000-000000000000"
    }
  }
}
```

Replace `00000000-0000-0000-0000-000000000000` with your actual App ID from the Capawesome Cloud Console.

After configuring the App ID, sync your Capacitor project again:

```bash
npx cap sync
```

### Usage

The most basic usage of the Live Update plugin is to call the [`sync(...)`](https://capawesome.io/plugins/live-update/#sync){rel="&#x22;nofollow&#x22;"} method when the app starts. This method checks for updates, downloads them if available, and sets them as the next bundle to be applied. You can then call the [`reload()`](https://capawesome.io/plugins/live-update/#reload){rel="&#x22;nofollow&#x22;"} method to apply the update immediately. If the [`reload()`](https://capawesome.io/plugins/live-update/#reload){rel="&#x22;nofollow&#x22;"} method is not called, the new bundle will be used on the next app start.

```js
import { LiveUpdate } from "@capawesome/capacitor-live-update"

const sync = async () => {
  const result = await LiveUpdate.sync()
  if (result.nextBundleId) {
    await LiveUpdate.reload()
  }
}
```

### Publishing updates

To publish your first update, you need to [create a bundle](https://capawesome.io/cloud/live-updates/bundles/#create-a-bundle){rel="&#x22;nofollow&#x22;"} on Capawesome Cloud. For this, you need a bundle artifact. A bundle artifact is the build output of your web app. In Nuxt, this is the `dist` folder. You can create a bundle artifact by running the following command:

#### Building your app

Generate the production build of your Nuxt app:

```bash
npx nuxt generate
```

This creates a `dist` folder with the build output of your web app.

#### Publishing with Capawesome CLI

To install the Capawesome CLI,run the following command:

```bash
npm i -g @capawesome/cli
```

After installing the Capawesome CLI, you need to log in to your Capawesome Cloud account. Run the following command and follow the instructions:

```bash
npx capawesome login
```

Once you are logged in, you can create a bundle by running the following command:

```bash
npx capawesome apps:bundles:create --path dist
```

Congratulations! You have successfully published your first live update. You can now test it by running your app on a device or emulator. The app will check for updates and apply them if available.
Feel free to check out the [documentation](https://capawesome.io/plugins/live-update/){rel="&#x22;nofollow&#x22;"} of the Live Update plugin to see what else you can do with it.

## Other providers

For other live update providers, consult their respective documentation for the specific upload process and tooling requirements.

::callout{color="info" icon="i-lucide-info"}
We'd welcome PRs to add examples for other providers.
::


# Get Started

::u-page-hero
---
orientation: horizontal
---
```bash [Terminal]
npx nuxi@latest module add ionic
```

#title
Nuxt [Ionic]{style="color:var(--color-primary-500);"}

#description
Batteries-included [Ionic](https://ionicframework.com/){rel=""nofollow""} integration for Nuxt.

- Zero-config required
- Auto-import Ionic components, composables and icons
- Ionic Router integration
- Pre-render routes
- Mobile meta tags
- Works out of the box with [Capacitor](https://capacitorjs.com/){rel=""nofollow""} to build mobile apps

#links
  :::u-button
  ---
  size: xl
  to: https://ionic.nuxtjs.org/get-started/introduction
  trailing-icon: i-lucide-arrow-right
  ---
  Get started
  :::

  :::u-button
  ---
  color: neutral
  icon: simple-icons-github
  size: xl
  to: https://github.com/nuxt-modules/ionic
  variant: outline
  ---
  Star on GitHub
  :::
::