[
{
"path": ".editorconfig",
"content": "root = true\n\n[*]\nindent_size = 2\nindent_style = space\nend_of_line = lf\ncharset = utf-8\ntrim_trailing_whitespace = true\ninsert_final_newline = true\n\n[*.md]\ntrim_trailing_whitespace = false\n"
},
{
"path": ".github/FUNDING.yml",
"content": "github: [danielroe]\n"
},
{
"path": ".github/ISSUE_TEMPLATE/bug-report.yml",
"content": "name: \"\\U0001F41B Bug report\"\ndescription: Something's not working\nlabels: [\"bug\"]\nbody:\n - type: textarea\n validations:\n required: true\n attributes:\n label: ๐ The bug\n description: What isn't working? Describe what the bug is.\n - type: input\n validations:\n required: true\n attributes:\n label: ๐ ๏ธ To reproduce\n description: A reproduction of the bug via https://stackblitz.com/github/nuxt-modules/ionic/tree/main/playground\n placeholder: https://stackblitz.com/[...]\n - type: textarea\n validations:\n required: true\n attributes:\n label: ๐ Expected behaviour\n description: What did you expect to happen? Is there a section in the docs about this?\n - type: textarea\n attributes:\n label: โน๏ธ Additional context\n description: Add any other context about the problem here.\n"
},
{
"path": ".github/ISSUE_TEMPLATE/config.yml",
"content": "contact_links:\n - name: Nuxt Community Discord\n url: https://discord.nuxtjs.org/\n about: Consider asking questions about the module here.\n"
},
{
"path": ".github/ISSUE_TEMPLATE/documentation.yml",
"content": "name: \"\\U0001F4DA Documentation\"\ndescription: How do I ... ?\nlabels: [\"documentation\"]\nbody:\n - type: textarea\n validations:\n required: true\n attributes:\n label: ๐ Is your documentation request related to a problem?\n description: A clear and concise description of what the problem is.\n placeholder: I feel I should be able to [...] but I can't see how to do it from the docs.\n - type: textarea\n attributes:\n label: ๐ Where should you find it?\n description: What page of the docs do you expect this information to be found on?\n - type: textarea\n attributes:\n label: โน๏ธ Additional context\n description: Add any other context or information.\n"
},
{
"path": ".github/ISSUE_TEMPLATE/feature-suggestion.yml",
"content": "name: \"\\U0001F195 Feature suggestion\"\ndescription: Suggest an idea\nlabels: [\"enhancement\"]\nbody:\n - type: textarea\n validations:\n required: true\n attributes:\n label: ๐ Your use case\n description: Add a description of your use case, and how this feature would help you.\n placeholder: When I do [...] I would expect to be able to do [...]\n - type: textarea\n validations:\n required: true\n attributes:\n label: ๐ The solution you'd like\n description: Describe what you want to happen.\n - type: textarea\n attributes:\n label: ๐ Alternatives you've considered\n description: Have you considered any alternative solutions or features?\n - type: textarea\n attributes:\n label: โน๏ธ Additional info\n description: Is there any other context you think would be helpful to know?\n"
},
{
"path": ".github/ISSUE_TEMPLATE/help-wanted.yml",
"content": "name: \"\\U0001F198 Help\"\ndescription: I need help with ...\nlabels: [\"help\"]\nbody:\n - type: textarea\n validations:\n required: true\n attributes:\n label: ๐ What are you trying to do?\n description: A clear and concise description of your objective.\n placeholder: I'm not sure how to [...].\n - type: textarea\n attributes:\n label: ๐ What have you tried?\n description: Have you looked through the docs? Tried different approaches? The more detail the better.\n - type: textarea\n attributes:\n label: โน๏ธ Additional context\n description: Add any other context or information.\n"
},
{
"path": ".github/workflows/ci.yml",
"content": "name: ci\n\non:\n pull_request:\n branches:\n - main\n - renovate/*\n push:\n branches:\n - main\n\njobs:\n lint:\n if: github.event_name == 'pull_request' || github.event_name == 'push' && github.ref != 'refs/heads/renovate/*' || github.event_name == 'push' && github.ref == 'refs/heads/renovate/*' && github.event.pull_request == null\n runs-on: ubuntu-latest\n\n steps:\n - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6\n - run: corepack enable\n - uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6\n with:\n node-version: lts/*\n cache: 'pnpm'\n\n - name: ๐ฆ Install dependencies\n run: pnpm install --frozen-lockfile\n\n - name: ๐ง Set up project\n run: pnpm dev:prepare\n\n - name: ๐ Lint project\n run: pnpm run lint\n\n test:\n if: github.event_name == 'pull_request' || github.event_name == 'push' && github.ref != 'refs/heads/renovate/*' || github.event_name == 'push' && github.ref == 'refs/heads/renovate/*' && github.event.pull_request == null\n strategy:\n matrix:\n os: [ubuntu-latest, windows-latest]\n runs-on: ${{ matrix.os }}\n\n steps:\n - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6\n - run: corepack enable\n - uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6\n with:\n node-version: lts/-1\n cache: 'pnpm'\n\n - name: ๐ฆ Install dependencies\n run: pnpm install --frozen-lockfile\n\n - name: ๐ง Set up project\n run: pnpm dev:prepare\n\n - name: ๐ญ Set up playwright\n run: pnpm playwright-core install\n\n - name: ๐งช Test project\n run: pnpm test\n\n - name: ๐ช Test types\n run: pnpm test:types\n\n - name: ๐ Build project\n run: pnpm build\n\n - name: ๐ฉ Coverage\n if: matrix.os != 'windows-latest'\n uses: codecov/codecov-action@57e3a136b779b570ffcdbf80b3bdc90e7fab3de2 # v6\n env:\n CODECOV_TOKEN: ${{ secrets.CODECOV_TOKEN }}\n"
},
{
"path": ".github/workflows/provenance.yml",
"content": "name: ci\n\non:\n push:\n branches:\n - main\n pull_request:\n branches:\n - main\npermissions:\n contents: read\njobs:\n check-provenance:\n runs-on: ubuntu-latest\n steps:\n - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6\n with:\n fetch-depth: 0\n - name: Check provenance downgrades\n uses: danielroe/provenance-action@41bcc969e579d9e29af08ba44fcbfdf95cee6e6c # v0.1.1\n with:\n fail-on-provenance-change: true\n"
},
{
"path": ".github/workflows/release.yml",
"content": "name: Release\n\npermissions:\n contents: write\n\non:\n push:\n tags:\n - 'v*'\n workflow_dispatch:\n\njobs:\n release:\n runs-on: ubuntu-latest\n steps:\n - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6\n - run: corepack enable\n - uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6\n with:\n node-version: lts/*\n cache: 'pnpm'\n\n - run: npx changelogithub\n env:\n GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}\n"
},
{
"path": ".gitignore",
"content": "# Dependencies\nnode_modules\n\n# Capacitor projects\nplayground/android\nplayground/ios\n\n# Logs\n*.log*\n\n# Temp directories\n.temp\n.tmp\n.cache\n\n# Yarn\n**/.yarn/cache\n**/.yarn/*state*\n\n# Generated dirs\ndist\n\n# Nuxt\n.nuxt\n.output\n.vercel_build_output\n.build-*\n.env\n.netlify\n\n# Env\n.env\n\n# Testing\nreports\ncoverage\n*.lcov\n.nyc_output\n\n# VSCode\n.vscode\n\n# Intellij idea\n*.iml\n.idea\n\n# Zed\n.zed\n\n# OSX\n.DS_Store\n.AppleDouble\n.LSOverride\n.AppleDB\n.AppleDesktop\nNetwork Trash Folder\nTemporary Items\n.apdisk\n\nionic.config.json\n"
},
{
"path": "CODEOWNERS",
"content": "* @danielroe\n"
},
{
"path": "CODE_OF_CONDUCT.md",
"content": "# Contributor Covenant Code of Conduct\n\n## Our pledge\n\nIn the interest of fostering an open and welcoming environment, we as contributors and maintainers pledge to make participation in our project and our community a harassment-free experience for everyone, regardless of age, body size, disability, ethnicity, sex characteristics, gender identity and expression, level of experience, education, socio-economic status, nationality, personal appearance, race, religion, or sexual identity and orientation.\n\n## Our standards\n\nExamples of behavior that contributes to creating a positive environment include:\n\n- Using welcoming and inclusive language\n- Being respectful of differing viewpoints and experiences\n- Gracefully accepting constructive criticism\n- Focusing on what is best for the community\n- Showing empathy towards other community members\n\nExamples of unacceptable behavior by participants include:\n\n- The use of sexualized language or imagery and unwelcome sexual attention or advances\n- Trolling, insulting/derogatory comments, and personal or political attacks\n- Public or private harassment\n- Publishing others' private information, such as a physical or electronic address, without explicit permission\n- Other conduct which could reasonably be considered inappropriate in a professional setting\n\n## Our responsibilities\n\nProject maintainers are responsible for clarifying the standards of acceptable behavior and are expected to take appropriate and fair corrective action in response to any instances of unacceptable behavior.\n\nProject maintainers have the right and responsibility to remove, edit, or reject comments, commits, code, wiki edits, issues, and other contributions that are not aligned to this Code of Conduct, or to ban temporarily or permanently any contributor for other behaviors that they deem inappropriate, threatening, offensive, or harmful.\n\n## Scope\n\nThis Code of Conduct applies within all project spaces, and it also applies when an individual is representing the project or its community in public spaces. Examples of representing a project or community include using an official project e-mail address, posting via an official social media account, or acting as an appointed representative at an online or offline event. Representation of a project may be further defined and clarified by project maintainers.\n\n## Enforcement\n\nInstances of abusive, harassing, or otherwise unacceptable behavior may be reported by contacting the project team at [daniel@roe.dev](mailto:daniel@roe.dev). All complaints will be reviewed and investigated and will result in a response that is deemed necessary and appropriate to the circumstances. The project team is obligated to maintain confidentiality with regard to the reporter of an incident. Further details of specific enforcement policies may be posted separately.\n\nProject maintainers who do not follow or enforce the Code of Conduct in good faith may face temporary or permanent repercussions as determined by other members of the project's leadership.\n\n## Attribution\n\nThis Code of Conduct is adapted from the [Contributor Covenant][homepage], version 1.4, available at https://www.contributor-covenant.org/version/1/4/code-of-conduct.html\n\n[homepage]: https://www.contributor-covenant.org\n\nFor answers to common questions about this code of conduct, see https://www.contributor-covenant.org/faq\n"
},
{
"path": "LICENCE",
"content": "MIT License\n\nCopyright (c) 2022 Daniel Roe\n\nPermission is hereby granted, free of charge, to any person obtaining a copy\nof this software and associated documentation files (the \"Software\"), to deal\nin the Software without restriction, including without limitation the rights\nto use, copy, modify, merge, publish, distribute, sublicense, and/or sell\ncopies of the Software, and to permit persons to whom the Software is\nfurnished to do so, subject to the following conditions:\n\nThe above copyright notice and this permission notice shall be included in all\ncopies or substantial portions of the Software.\n\nTHE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\nIMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\nFITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\nAUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\nLIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\nOUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\nSOFTWARE.\n"
},
{
"path": "README.md",
"content": "[](https://ionic.nuxtjs.org)\n\n# Nuxt Ionic\n\n[![npm version][npm-version-src]][npm-version-href]\n[![npm downloads][npm-downloads-src]][npm-downloads-href]\n[![Github Actions][github-actions-src]][github-actions-href]\n[![Codecov][codecov-src]][codecov-href]\n[](https://nuxt.care/?search=ionic)\n\n> [Ionic](https://ionicframework.com/docs/) integration for [Nuxt](https://nuxtjs.org)\n\n- [โจ Changelog](https://github.com/nuxt-modules/ionic/blob/main/CHANGELOG.md)\n- [๐ Read the documentation](https://ionic.nuxtjs.org)\n- [โถ๏ธ Online playground](https://stackblitz.com/github/nuxt-modules/ionic/tree/main/playground)\n\n## Features\n\n- Zero-config required\n- Auto-import Ionic components, composables and icons\n- Ionic Router integration\n- Pre-render routes\n- Mobile meta tags\n- Works out-of-the-box with [Capacitor](https://capacitorjs.com/) to build mobile apps\n\n**In progress**\n\n- [ ] PWA Elements [#14](https://github.com/nuxt-modules/ionic/issues/14)\n\n## Usage\n\n๐ Check out https://ionic.nuxtjs.org.\n\n## ๐ป Development\n\n- Clone this repository\n- Enable [Corepack](https://github.com/nodejs/corepack) using `corepack enable`\n- Install dependencies using `pnpm install`\n- Stub module with `pnpm dev:prepare`\n- Run `pnpm dev` to start [playground](./playground) in development mode\n\n## License\n\nMade with โค๏ธ\n\nPublished under the [MIT License](./LICENCE).\n\n\n\n[npm-version-src]: https://npmx.dev/api/registry/badge/version/@nuxtjs/ionic\n[npm-version-href]: https://npmx.dev/package/@nuxtjs/ionic\n[npm-downloads-src]: https://npmx.dev/api/registry/badge/downloads/@nuxtjs/ionic\n[npm-downloads-href]: https://npm.chart.dev/@nuxtjs/ionic\n[github-actions-src]: https://img.shields.io/github/actions/workflow/status/nuxt-modules/ionic/ci.yml?style=flat-square&branch=main\n[github-actions-href]: https://github.com/nuxt-modules/ionic/actions?query=workflow%3Aci\n[codecov-src]: https://img.shields.io/codecov/c/gh/nuxt-modules/ionic/main?style=flat-square\n[codecov-href]: https://codecov.io/gh/nuxt-modules/ionic\n"
},
{
"path": "build.config.ts",
"content": "import { defineBuildConfig } from 'unbuild'\n\nexport default defineBuildConfig({\n // TODO: fix in unbuild\n externals: ['node:fs'],\n})\n"
},
{
"path": "docs/.gitignore",
"content": "node_modules\n*.iml\n.idea\n*.log*\n.nuxt\n.vscode\n.DS_Store\ncoverage\ndist\nsw.*\n.env\n.output\n.data"
},
{
"path": "docs/app.config.ts",
"content": "export default defineAppConfig({\n ui: {\n colors: {\n primary: 'blue',\n neutral: 'zinc',\n },\n },\n docus: {\n title: 'nuxt/ionic',\n url: 'https://ionic.nuxtjs.org/',\n description: 'Batteries-included Ionic integration for Nuxt.',\n socials: {\n twitter: 'danielcroe',\n github: 'nuxt-modules/ionic',\n },\n cover: {\n src: '/cover.jpg',\n alt: 'Nuxt Ionic module.',\n },\n github: {\n owner: 'nuxt-modules',\n repo: 'ionic',\n branch: 'main',\n root: 'docs/content',\n edit: true,\n },\n header: {\n logo: true,\n },\n footer: {\n credits: {\n icon: 'IconDocus',\n text: 'Powered by Docus',\n href: 'https://docus.com',\n },\n iconLinks: [\n {\n label: 'NuxtJS',\n href: 'https://nuxtjs.org',\n icon: 'IconNuxt',\n },\n ],\n },\n },\n})\n"
},
{
"path": "docs/assets/css/main.css",
"content": "@import \"tailwindcss\";\n@import \"@nuxt/ui\";\n\n\n:root {\n--color-blue: oklch(66.85% 0.17582 260.7);\n--color-blue-50: oklch(100% 0 none);\n--color-blue-100: oklch(98.081% 0.00906 258.34);\n--color-blue-200: oklch(89.967% 0.0486 260.89);\n--color-blue-300: oklch(82.018% 0.08975 261.51);\n--color-blue-400: oklch(74.222% 0.13277 261.06);\n--color-blue-500: oklch(66.85% 0.17582 260.7);\n--color-blue-600: oklch(57.957% 0.23039 261.17);\n--color-blue-700: oklch(49.935% 0.22723 261.78);\n--color-blue-800: oklch(40.624% 0.18173 261.53);\n--color-blue-900: oklch(30.965% 0.13179 260.75);\n--color-blue-950: oklch(25.869% 0.105 259.91);\n\n}"
},
{
"path": "docs/components/AppHeaderLogo.vue",
"content": "\n
\n \n \n \n \n Nuxt Ionic\n \n
\n\n\n\n"
},
{
"path": "docs/content/1.get-started/.navigation.yml",
"content": "icon: heroicons-outline:star\nnavigation.redirect: /get-started/introduction\n"
},
{
"path": "docs/content/1.get-started/1.introduction.md",
"content": "---\nnavigation.icon: uil:info-circle\ndescription: 'Batteries-included, zero-config needed, Ionic integration for Nuxt'\n---\n\n`@nuxtjs/ionic` provides a batteries-included, zero-config needed, Ionic integration for Nuxt.\n\nSupercharge your Ionic apps with the power of Nuxt, giving you the tremendous development experience you're used to\nwhen using Nuxt for web.\n\nFollow the installation guide to get going immediately, or continue reading to find out more about what this module provides.\n\n::callout{color=\"info\" icon=\"i-lucide-info\"}\nGet started with our [Installation guide](/get-started/installation).\n::\n\n## What is Ionic?\n\n[The Ionic SDK](https://ionicframework.com/) 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.\n\n::callout{color=\"info\" icon=\"i-lucide-info\"}\nRead the [Ionic documentation for Vue](https://ionicframework.com/docs/vue/overview) to learn more about Vue development with Ionic.\n::\n\n## Features\n\nThis 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.\n\n::list{type=success}\n- **Ionic router integration:** continue defining routes based on the structure of your `~/pages` directory and using page-level utilities such as `definePageMeta()`.\n- **Auto-imports**: Ionic components, composables and icons are all [auto-imported](https://nuxt.com/docs/guide/concepts/auto-imports) for ease of use.\n- **Helpful components and utilities**: This module provides components and utilities to accomplish common tasks more easily.\n- **Pre-render routes**\n- **Mobile meta tags**\n- **Capacitor integration**: works out-of-the-box with [Capacitor](https://capacitorjs.com/) for shipping to native platforms like iOS and Android.\n::\n\n::callout{color=\"info\" icon=\"i-lucide-info\"}\nRead more about [our features](/overview).\n::\n\n## Cookbook\n\nOur 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.\n\n::callout{color=\"info\" icon=\"i-lucide-info\"}\nDiscover common recipes in [our cookbook](/cookbook).\n::\n"
},
{
"path": "docs/content/1.get-started/2.installation.md",
"content": "---\nnavigation.icon: uil:play-circle\ndescription: 'Get started quickly by installing and setting up this module with the following instructions.'\n---\n\n## Prerequisites\n\n- A fresh or existing Nuxt project\n- [Nuxt's prerequisites](https://nuxt.com/docs/getting-started/installation#prerequisites)\n- [Ionic's environment setup](https://ionicframework.com/docs/intro/environment)\n- [Capacitor's enviroment setup](https://capacitorjs.com/docs/getting-started/environment-setup) if using iOS or Android\n\n## Installation\n\n::steps{level=3}\n\n### Add module\n\nAdd `@nuxtjs/ionic` to your project's dev dependencies:\n```bash [Terminal]\nnpx nuxi@latest module add ionic\n```\n\n### Nuxt Module\n\nNext, add the module to your Nuxt configuration in `nuxt.config.ts`.\n\n```js{}[nuxt.config.ts]\nexport default defineNuxtConfig({\n modules: ['@nuxtjs/ionic'],\n ssr: false,\n})\n```\n\n::callout{color=\"warning\" icon=\"i-lucide-alert-triangle\"}\nIf 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](/cookbook/web-and-device).\n::\n\nFinally, either remove your `app.vue` file or [replace it with a custom one](/cookbook/customising-app-vue).\n\n### Development Server\n\nNow you'll be able to start your Nuxt app in development mode as usual:\n\n::code-group\n\n```bash [yarn]\nyarn dev -o\n```\n\n```bash [npm]\nnpm run dev -- -o\n```\n\n```bash [pnpm]\npnpm dev -o\n```\n\n::\n::callout{color=\"success\" icon=\"i-lucide-check-circle\" .font-bold}\nWell done! A browser window should automatically open for .\n::\n\n\n::callout{color=\"info\" icon=\"i-lucide-info\"}\nThe 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.\n::\n\n::\n"
},
{
"path": "docs/content/1.get-started/3.configuration.md",
"content": "---\ntitle: Configuration\ndescription: >\n This module provides configuration options for itself, as well as passing through configuration for ionic.\n Configuration for capacitor is set in the usual way, via capacitor.config.ts.\nnavigation.icon: uil:wrench\n---\n\n\n\n### Module Config\n\nThis module exposes three keys for configuration: `integrations`, `css` and `config`:\n\n```js [nuxt.config.ts]\nexport default defineNuxtConfig({\n modules: ['@nuxtjs/ionic'],\n ionic: {\n integrations: {\n //\n },\n css: {\n //\n },\n config: {\n //\n }\n },\n})\n```\n\n#### `integrations`\n\nIntegrations 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.\n\n- **meta**\n\n Default: `true` \n Disable to take full control of meta tags.\n\n- **router**\n\n Default: `true` \n Disable to configure Ionic Router yourself.\n\n- **icons**\n\n Default: `true` \n Disable to stop icons from being auto-imported.\n\n#### `css`\n\nConfigure which Ionic stylesheets are automatically added to your application. For more information about\nthese stylesheets, [see the Ionic Documentation for Stylesheets](https://ionicframework.com/docs/layout/global-stylesheets).\n\n- **core**\n\n Default: `true` \n Disable to import these CSS files manually:\n\n - `@ionic/vue/css/core.css`\n\n- **basic**\n\n Default: `true` \n Disable to import these CSS files manually:\n\n - `@ionic/vue/css/normalize.css`\n - `@ionic/vue/css/structure.css`\n - `@ionic/vue/css/typography.css`\n\n- **utilities**\n\n Default: `false` \n Enable to add extra Ionic CSS utilities:\n\n - `@ionic/vue/css/padding.css`\n - `@ionic/vue/css/float-elements.css`\n - `@ionic/vue/css/text-alignment.css`\n - `@ionic/vue/css/text-transformation.css`\n - `@ionic/vue/css/flex-utils.css`\n - `@ionic/vue/css/display.css`\n\n#### `config`\n\nConfigure Ionic components globally across your app, such as app mode, tab button layout, etc. For example:\n\n```js [nuxt.config.ts]\nexport default defineNuxtConfig({\n ionic: {\n config: {\n rippleEffect: false,\n mode: 'md',\n // ...\n },\n },\n})\n```\n\n::callout{color=\"info\" icon=\"i-lucide-info\"}\nPlease see the [Ionic Config Options](https://ionicframework.com/docs/vue/config#config-options) for available keys, values\nand examples of how they work.\n::\n\n### Capacitor Config\n\nCapacitor is configured via the `capacitor.config.ts` file - this is only required if you are targeting native devices such as iOS or Android.\n\n::callout{color=\"info\" icon=\"i-lucide-info\"}\nPlease see the [Capacitor Config docs](https://capacitorjs.com/docs/config) for more information.\n::\n"
},
{
"path": "docs/content/1.get-started/4.enabling-capacitor.md",
"content": "---\ntitle: Enabling Capacitor\ndescription: \"\"\nnavigation.icon: nonicons:capacitor-16\n---\n\n[Capacitor](https://capacitorjs.com/) is a powerful tool for shipping to native platforms like iOS and Android, separate from or alongside your web app.\n\nThe 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.\n\n> 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`.\n\n::code-group\n\n```bash [npx]\nnpx @ionic/cli integrations enable capacitor\nnpx @ionic/cli capacitor add ios\nnpx @ionic/cli capacitor add android\n```\n\n```bash [npm]\n# ionic config set -g npmClient npm\n\nionic integrations enable capacitor\nionic capacitor add ios\nionic capacitor add android\n```\n\n```bash [yarn]\nionic config set -g npmClient yarn\n\nionic integrations enable capacitor\nionic capacitor add ios\nionic capacitor add android\n```\n\n```bash [pnpm]\nionic config set -g npmClient pnpm\n\nionic integrations enable capacitor\nionic capacitor add ios\nionic capacitor add android\n```\n\n::\n\n::callout{color=\"info\" icon=\"i-lucide-info\"}\nRead more about [creating for iOS and Android here](/cookbook/creating-ios-android-apps).\n::\n\n#### Run on iOS or Android\n\nOnce an Android or iOS project is added with Capacitor, you can run your app on an iOS or Android emulator.\n\n::callout\nAndroid 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) for details.\n::\n\nTo build, sync, and run your app:\n\n1. Create a web build with `npx nuxt generate` or `npx nuxt build`.\n2. Run `npx cap sync` to update your Capacitor project directories with your latest app build.\n3. Run `npx cap run android` or `npx cap run ios` to run the app from the command line using an installed device **OR**\n4. _(Optional)_ Run `npx cap open android` or `npx cap open ios` to open the project in Android Studio or XCode, respectively.\n\n> Remember to run `npx cap sync` after every new build to ensure your Android and/or iOS project is up-to-date.\n\n::callout{color=\"info\" icon=\"i-lucide-info\"}\nRead more about [local development for iOS and Android here](/cookbook/local-development).\n::\n"
},
{
"path": "docs/content/1.get-started/5.watch-outs.md",
"content": "---\ntitle: Watchouts\ndescription: \"\"\nnavigation.icon: uil:exclamation-triangle\n---\n\nThis 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.\n\n## Pages and Navigation\n\n::list{type=\"warning\"}\n- Avoid using ``, `` or ``. These are currently not integrated with this module.\n::\n\nInstead, Ionic expects `` to show the route component, and `useIonRouter()` or the `router-link` property on any `ion-` component to change page.\n\n```vue [app.vue]\n\n \n \n \n\n```\n\n::list{type=\"warning\"}\n- The root element of every page must always be ``. \n::\n\nThis 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.\n\n::list{type=\"warning\"}\n- When navigating from a tabbed route to a non-tabbed route, `route.params` from the auto-imported `useRoute()` will always be an empty object.\n::\n\nA current workaround is to `import { useRoute } from 'vue-router';`.\n\n::callout{color=\"info\" icon=\"i-lucide-info\"}\nRead more [about routing here](/overview/routing).\n::\n\n## Lifecycle Hooks\n\nIonic handles lifecycle events slightly differently to Vue, as it persists some components in the DOM when Vue would usually unmount them.\n\nThis means the various mounted hooks, e.g. `onBeforeMount`, may not be called when you would expect them to.\n\nTo help with this, Ionic has added extra lifecycle hooks which behave how you may have expected the mounted hooks to behave.\n\n::callout{color=\"info\" icon=\"i-lucide-info\"}\nRead about the [Ionic Vue lifecycle hooks here](https://ionicframework.com/docs/vue/lifecycle).\n::\n\nBecause of this, some expected functionality from Nuxt or other modules may not work or may require changes to get functioning:\n\n::list{type=\"warning\"}\n- **The composable `useHead()` will not work out of the box**. \n See [our cookbook page](/cookbook/page-metadata) for how to continue using `useHead()`\n- **Certain Vue Router components should not be used**. \n This includes ``, ``, and `` - [read more here](https://ionicframework.com/docs/vue/lifecycle#how-ionic-framework-handles-the-life-of-a-page).\n::\n\n## No serverside rendering\n\n::list{type=\"warning\"}\n- The application code cannot contain any serverside rendering.\n::\n\nWhen 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](/cookbook/web-and-device).\n\n::callout{color=\"info\" icon=\"i-lucide-info\"}\nLearn more about [building for native devices here](/cookbook/creating-ios-android-apps).\n::\n"
},
{
"path": "docs/content/2.overview/.navigation.yml",
"content": "icon: heroicons-outline:sparkles\nnavigation.redirect: /overview/routing\n"
},
{
"path": "docs/content/2.overview/1.routing.md",
"content": "---\ntitle: Routing\ndescription: Routing within your Nuxt Ionic application will feel very similar, but with a couple of differences.\nnavigation.icon: uil:sign-alt\n---\n\nBy 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.\n\n::list{type=\"success\"}\n- Enables [non-linear routing](https://ionicframework.com/docs/vue/navigation#non-linear-routing), e.g. for application tabs\n- Separate navigation stacks for each tab of your application\n- Rich page transitions out-of-the-box, appropriate for mobile\n- Simple API for custom animations and direction control when navigating via links \n::\n\n## Pages\n\nJust 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) here.\n\n::list{type=\"warning\"}\n- The root component of every page must always be the `` component.\n::\n\nThis 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.\n\n```vue [~/pages/home.vue]\n\n \n \n \n Home\n \n \n Hello World\n \n\n```\n\n::callout{color=\"info\" icon=\"i-lucide-info\"}\nRead more about [`` here](https://ionicframework.com/docs/vue/navigation#ionpage).\n::\n\n### Defining page meta\n\nNuxt utilities like `definePageMeta` are fully functional. However, you should avoid using `` or `` as these will not function correctly, due to Ionic requiring an `` instead.\n\n::callout{color=\"info\" icon=\"i-lucide-info\"}\nRead more about [`definePageMeta` here](https://nuxt.com/docs/api/utils/define-page-meta).\n::\n\n### Define a root alias if there's no index.vue page\n\nUsually 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.\n\nTo 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:\n\n```ts [pages/tabs.vue]\ndefinePageMeta({\n alias: ['/'],\n})\n```\n\nIt will now be used as the root path, and will be routed to by default when visiting e.g. localhost:3000.\n\n\n## Navigation\n\nNavigation can be done in several ways, using the `IonRouter` or certain `ion-` components.\n\n::callout{color=\"info\" icon=\"i-lucide-info\"}\nRead about navigation in [Ionic's Vue Navigation docs](https://ionicframework.com/docs/vue/navigation).\n::\n\n### IonRouter\n\nTo 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.\n\nThis module auto-imports `useIonRouter()` so it should be available automatically. If this is disabled, you can import it from `@ionic/vue`.\n\nIt is best used when you wish to control navigation programmatically and have full control over the page transitions.\n\n```vue\n\n```\n\n::callout{color=\"info\" icon=\"i-lucide-info\"}\nRead more about [`useIonRouter() here`](https://ionicframework.com/docs/vue/navigation#navigating-using-useionrouter).\n::\n\n### Navigating with Components\n\nAll 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.\n\n`router-direction` and `router-animation` are also available for further control.\n\nIt's best used when simple routing is required, without any programmatic logic before or after.\n\n```vue\n\n Click Me\n \n Click Me\n \n\n```\n\n\n::callout{color=\"info\" icon=\"i-lucide-info\"}\nRead about [using the `router-link` attribute here](https://ionicframework.com/docs/vue/navigation#navigating-using-router-link).\n::\n\n::callout{color=\"warning\" icon=\"i-lucide-alert-triangle\"}\nAvoid using `` for now as it currently is not integrated with the Ionic Router.\n::\n\n## Route Parameters\n\nWhen accessing route parameters, `useRoute()` should continue to be used, just like regular Nuxt.\n\n```vue [pages/posts/[id}.vue]\n\n```\n\n::callout{color=\"info\" icon=\"i-lucide-info\"}\nRead more about [Nuxt route parmeters here](https://nuxt.com/docs/getting-started/routing#route-parameters). \n::\n\n## Route Middleware\n\nNuxt's Route Middleware is also integrated and available, just like regular Nuxt.\n\n::code-group\n\n```ts [middleware/auth.ts]\nexport default defineNuxtRouteMiddleware((to, from) => {\n // isAuthenticated() is an example method verifying if a user is authenticated\n if (isAuthenticated() === false) {\n return showLoginModal(); // showLoginModal() is an example of opening a modal flow for authentication\n }\n})\n```\n\n```html [pages/tabs/feed.vue]\n\n\n\n
Welcome to your feed
\n\n```\n\n::\n\n::callout{color=\"info\" icon=\"i-lucide-info\"}\nRead more about [Nuxt route middleware here](https://nuxt.com/docs/getting-started/routing#route-middleware).\n::\n"
},
{
"path": "docs/content/2.overview/2.theming.md",
"content": "---\ntitle: Theming\ndescription: \"\"\nnavigation.icon: uil:palette\n---\n\nIonic provides many css variables with which their components derive css styles. These variables can be overridden to customise the theme of your app. \n\nIn 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:\n\n::code-group\n\n```css [assets/css/ionic.css]\n:root {\n --ion-color-primary: #57e389;\n --ion-color-primary-rgb: 87, 227, 137;\n --ion-color-primary-contrast: #000000;\n --ion-color-primary-contrast-rgb: 0, 0, 0;\n --ion-color-primary-shade: #4dc879;\n --ion-color-primary-tint: #68e695;\n\n /* And so on... */\n}\n```\n\n```ts [nuxt.config.ts]\nexport default defineNuxtConfig({\n css: ['~/assets/css/ionic.css'],\n})\n```\n\n::\n\nTo learn more about theming and which variables to override, check out Ionic's [official theming documentation](https://ionicframework.com/docs/theming/basics).\n"
},
{
"path": "docs/content/2.overview/3.ionic-auto-imports.md",
"content": "---\ntitle: Ionic Auto-Imports\nnavigation.icon: uil:channel\ndescription:\n---\n\nIonic provides various components and helper functions for use in your application.\n\nThis module automatically auto-imports them throughout your app, so you do not need to import them manually.\n\n::callout{color=\"info\" icon=\"i-lucide-info\"}\nRead more about [how component auto-imports work](https://v3.nuxtjs.org/guide/directory-structure/components#components-directory).\n::\n\n## Ionic Components\n\nAll 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.\n\nFor a list of all Ionic Vue components, please refer to the ionic component documentation: https://ionicframework.com/docs/components\n\n::callout{color=\"info\" icon=\"i-lucide-info\"}\nIf you find a component that isn't being auto-imported, please [open an issue](https://github.com/nuxt-modules/ionic/issues/new/choose) or [a pull request](https://github.com/nuxt-modules/ionic/compare).\n::\n\n## Ionic Helper Functions\n\nA number of Ionic hooks/composables are also imported by Nuxt via auto-imports within your app:\n\n- [`getPlatforms`](https://ionicframework.com/docs/vue/platform#getplatforms)\n- [`isPlatform`](https://ionicframework.com/docs/vue/platform#isplatform)\n- [`menuController`](https://ionicframework.com/docs/api/menu)\n- [`onIonViewWillEnter`](https://ionicframework.com/docs/vue/lifecycle#ionic-framework-lifecycle-methods)\n- [`onIonViewDidEnter`](https://ionicframework.com/docs/vue/lifecycle#ionic-framework-lifecycle-methods)\n- [`onIonViewWillLeave`](https://ionicframework.com/docs/vue/lifecycle#ionic-framework-lifecycle-methods)\n- [`onIonViewDidLeave`](https://ionicframework.com/docs/vue/lifecycle#ionic-framework-lifecycle-methods)\n- [`useBackButton`](https://ionicframework.com/docs/vue/utility-functions#hardware-back-button)\n- [`useKeyboard`](https://ionicframework.com/docs/vue/utility-functions#keyboard)\n- [`useIonRouter`](https://ionicframework.com/docs/vue/utility-functions#router)\n- [`createAnimation`](https://ionicframework.com/docs/utilities/animations)\n- [`createGesture`](https://ionicframework.com/docs/utilities/gestures)\n- [`getTimeGivenProgression`](https://github.com/ionic-team/ionic-framework/blob/main/core/src/utils/animation/cubic-bezier.ts#L20)\n- [`iosTransitionAnimation`](https://github.com/ionic-team/ionic-framework/blob/main/core/src/utils/transition/ios.transition.ts#L267)\n- [`mdTransitionAnimation`](https://github.com/ionic-team/ionic-framework/blob/main/core/src/utils/transition/md.transition.ts#L6)\n\n::callout{color=\"info\" icon=\"i-lucide-info\"}\nRead more about these [helper functions in Ionic's docs](https://ionicframework.com/docs/).\n::\n\n"
},
{
"path": "docs/content/2.overview/4.module-utilities.md",
"content": "---\ntitle: Module Utilities\nnavigation.icon: uil:layer-group\ndescription:\n---\n\nThis 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.\n\n## Components\n\n### `IonAnimation` component\n\nThis component makes using Ionic's `createAnimation` easier. It matches the majority of props directly to the usual Ionic animation object, to make adoption easier.\n\nFor more information, see [official Ionic docs](https://ionicframework.com/docs/utilities/animations) or check out the [playground examples](https://github.com/nuxt-modules/ionic/blob/main/playground/pages/tabs/tab4.vue)\n\nYou can see how it replaces usage of the regular [`createAnimation`](https://ionicframework.com/docs/utilities/animations#installation) function in the code example below:\n\n::code-group\n\n```vue [IonAnimation]\n\n \n \n \n\n```\n\n```vue [Manual usage]\n\n```\n\n::\n\n::callout{color=\"info\" icon=\"i-lucide-info\"}\nCurrently component doesn't support grouped and chained animations. For that usage we still recommend using `createAnimation` by itself\n::\n"
},
{
"path": "docs/content/2.overview/5.icons.md",
"content": "---\nnavigation.icon: uil:illustration\ndescription: \"\"\n---\n\nIcons are auto-imported from [`ionicons/icons`](https://github.com/ionic-team/ionicons) 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).\n\n::code-group\n\n```vue [Auto-imported icons]\n\n \n \n\n```\n\n```vue [Manual imports]\n\n\n\n \n \n\n```\n\n::\n\nYou can opt-out of auto-importing icons by setting the `integrations.icons` module options in your `nuxt.config.ts` to `false`.\n\n```js\nexport default defineNuxtConfig({\n ionic: {\n integrations: {\n icons: false,\n },\n },\n})\n```\n"
},
{
"path": "docs/content/2.overview/6.deployment.md",
"content": "---\nnavigation.icon: uil:rocket\n---\n\n## Web\n\nDeployment on the web is the same as any Nuxt project. You can find more information for this in Nuxt's deployment documentation.\n\n::callout{color=\"info\" icon=\"i-lucide-info\"}\nRead more about [deploying to the web](https://nuxt.com/docs/getting-started/deployment).\n::\n\n\n## iOS and Android\n\nFor iOS and Android, it's a little more involved. We recommend looking at the deployment documentation from Ionic for these platforms: \n\n### iOS\n\nhttps://ionicframework.com/docs/deployment/app-store\n\n### Android\n\nhttps://ionicframework.com/docs/deployment/play-store\n"
},
{
"path": "docs/content/3.cookbook/.navigation.yml",
"content": "icon: heroicons-outline:bookmark-alt\nnavigation.redirect: /cookbook/customising-app-vue\n"
},
{
"path": "docs/content/3.cookbook/1.customising-app-vue.md",
"content": "---\ntitle: Customising app.vue\ndescription: \"\"\n---\n\nThis module provides a default `app.vue` file for when one is not otherwise provided by your app.\n\nIf you need to customize this `app.vue` file, you can create a new one in your project's source directory, based off the default:\n\n```vue [app.vue]\n\n \n \n \n\n```\n\nThis module will then stop providing one, so that your project's `app.vue` is used instead.\n\n## Necessary ion tags\n\nIt's necessary that `` and `` are provided in your `app.vue` for Ionic to function.\n\n`` 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) for more info.\n\nEqually, `` provides a mounting point for the route component. In regular Nuxt applications,\nthis would be ``, but as Ionic Router is handling our routing we must use the ``.\n\n::callout{color=\"warning\" icon=\"i-lucide-alert-triangle\"}\nRemember 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).\n::\n"
},
{
"path": "docs/content/3.cookbook/2.local-development.md",
"content": "---\ndescription: \"\"\n---\n\n::callout{color=\"info\" icon=\"i-lucide-info\"}\nYou may find the Ionic docs on developing [for iOS](https://ionicframework.com/docs/developing/ios) and [for Android](https://ionicframework.com/docs/developing/android) helpful before continuing.\n::\n\nWhen using Ionic just for the web, local development is as easy as running the `dev` script provided by Nuxt:\n\n::code-group\n\n```bash [yarn]\nyarn dev -o\n```\n\n```bash [npm]\nnpm run dev -- -o\n```\n\n```bash [pnpm]\npnpm dev -o\n```\n\n::\n\n\nBut 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). \n\nThis 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.\n\n## Native device or simulator\n\nFirst, ensure your Nuxt development build is created and the development server is running:\n\n::code-group\n\n```bash [yarn]\nyarn dev -o\n```\n\n```bash [npm]\nnpm run dev -- -o\n```\n\n```bash [pnpm]\npnpm dev -o\n```\n\n::\n\nThen, in a separate tab, [sync the build](https://ionicframework.com/docs/cli/commands/capacitor-sync) 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.\n\n::code-group\n\n```bash [ios]\nnpx @ionic/cli capacitor sync ios --no-build\n```\n\n```bash [android]\nnpx @ionic/cli capacitor sync android --no-build\n```\n\n::\n\nThen 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). Ensure your native device is plugged in so that it displays in your list.\n\n::code-group\n\n```bash [ios]\nnpx @ionic/cli capacitor run ios --livereload-url=http://${LIP}:3000 --external --mode development\n```\n\n```bash [android]\nnpx @ionic/cli capacitor run android --livereload-url=http://${LIP}:3000 --external --mode development\n```\n\n::\n\nThe app will then open on the chosen native device or device simulator. \n\n## Automating on-device dev\n\nWe recommend putting this into a script in `scripts/` that you can run more easily via `yarn run` or `pnpm run`. For example:\n\n::code-group\n\n```bash [scripts/android.sh]\n#!/bin/bash\nLIP=$(ipconfig getifaddr en0)\n\necho \"๐ฆ Starting local development to android device - ensure local dev server is running already\"\necho \"๐๏ธ Type checking and building for development...\"\npnpm run build:dev\necho \"๐ Capacitor installation, podfile installation, sync and copy to app distribution folders...\"\nnpx @ionic/cli capacitor sync android --no-build\necho \"๐ Select an Android device to run the build at local ip address ${LIP} on...\"\neval \"npx @ionic/cli capacitor run android --livereload-url=http://${LIP}:3000 --external --mode development\"\n```\n\n```bash [scripts/ios.sh]\n#!/bin/bash\nLIP=$(ipconfig getifaddr en0)\n\necho \"๐ฆ Starting local development to ios device - ensure local dev server is running already\"\necho \"๐๏ธ Type checking and building for development...\"\npnpm run build:dev\necho \"๐ Capacitor installation, podfile installation, sync and copy to app distribution folders...\"\nnpx @ionic/cli capacitor sync ios --no-build\necho \"๐ Select an iOS device to run the build at local ip address ${LIP} on...\"\neval \"npx @ionic/cli capacitor run ios --livereload-url=http://${LIP}:3000 --external --mode development\"\n```\n\n::\n\n```json [package.json]\n{\n \"scripts\": {\n \"android\": \"bash ./scripts/android.sh\",\n \"ios\": \"bash ./scripts/ios.sh\"\n }\n}\n```\n\n::code-group\n\n```bash [yarn]\nyarn ios\nyarn android\n```\n\n```bash [npm]\nnpm run ios\nnpm run android\n```\n\n```bash [pnpm]\npnpm run ios\npnpm run android\n```\n\n::\n\n\n::callout{color=\"warning\" icon=\"i-lucide-alert-triangle\"}\nIf you're having trouble with this step, please check the Ionic guides for [deploying to iOS](https://ionicframework.com/docs/developing/ios) and [deploying to android](https://ionicframework.com/docs/developing/android) for more information.\n::\n"
},
{
"path": "docs/content/3.cookbook/3.app-tabs.md",
"content": "---\ntitle: App Tabs\ndescription: \"\"\n---\n\nIt'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.\n\nIonic provides several components to provide App Tabs out of the box, with a deep integration with the Ionic Router for them.\n\n::callout{color=\"info\" icon=\"i-lucide-info\"}\nRead more about [Ionic's `ion-tabs` here](https://ionicframework.com/docs/api/tabs).\n::\n\n## Setup an application with tabs\n\n> See the example in [the playground](https://github.com/nuxt-modules/ionic/blob/main/playground) for a working demo of an app with tabs.\n\nTabs require a main tab component, and then child components to be rendered in the tab view.\n\nYour file structure should look like this:\n\n```text [pages/ directory]\npages/\n--| tabs.vue\n--| tabs/\n----| tab1.vue\n----| tab2.vue\n----| tab3.vue\n----| tab4.vue\n```\n\nThese tabs should then have a similar code structure as shown below. Remember, all pages must start with an `ion-page` component.\n\n::code-group\n\n```vue [pages/tabs.vue]\n\n \n \n \n \n \n \n \n \n Tab 1\n \n\n \n \n Photos\n \n\n \n \n Tab 3\n \n\n \n \n Animation examples\n \n \n \n \n \n\n```\n\n```vue [pages/tabs/tab1.vue]\n\n \n \n \n Tab 1\n \n \n \n Tab 1 content\n \n \n\n```\n\n```vue [pages/tabs/tab2.vue]\n\n \n \n \n Tab 2\n \n \n \n Tab 2 content\n \n \n\n```\n\n::\n\n\nAll 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.\n\nThe simplest way to manage this is for all pages being within this `pages/tabs/` directory, with a directory per tab, like so:\n\n```text [pages/ directory]\npages/\n--| tabs.vue\n--| tabs/\n----| tab1/\n------| index.vue\n------| a-page.vue\n----| tab2/\n------| index.vue\n----| tab3/\n------| index.vue\n----| tab4.vue\n------| index.vue\n------| another-page.vue\n```\n\nIf a particular tab only has one route component, you don't explicitly need the directory for it with the index.vue inside\nof it, but we find it's a neater approach this way.\n\nUsing 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:\n\n::list{type=\"danger\"}\n- An example of incorrect routing (do not copy):\n::\n\n```text [pages/ directory]\npages/\n--| tabs.vue\n--| tabs/\n----| tab1.vue\n----| tab1/\n------| a-page.vue\n----| tab2.vue\n----| tab3.vue\n----| tab4.vue\n----| tab4/\n------| another-page.vue\n```\n\n::callout{color=\"success\" icon=\"i-lucide-check-circle\"}\nIonic provides an article on [best practices for using tabs in your application](https://ionicframework.com/docs/vue/navigation#working-with-tabs).\n::\n\n## Routing to pages that shouldn't be displayed in the tabs\n\nIf 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\nof the tabs directory.\n\n```text [pages/ directory]\npages/\n--| tabs.vue\n--| tabs/\n----| tab1/\n------| index.vue\n------| a-page.vue\n----| tab2/\n------| index.vue\n--| settings.vue\n```\n\n::list{type=\"danger\"}\n- 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';`.\n::\n\n## Reusing views across tabs\n\nSome 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.\n\nTo 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.\n\n::code-group\n```text [pages/ directory]\npages/\n--| tabs.vue\n--| tabs/\n----| home/\n------| index.vue\n------| album-[id].vue\n----| search/\n------| index.vue\n------| album.vue\n----| library/\n------| index.vue\n```\n\n```vue [pages/home/album-{id}.vue]\n\n \n\n```\n\n```vue [pages/search/album-{id}.vue]\n\n \n\n```\n::\n\n::callout{color=\"info\" icon=\"i-lucide-info\"}\nRead more about [reusing views across tabs in the Ionic docs](https://ionicframework.com/docs/vue/navigation#switching-between-tabs).\n::\n"
},
{
"path": "docs/content/3.cookbook/4.page-metadata.md",
"content": "---\ntitle: useHead / Page Meta\ndescription: \"\"\n---\n\n::callout{color=\"warning\" icon=\"i-lucide-alert-triangle\"}\nโ ๏ธ This page is a stub and needs further information.\n::\n\nThe composable `useHead()` will not work out of the box.\n\nPlease see this issue for reference: https://github.com/nuxt-modules/ionic/issues/6\n\nAlso see the documentation for use-head: https://nuxt.com/docs/api/composables/use-head\n"
},
{
"path": "docs/content/3.cookbook/5.creating-ios-android-apps.md",
"content": "---\ntitle: iOS and Android Apps\n---\n\n\n::callout{color=\"warning\" icon=\"i-lucide-alert-triangle\"}\nโ ๏ธ This page is a stub and needs further information.\n::\n\nWhen building for iOS and Android, we recommend setting `ssr: false` in your nuxt config\n\n```js [nuxt.config.ts]\nexport default defineNuxtConfig({\n modules: ['@nuxtjs/ionic'],\n ssr: false,\n})\n```\n\nAlso see:\n\n- https://ionicframework.com/docs/developing/ios\n- https://ionicframework.com/docs/developing/android\n- https://ionicframework.com/docs/deployment/app-store\n- https://ionicframework.com/docs/deployment/play-store\n\nPlease also see our page on (building for both Web and Device together)(/cookbook/web-and-device)\n"
},
{
"path": "docs/content/3.cookbook/6.web-and-device.md",
"content": "---\ndescription: \"\"\n---\nHere 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. \n\n## Building for native devices\n\nOne main caveat of building for native devices is that the final build needs to be able to run completely\nclientside. Another is that deploying a new build requires submitting to the app stores and being manually reviewed and approved.\n\nThis makes building for devices more cumbersome than deploying to the web, and means the following must be followed when deploying:\n\n::list{type=danger}\n- **No serverside rendering in the codebase** \n As the build must be able to run completely clientside, we cannot have serverside rendering in the codebase.\n\n- **Generating new builds are not quickly deployed** \n 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.\n\n As deploying to the app stores is much slower than to the web, this approach likely will not work anymore.\n::\n\nThis means, in the codebase that will be deployed to the devices, we recommend using `ssr: false`, and not using serverside rendering at all.\n\nIf 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.\n\n## Further Solutions\n\nHaving two completely separate codebases to target web and device is a little cumbersome, so there are some potential solutions you could explore.\n\nThese 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.\n\n### A single codebase\n\nIt 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`.\n\nYou may need further wrapping around other SSR-aware code and utilities, such as `useAsyncData()`.\n\n### A monorepo\n\nYou 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`.\n\nA possible directory structure for this may look like:\n\n```\n- apps\n - nuxt-web\n - ...\n - nuxt.config.ts\n - nuxt-device\n - ...\n - nuxt.config.ts\n- packages\n - core\n - components\n - composables\n - ...\n```\n\n\n"
},
{
"path": "docs/content/3.cookbook/7.live-updates.md",
"content": "---\ntitle: Live Updates\ndescription: \"\"\n---\n\nLive 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. \n\nThere are several providers that offer live update services, including:\n- [Capawesome Cloud](https://cloud.capawesome.io/)\n- [CodePush (standalone)](https://github.com/microsoft/code-push-server)\n\n## Capawesome Cloud\n\nThis guide demonstrates how to implement live updates using Capawesome Cloud.\n\n### Installation\n\nTo enable Live Updates with Capawesome Cloud, you need to install the `@capawesome/capacitor-live-update` plugin:\n\n```bash\nnpm install --save @capawesome/capacitor-live-update\n```\n\nAfter that, you need to sync the changes with your native projects:\n\n```bash\nnpx cap sync\n```\n\n### Configuration\n\nNext, you need to configure the plugin to work with [Capawesome Cloud](https://cloud.capawesome.io/).\n\n#### App ID\n\nIn 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/) and get the App ID.\n\n```json\n{\n \"plugins\": {\n \"LiveUpdate\": {\n \"appId\": \"00000000-0000-0000-0000-000000000000\"\n }\n }\n}\n```\n\nReplace `00000000-0000-0000-0000-000000000000` with your actual App ID from the Capawesome Cloud Console.\n\nAfter configuring the App ID, sync your Capacitor project again:\n\n```bash\nnpx cap sync\n```\n\n### Usage\n\nThe most basic usage of the Live Update plugin is to call the [`sync(...)`](https://capawesome.io/plugins/live-update/#sync) 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) method to apply the update immediately. If the [`reload()`](https://capawesome.io/plugins/live-update/#reload) method is not called, the new bundle will be used on the next app start.\n\n```js\nimport { LiveUpdate } from \"@capawesome/capacitor-live-update\"\n\nconst sync = async () => {\n const result = await LiveUpdate.sync()\n if (result.nextBundleId) {\n await LiveUpdate.reload()\n }\n}\n```\n\n### Publishing updates\n\nTo publish your first update, you need to [create a bundle](https://capawesome.io/cloud/live-updates/bundles/#create-a-bundle) 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:\n\n#### Building your app\n\nGenerate the production build of your Nuxt app:\n\n```bash\nnpx nuxt generate\n```\n\nThis creates a `dist` folder with the build output of your web app.\n\n#### Publishing with Capawesome CLI\n\nTo install the Capawesome CLI,run the following command:\n\n```bash\nnpm i -g @capawesome/cli\n```\n\nAfter installing the Capawesome CLI, you need to log in to your Capawesome Cloud account. Run the following command and follow the instructions:\n\n```bash\nnpx capawesome login\n```\n\nOnce you are logged in, you can create a bundle by running the following command:\n\n```bash\nnpx capawesome apps:bundles:create --path dist\n```\n\nCongratulations! 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.\nFeel free to check out the [documentation](https://capawesome.io/plugins/live-update/) of the Live Update plugin to see what else you can do with it.\n\n## Other providers\n\nFor other live update providers, consult their respective documentation for the specific upload process and tooling requirements.\n\n::callout{color=\"info\" icon=\"i-lucide-info\"}\nWe'd welcome PRs to add examples for other providers.\n::\n\n"
},
{
"path": "docs/content/index.md",
"content": "---\ntitle: 'Get Started'\nnavigation: false\nlayout: page\n---\n\n::u-page-hero{orientation=\"horizontal\"}\n#title\nNuxt [Ionic]{style=\"color:var(--color-primary-500);\"}\n\n#description\nBatteries-included [Ionic](https://ionicframework.com/) integration for Nuxt.\n\n- Zero-config required\n- Auto-import Ionic components, composables and icons\n- Ionic Router integration\n- Pre-render routes\n- Mobile meta tags\n- Works out of the box with [Capacitor](https://capacitorjs.com/) to build mobile apps\n\n#links\n :::u-button\n ---\n size: xl\n to: /get-started/introduction\n trailing-icon: i-lucide-arrow-right\n ---\n Get started\n :::\n\n :::u-button\n ---\n color: neutral\n icon: simple-icons-github\n size: xl\n to: https://github.com/nuxt-modules/ionic\n variant: outline\n ---\n Star on GitHub\n :::\n\n#default\n```bash [Terminal]\nnpx nuxi@latest module add ionic\n```\n\n::\n\n"
},
{
"path": "docs/nuxt.config.ts",
"content": "export default defineNuxtConfig({\n extends: ['docus'],\n modules: ['@nuxtjs/plausible'],\n css: ['~/assets/css/main.css'],\n site: {\n name: 'Nuxt Ionic',\n },\n colorMode: {\n preference: 'dark',\n },\n routeRules: {\n '/overview': { redirect: '/overview/routing' },\n '/cookbook': { redirect: '/cookbook/customising-app-vue' },\n },\n plausible: {\n domain: 'ionic.nuxtjs.org',\n apiHost: 'https://v.roe.dev',\n },\n})\n"
},
{
"path": "docs/package.json",
"content": "{\n \"name\": \"nuxt-ionic-docs\",\n \"description\": \"Batteries-included Ionic integration for Nuxt.\",\n \"homepage\": \"https://github.com/nuxt-modules/ionic/\",\n \"scripts\": {\n \"dev\": \"nuxt dev\",\n \"build\": \"nuxt build\",\n \"generate\": \"nuxt generate\",\n \"preview\": \"nuxt preview\"\n },\n \"dependencies\": {\n \"@nuxt/content\": \"3.12.0\",\n \"@nuxt/ui\": \"4.6.0\",\n \"@nuxtjs/plausible\": \"3.0.2\",\n \"better-sqlite3\": \"12.8.0\",\n \"docus\": \"5.8.1\",\n \"nuxt\": \"4.3.1\",\n \"tailwindcss\": \"4.2.2\"\n }\n}\n"
},
{
"path": "docs/tokens.config.ts",
"content": "import { defineTheme } from 'pinceau'\n\nexport default defineTheme({\n color: {\n primary: {\n 50: '#84c3ff',\n 100: '#7ab9ff',\n 200: '#70afff',\n 300: '#66a5ff',\n 400: '#5c9bff',\n 500: '#5291ff',\n 600: '#4887f5',\n 700: '#3e7deb',\n 800: '#3473e1',\n 900: '#2a69d7',\n },\n },\n})\n"
},
{
"path": "docs/tsconfig.json",
"content": "{\n \"extends\": \"./.nuxt/tsconfig.json\"\n}\n"
},
{
"path": "eslint.config.js",
"content": "// @ts-check\nimport { createConfigForNuxt } from '@nuxt/eslint-config/flat'\n\nexport default createConfigForNuxt({\n features: {\n tooling: true,\n stylistic: true,\n },\n dirs: {\n src: [\n './playground',\n './docs',\n ],\n },\n}).append(\n {\n files: ['test/**'],\n rules: {\n '@typescript-eslint/no-explicit-any': 'off',\n },\n },\n {\n files: ['docs/**'],\n rules: {\n 'vue/multi-word-component-names': 'off',\n },\n },\n {\n files: ['playground/**'],\n rules: {\n 'vue/no-deprecated-slot-attribute': 'off',\n },\n },\n)\n"
},
{
"path": "package.json",
"content": "{\n \"name\": \"@nuxtjs/ionic\",\n \"version\": \"1.0.2\",\n \"license\": \"MIT\",\n \"repository\": {\n \"type\": \"git\",\n \"url\": \"git+https://github.com/nuxt-modules/ionic.git\"\n },\n \"description\": \"Ionic integration for Nuxt\",\n \"keywords\": [\n \"nuxt\",\n \"module\",\n \"nuxt-module\",\n \"ionic\",\n \"ionic-framework\",\n \"web-components\",\n \"native\",\n \"android\",\n \"ios\"\n ],\n \"author\": {\n \"name\": \"Daniel Roe\",\n \"email\": \"daniel@roe.dev\",\n \"url\": \"https://github.com/danielroe\"\n },\n \"type\": \"module\",\n \"exports\": {\n \".\": {\n \"types\": \"./dist/types.d.mts\",\n \"import\": \"./dist/module.mjs\"\n }\n },\n \"main\": \"./dist/module.mjs\",\n \"typesVersions\": {\n \"*\": {\n \".\": [\n \"./dist/types.d.mts\"\n ]\n }\n },\n \"files\": [\n \"dist\"\n ],\n \"scripts\": {\n \"build\": \"pnpm dev:prepare && nuxt-module-build build\",\n \"dev\": \"nuxt dev playground\",\n \"dev:build\": \"nuxt build playground\",\n \"dev:prepare\": \"pnpm nuxt-module-build build --stub && nuxt-module-build prepare && nuxt prepare playground\",\n \"docs:dev\": \"pnpm --filter 'nuxt-ionic-docs' dev\",\n \"docs:build\": \"pnpm --filter 'nuxt-ionic-docs' generate\",\n \"lint\": \"eslint\",\n \"prepack\": \"pnpm build\",\n \"prepare\": \"simple-git-hooks\",\n \"prepublishOnly\": \"pnpm lint && pnpm test\",\n \"release\": \"bumpp && npm publish && git push --follow-tags\",\n \"test\": \"vitest run --coverage\",\n \"test:types\": \"tsc --noEmit\"\n },\n \"dependencies\": {\n \"@capacitor/cli\": \"^8.0.0\",\n \"@capacitor/core\": \"^8.0.0\",\n \"@ionic/cli\": \"^7.2.1\",\n \"@ionic/vue\": \"^8.7.3\",\n \"@ionic/vue-router\": \"^8.7.3\",\n \"@nuxt/kit\": \"^4.1.2\",\n \"@unhead/vue\": \"^2.0.14\",\n \"ionicons\": \"^8.0.13\",\n \"jiti\": \"^2.6.0\",\n \"pathe\": \"^2.0.3\",\n \"pkg-types\": \"^2.3.0\",\n \"std-env\": \"^4.0.0\",\n \"ufo\": \"^1.6.1\",\n \"unimport\": \"^6.0.0\"\n },\n \"devDependencies\": {\n \"@ionic/core\": \"8.8.2\",\n \"@nuxt/eslint-config\": \"1.15.2\",\n \"@nuxt/module-builder\": \"1.0.2\",\n \"@nuxt/schema\": \"4.3.1\",\n \"@nuxt/test-utils\": \"4.0.0\",\n \"@types/node\": \"24.12.0\",\n \"@vitest/coverage-v8\": \"4.1.5\",\n \"@vue/test-utils\": \"2.4.6\",\n \"bumpp\": \"11.0.1\",\n \"eslint\": \"10.2.1\",\n \"expect-type\": \"1.3.0\",\n \"happy-dom\": \"20.9.0\",\n \"husky\": \"9.1.7\",\n \"lint-staged\": \"16.4.0\",\n \"nuxt\": \"4.3.1\",\n \"playwright-core\": \"1.58.2\",\n \"simple-git-hooks\": \"2.13.1\",\n \"typescript\": \"6.0.2\",\n \"unbuild\": \"3.6.1\",\n \"unhead\": \"2.1.13\",\n \"vitest\": \"4.1.5\",\n \"vue\": \"3.5.30\",\n \"vue-tsc\": \"3.2.6\"\n },\n \"lint-staged\": {\n \"*.{md,js,ts,mjs,cjs,json,.*rc}\": [\n \"npx eslint --fix\"\n ]\n },\n \"simple-git-hooks\": {\n \"pre-commit\": \"npx lint-staged\"\n },\n \"resolutions\": {\n \"@nuxt/kit\": \"^4.1.2\",\n \"@nuxt/schema\": \"4.3.1\",\n \"@nuxtjs/ionic\": \"link:.\",\n \"consola\": \"^3.4.2\",\n \"nuxt-component-meta\": \">=0.14.0\"\n },\n \"packageManager\": \"pnpm@10.33.0\"\n}\n"
},
{
"path": "playground/assets/css/ionic.css",
"content": ":root {\n --ion-color-primary: #6030ff;\n --ion-color-primary-rgb: 96, 48, 255;\n --ion-color-primary-contrast: #ffffff;\n --ion-color-primary-contrast-rgb: 255, 255, 255;\n --ion-color-primary-shade: #542ae0;\n --ion-color-primary-tint: #7045ff;\n}\n"
},
{
"path": "playground/capacitor.config.ts",
"content": "import type { CapacitorConfig } from '@capacitor/cli'\n\nconst config: CapacitorConfig = {\n appId: 'io.ionic.starter',\n appName: 'nuxt-ionic-playground',\n webDir: 'dist',\n}\n\nexport default config\n"
},
{
"path": "playground/components/ExploreContainer.vue",
"content": "\n\n\n