Nuxt Ionic

repository·main·Indexed 19 days ago

https://github.com/nuxt-modules/ionic

A Nuxt module providing a zero-config integration of the Ionic SDK. It enables the development of mobile-optimized web applications and native mobile apps via Capacitor, featuring auto-imports for Ionic components, composables, and icons, as well as integrated routing and pre-rendering support.

Tokens
13.7K
Snippets
50
Records
67
Agent score
65%

What's inside @nuxtjs/ionic

  1. Overview of Nuxt Ionic features

    main

    Nuxt Ionic provides a batteries-included integration for the Ionic framework within Nuxt applications. Key features include:

    • Zero-config required: Works immediately after installation.
    • Auto-imports: Automatically imports Ionic components, composables, and icons so they are available in your templates and scripts without manual import statements.
    • Ionic Router integration: Seamlessly integrates Ionic's routing capabilities with Nuxt.
    • Pre-render routes: Supports pre-rendering for optimized performance.
    • Mobile meta tags: Automatically manages necessary meta tags for mobile web experiences.
    • Capacitor support: Works out of the box with Capacitor for building native mobile applications.
  2. Overview of Nuxt Ionic

    main

    Nuxt Ionic provides an integration between Ionic and Nuxt. It is designed to streamline the development of mobile-friendly web applications and mobile apps using Capacitor.

    Key features include:

    • Zero-config: Works out-of-the-box without extensive setup.
    • Auto-imports: Automatically imports Ionic components, composables, and icons.
    • Ionic Router integration: Seamlessly integrates Ionic's routing capabilities with Nuxt.
    • Pre-rendering: Supports pre-rendering of routes.
    • Mobile optimization: Includes mobile meta tags and works natively with Capacitor for mobile app builds.
  3. Compare `IonAnimation` component vs manual `createAnimation` usage

    main

    While IonAnimation provides a declarative way to handle animations via props, the manual createAnimation approach is still required for complex logic, such as chaining animations or managing specific element references via template refs.

    IonAnimation approach

    Best for simple, single-sequence animations using props like :duration, :iterations, and :keyframes.

    Manual createAnimation approach

    Best for complex animations, grouped animations, or when you need fine-grained control over when the animation plays (e.g., inside onMounted).

    <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>
  4. Strategies for managing Web and Native device codebases

    main

    If your project requires Server-Side Rendering (SSR) for the web but must be a static client-side app for native devices, consider one of the following architectural patterns:

    1. Two Separate Nuxt Projects

    Create one Nuxt project optimized for the web (using ssr: true or SSG) and a second, separate Nuxt project optimized for devices (using ssr: false).

    2. Single Codebase with Configuration Switching

    Maintain one codebase and use environment variables or configuration to switch modes. For example, set ssr: true during web builds and ssr: false during device builds.

    Note: You may need to wrap SSR-specific utilities like useAsyncData() to ensure they behave correctly in a client-only environment.

    3. Monorepo Approach

    Use a monorepo to share business logic and UI components while maintaining two distinct Nuxt applications. This reduces duplication while allowing different configurations for each target.

    Example Monorepo Structure:

    - apps
      - nuxt-web
        - ...
        - nuxt.config.ts (ssr: true)
      - nuxt-device
        - ...
        - nuxt.config.ts (ssr: false)
    - packages
      - core
        - components
        - composables
        - ...
    - apps
      - nuxt-web
        - ...
        - nuxt.config.ts
      - nuxt-device
        - ...
        - nuxt.config.ts
    - packages
      - core
        - components
        - composables
        - ...
  5. Key features of @nuxtjs/ionic

    main

    The module provides several core features to streamline Ionic development within Nuxt:

    • Ionic router integration: You can continue defining routes based on your ~/pages directory structure and use page-level utilities like definePageMeta().
    • Auto-imports: Ionic components, composables, and icons are automatically imported, reducing boilerplate.
    • Helpful components and utilities: Includes specialized components and utilities for common mobile development tasks.
    • Pre-render routes: Supports pre-rendering for optimized performance.
    • Mobile meta tags: Automatically handles mobile-specific meta tags.
    • Capacitor integration: Works out-of-the-box with Capacitor for deploying to native iOS and Android platforms.
  6. Understand SSR Limitations in Nuxt Ionic

    main

    Nuxt Ionic applications cannot use Server-Side Rendering (SSR).

    When targeting native platforms like iOS or Android, the entire application must be capable of running exclusively on the client-side. If your application needs to support both web (SSR) and native devices, you must implement specific architectural patterns to handle the client-only requirement for native builds.

  7. Required Ionic tags in app.vue

    main

    When customizing your app.vue, you must include these two specific components to maintain Ionic's core functionality:

    1. <ion-app>: The mandatory top-level container element for Ionic. There should be exactly one per project. It is required for various Ionic behaviors to work correctly.
    2. <ion-router-outlet>: The mounting point for routed components. While standard Nuxt applications use <NuxtPage />, this module requires <ion-router-outlet> because the Ionic Router is managing the application's routing.
  8. Handle Lifecycle Hooks and Vue Components

    main

    Ionic manages the DOM differently than standard Vue; it persists components in the DOM instead of unmounting them immediately. This affects how lifecycle hooks and certain Vue components behave.

    Lifecycle Hooks

    Standard Vue hooks like onBeforeMount may not trigger when expected because Ionic keeps pages in the stack. Use Ionic Vue lifecycle hooks to ensure code runs at the correct time during page entry and exit.

    Component Compatibility

    • Avoid: <keep-alive>, <transition>, and <router-view>. These conflict with Ionic's internal lifecycle management.
    • useHead() Warning: The Nuxt composable useHead() will not work out of the box due to the way pages are kept in the DOM. Refer to the cookbook for the correct implementation pattern.
  9. How IonRouter works in Nuxt Ionic

    main

    The module uses IonRouter, which is built on top of vue-router but optimized for mobile applications. It enables features like non-linear routing (essential for application tabs), separate navigation stacks for each tab, and rich mobile-appropriate page transitions.

    Important Constraints:

    • You must avoid using <NuxtPage> or <NuxtLayout> because Ionic requires an <ion-router-outlet> to manage its navigation stack and transitions correctly.
    • Every page component must have <ion-page> as its root element to ensure transitions and stack navigation function properly.
    <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>
  10. Use auto-imported Ionic Vue components

    main

    The @nuxtjs/ionic module automatically auto-imports all Ionic Vue components throughout your application. You do not need to manually import components like <IonButton>, <IonContent>, or others in your <script> blocks.

    Key details:

    • Components are not globally registered; they are imported only within the specific components that use them.
    • Your IDE should recognize these components, but if you encounter issues, ensure your Nuxt project is correctly configured with the module.
    • For a complete list of available components, refer to the official Ionic component documentation.
  11. Enable Capacitor in your Nuxt Ionic project

    main

    Capacitor is installed by default with @nuxtjs/ionic. To enable it and add native platforms, use the Ionic CLI. You can use npx to run commands without a global installation, or configure your npmClient if using a global ionic installation.

    npx @ionic/cli integrations enable capacitor
    npx @ionic/cli capacitor add ios
    npx @ionic/cli capacitor add android

    Using global Ionic CLI

    Depending on your package manager, first set the client, then enable Capacitor and add platforms:

    npm:

    # ionic config set -g npmClient npm
    ionic integrations enable capacitor
    ionic capacitor add ios
    ionic capacitor add android

    yarn:

    # ionic config set -g npmClient yarn
    ionic integrations enable capacitor
    ionic capacitor add ios
    ionic capacitor add android

    pnpm:

    # ionic config set -g npmClient pnpm
    ionic integrations enable capacitor
    ionic capacitor add ios
    ionic capacitor add android
    npx @ionic/cli integrations enable capacitor
    npx @ionic/cli capacitor add ios
    npx @ionic/cli capacitor add android