diff --git a/docs/angular/overview.md b/docs/angular/overview.md index 4b1182bb76a..ac884c576da 100644 --- a/docs/angular/overview.md +++ b/docs/angular/overview.md @@ -14,33 +14,58 @@ sidebar_label: Overview import DocsCard from '@components/global/DocsCard'; import DocsCards from '@components/global/DocsCards'; -`@ionic/angular` combines the core Ionic experience with the tooling and APIs that are tailored to Angular Developers. +`@ionic/angular` brings the full power of the Ionic Framework to Angular developers. It offers seamless integration with the Angular ecosystem, so you can build high-quality cross-platform apps using familiar Angular tools, components, and best practices. You also get access to Ionic's extensive UI library and native capabilities. ## Angular Version Support -Ionic v7 supports Angular v14+. As part of their upgrade strategy, Angular has built-in tooling to help automate upgrades and provide feedback to developers whenever changes to an API occurred. This reduces update friction and keeps the ecosystem in a evergreen state. +Ionic Angular v8 supports Angular versions 16 and above. For detailed information on supported versions and our support policy, see the [Ionic Angular Support Policy](/docs/reference/support#ionic-angular). ## Angular Tooling -With Ionic 4+, the official Angular stack for building an app and routing are used, so your app can fall in-line with the rest of the great Angular ecosystem. In cases where more opinionated features are needed, Ionic provides `@ionic/angular-toolkit`, which builds and integrates with the [official Angular CLI](https://angular.io/cli) and provides features that are specific to `@ionic/angular` apps. +Ionic uses the official Angular stack for building apps and routing, so your app can fall in line with the rest of the Angular ecosystem. In cases where more opinionated features are needed, Ionic provides `@ionic/angular-toolkit`, which builds and integrates with the [official Angular CLI](https://angular.io/cli) and provides features that are specific to `@ionic/angular` apps. + +## Native Tooling + +[Capacitor](https://capacitorjs.com) is the official cross-platform runtime for Ionic Angular, enabling your apps to run natively on iOS, Android, and the web with a single codebase. + +## Installation + +Before you begin, make sure you have [Node.js](https://nodejs.org/) (which includes npm) installed on your machine. + +```shell-session +$ npm install -g @ionic/cli +$ ionic start myApp tabs --type angular + +$ cd myApp +$ ionic serve █ +``` ## Resources - -

Learn the fundamentals you need to know to start building amazing apps with Ionic Framework.

- - -

Learn the basics of navigation inside your app with Ionic and Angular Router

+ +

Quickly set up your first Ionic Angular app and learn the basics of the framework and CLI.

+ + + +

Learn more about Angular's core concepts, tools, and best practices from the official Angular documentation.

+ + + +

Discover how to handle routing and navigation in Ionic Angular apps using the Angular Router.

+ + + +

Explore Ionic's rich library of UI components for building beautiful apps.

 - -

Learn about using Ionic lifecycle events in class components and with hooks

+ +

Learn how to customize the look and feel of your app with Ionic's powerful theming system.

 - -

Learn about using Modules or Standalone Components in Ionic.

+ +

Explore how to access native device features and deploy your app to iOS, Android, and the web with Capacitor.

 diff --git a/docs/angular/quickstart.md b/docs/angular/quickstart.md new file mode 100644 index 00000000000..fa4505c70d3 --- /dev/null +++ b/docs/angular/quickstart.md @@ -0,0 +1,439 @@ +--- +title: Ionic Angular Quickstart +sidebar_label: Quickstart +--- + + + Ionic Angular Quickstart Using Ionic CLI: Angular Basics + + + +import DocsCard from '@components/global/DocsCard'; +import DocsCards from '@components/global/DocsCards'; + +Welcome! This guide will walk you through the basics of Ionic Angular development. You'll learn how to set up your development environment, generate a simple project, explore the project structure, and understand how Ionic components work. This is perfect for getting familiar with Ionic Angular before building your first real app. + +If you're looking for a high-level overview of what Ionic Angular is and how it fits into the Angular ecosystem, see the [Ionic Angular Overview](overview). + +## Prerequisites + +Before you begin, make sure you have Node.js and npm installed on your machine. +You can check by running: + +```shell +node -v +npm -v +``` + +If you don't have Node.js and npm, [download Node.js here](https://nodejs.org/en/download) (which includes npm). + +## Create a Project with the Ionic CLI + +First, install the latest [Ionic CLI](../cli): + +```shell +npm install -g @ionic/cli +``` + +Then, run the following commands to create and run a new project: + +```shell +ionic start myApp blank --type angular + +cd myApp +ionic serve +``` + +At the first prompt, choose `Standalone`. + +After running `ionic serve`, your project will open in the browser. + +![Screenshot of the Ionic Angular Home page](/img/guides/quickstart/home-page.png 'Ionic Angular Home Component') + +## Explore the Project Structure + +Your new app's `src/app` directory will look like this: + +```shell +├── app.component.html +├── app.component.scss +├── app.component.ts +├── app.routes.ts +└── home/ + ├── home.page.html + ├── home.page.scss + ├── home.page.spec.ts + └── home.page.ts +``` + +:::info +All file paths in the examples below are relative to the `src/app/` directory. +::: + +Let's walk through these files to understand the app's structure. + +## View the App Component + +The root of your app is defined in `app.component.ts`: + +```ts +import { Component } from '@angular/core'; +import { IonApp, IonRouterOutlet } from '@ionic/angular/standalone'; + +@Component({ + selector: 'app-root', + templateUrl: 'app.component.html', + imports: [IonApp, IonRouterOutlet], +}) +export class AppComponent { + constructor() {} +} +``` + +And its template in `app.component.html`: + +```html + + + +``` + +This sets up the root of your application, using Ionic's `ion-app` and `ion-router-outlet` components. The router outlet is where your pages will be displayed. + +## View Routes + +Routes are defined in `app.routes.ts`: + +```ts +import { Routes } from '@angular/router'; + +export const routes: Routes = [ + { + path: 'home', + loadComponent: () => import('./home/home.page').then((m) => m.HomePage), + }, + { + path: '', + redirectTo: 'home', + pathMatch: 'full', + }, +]; +``` + +When you visit the root URL (`/`), the `HomePage` component will be loaded. + +## View the Home Page + +The Home page component, defined in `home/home.page.ts`, imports the Ionic components it uses: + +```ts +import { Component } from '@angular/core'; +import { IonHeader, IonToolbar, IonTitle, IonContent } from '@ionic/angular/standalone'; + +@Component({ + selector: 'app-home', + templateUrl: 'home.page.html', + styleUrls: ['home.page.scss'], + imports: [IonHeader, IonToolbar, IonTitle, IonContent], +}) +export class HomePage { + constructor() {} +} +``` + +And the template, in the `home.page.html` file, uses those components: + +```html + + + Blank + + + + + + + Blank + + + +
+ Ready to create an app? +

+ Start with Ionic + UI Components +

+
+ +``` + +This creates a page with a header and scrollable content area. The second header shows a [collapsible large title](/docs/api/title#collapsible-large-titles) that displays when at the top of the content, then condenses to show the smaller title in the first header when scrolling down. + +:::tip Learn More +For detailed information about Ionic layout components, see the [Header](/docs/api/header), [Toolbar](/docs/api/toolbar), [Title](/docs/api/title), and [Content](/docs/api/content) documentation. +::: + +## Add an Ionic Component + +You can enhance your Home page with more Ionic UI components. For example, add a [Button](/docs/api/button) at the end of the `ion-content`: + +```html + + + + Navigate + +``` + +Then, import the `IonButton` component in `home.page.ts`: + +```ts +import { IonButton, IonContent, IonHeader, IonTitle, IonToolbar } from '@ionic/angular/standalone'; + +@Component({ + // ...existing config... + imports: [IonButton, IonContent, IonHeader, IonTitle, IonToolbar], +}) +``` + +## Add a New Page + +To add a new page, generate it with the CLI: + +```shell +ionic generate page new +``` + +A route will be automatically added to `app.routes.ts`. + +In your `new/new.page.html`, you can add a [Back Button](/docs/api/back-button) to the [Toolbar](/docs/api/toolbar): + +```html + + + + + + new + + +``` + +And import `IonBackButton` and `IonButtons` in `new/new.page.ts`: + +```ts +import { IonBackButton, IonButtons, IonContent, IonHeader, IonTitle, IonToolbar } from '@ionic/angular/standalone'; + +@Component({ + // ...existing config... + imports: [IonBackButton, IonButtons, IonContent, IonHeader, IonTitle, IonToolbar], +}) +``` + +The `ion-back-button` will automatically handle navigation back to the previous page, or to `/` if there is no history. + +## Navigate to the New Page + +To navigate to the new page, update the button in `home/home.page.html`: + +```html +Navigate +``` + +Then, import `RouterLink` in `home/home.page.ts`: + +```ts +import { RouterLink } from '@angular/router'; + +@Component({ + // ...existing config... + imports: [IonButton, IonContent, IonHeader, IonTitle, IonToolbar, RouterLink], +}) +``` + +:::info +Navigating can also be performed using Angular's Router service. See the [Angular Navigation documentation](/docs/angular/navigation#navigating-to-different-routes) for more information. +::: + +## Add Icons to the New Page + +Ionic Angular comes with [Ionicons](https://ionic.io/ionicons/) pre-installed. You can use any icon by setting the `name` property on the `ion-icon` component. Add the following icons to `new/new.page.html`: + +```html + + + + + + +``` + +You'll also need to import and register these icons in `new/new.page.ts`: + +```ts +// ...existing imports... +import { IonBackButton, IonButtons, IonContent, IonHeader, IonIcon, IonTitle, IonToolbar } from '@ionic/angular/standalone'; +import { addIcons } from 'ionicons'; +import { heart, logoIonic } from 'ionicons/icons'; + +@Component({ + // ...existing config... + imports: [IonBackButton, IonButtons, IonContent, IonHeader, IonIcon, IonTitle, IonToolbar], +}) +``` + +Then, update the constructor of the page to use `addIcons`: + +```ts +export class NewPage implements OnInit { + constructor() { + addIcons({ heart, logoIonic }); + } + + ngOnInit() {} +} +``` + +Alternatively, you can register icons in `app.component.ts` to use them throughout your app. + +For more information, see the [Icon documentation](/docs/api/icon) and the [Ionicons documentation](https://ionic.io/ionicons/). + +## Call Component Methods + +Let's add a button that can scroll the content area to the bottom. + +Update the `ion-content` in your `new/new.page.html` to include a button and some items after the existing icons: + +```html + + + + new + + + + + + + Scroll to Bottom + + + @for (item of items; track $index; let i = $index) { + + Item {{ i + 1 }} + + } + +``` + +In the component, add the `ViewChild` import, the new component imports and define the `scrollToBottom` function: + +```ts +import { Component, OnInit, ViewChild } from '@angular/core'; +import { + IonBackButton, + IonButton, + IonButtons, + IonContent, + IonHeader, + IonIcon, + IonItem, + IonLabel, + IonTitle, + IonToolbar, +} from '@ionic/angular/standalone'; +import { addIcons } from 'ionicons'; +import { heart, logoIonic } from 'ionicons/icons'; + +@Component({ + // ...existing config... + imports: [ + IonBackButton, + IonButton, + IonButtons, + IonContent, + IonHeader, + IonIcon, + IonItem, + IonLabel, + IonTitle, + IonToolbar, + ], +}) +export class NewPage implements OnInit { + @ViewChild(IonContent) content!: IonContent; + + items = Array.from({ length: 50 }, (_, i) => i); + + constructor() { + addIcons({ heart, logoIonic }); + } + + ngOnInit() {} + + scrollToBottom = () => { + this.content.scrollToBottom(300); + }; +} +``` + +To call methods on Ionic components: + +1. Create a `ViewChild` reference for the component +2. Call the method directly on the component instance + +You can find available methods for each component in the [Methods](/docs/api/content#methods) section of their API documentation. + +## Run on a Device + +Ionic's components work everywhere: on iOS, Android, and PWAs. To deploy to mobile, use [Capacitor](https://capacitorjs.com): + +```shell +ionic build +ionic cap add ios +ionic cap add android +``` + +Open the native projects in their IDEs: + +```shell +ionic cap open ios +ionic cap open android +``` + +See [Capacitor's Getting Started guide](https://capacitorjs.com/docs/getting-started/with-ionic) for more. + +## Explore More + +This guide covered the basics of creating an Ionic Angular app, adding navigation, and introducing Capacitor for native builds. To dive deeper, check out: + + + + +

Build a real Photo Gallery app with Ionic Angular and native device features.

+ + + +

Learn more about Angular's core concepts, tools, and best practices from the official Angular documentation.

+ + + +

Discover how to handle routing and navigation in Ionic Angular apps using the Angular Router.

+ + + +

Explore Ionic's rich library of UI components for building beautiful apps.

+ + + +

Learn how to customize the look and feel of your app with Ionic's powerful theming system.

+ + + +

Explore how to access native device features and deploy your app to iOS, Android, and the web with Capacitor.

+ + + diff --git a/docs/index.md b/docs/index.md index b49b366f28e..1979dcc7560 100644 --- a/docs/index.md +++ b/docs/index.md @@ -22,7 +22,7 @@ import DocsCards from '@components/global/DocsCards'; -Ionic is an open source UI toolkit for building performant, high-quality mobile apps using web technologies — HTML, CSS, and JavaScript — with integrations for popular frameworks like [Angular](angular/overview.md), [React](react.md), and [Vue](vue/overview.md). +Ionic is an open source UI toolkit for building performant, high-quality mobile apps using web technologies — HTML, CSS, and JavaScript — with integrations for popular frameworks like [Angular](angular/overview.md), [React](react/overview.md), and [Vue](vue/overview.md). Get started building by [installing Ionic](intro/cli.md) or following our [First App Tutorial](intro/next.md#build-your-first-app) to learn the main concepts. @@ -58,7 +58,7 @@ Get started building by [installing Ionic](intro/cli.md) or following our [First ## Overview -Ionic focuses on the frontend UX and UI interaction of an app — UI controls, interactions, gestures, animations. It's easy to learn, and integrates with other libraries or frameworks, such as [Angular](angular/overview.md), [React](react.md), or [Vue](vue/overview.md). Alternatively, it can be used standalone without any frontend framework using a simple [script include](intro/cdn.md). If you’d like to learn more about Ionic before diving in, we created a video to walk you through the basics. +Ionic focuses on the frontend UX and UI interaction of an app — UI controls, interactions, gestures, animations. It's easy to learn, and integrates with other libraries or frameworks, such as [Angular](angular/overview.md), [React](react/overview.md), or [Vue](vue/overview.md). Alternatively, it can be used standalone without any frontend framework using a simple [script include](intro/cdn.md). If you’d like to learn more about Ionic before diving in, we created a video to walk you through the basics. ### One codebase, running everywhere diff --git a/docs/react.md b/docs/react.md deleted file mode 100644 index 9c08d456016..00000000000 --- a/docs/react.md +++ /dev/null @@ -1,147 +0,0 @@ ---- -title: Ionic React -sidebar_label: Overview -hide_title: true -hide_table_of_contents: true ---- - -import PageStyles from '@components/page/react/PageStyles'; - -import DocsCard from '@components/global/DocsCard'; -import DocsCards from '@components/global/DocsCards'; - - - Create an Ionic React App: Framework and Documentation - - - - - -
-
-

One Codebase
Any Platform
Just React

- -- ✓ 100+ mobile optimized React UI components -- ✓ Standard React tooling with react-dom -- ✓ iOS / Android / Electron / PWA - -[Get Started](#installation) - -
- -
- -
-
- -### Build awesome apps across mobile and web, with the React you know and love. - -Ionic React is native React version of Ionic Framework, the free, open source SDK powering millions of mission-critical apps all over the world. - -It's everything you need to ship award-winning apps for any platform, with React. - -
- -
- -## Amazing Design - -Choose from over 100 beautiful, mobile-ready UI components, animations, and gestures, lightweight and customized to fit your brand. - -[Explore UI components](/docs/components) - -
- -
- -
- -
- -
- -
- -## Familiar tooling - -Ionic React projects are just like React projects, leveraging [react-dom](https://react.dev/reference/react-dom) and with setup normally found in a [Create React App (CRA)](https://github.com/facebook/create-react-app) app. For [routing and navigation](/docs/react/navigation), React Router is used under the hood. -Compatible with React version 16.8 and above. - -
- -
- -
- -
- -
- -
- -## More than mobile - -Deploy your Ionic React projects to native iOS, Android, Electron, and the web as a Progressive Web App, using [Capacitor](https://capacitorjs.com), a modern native runtime. All with one shared codebase. - -
- -
- -
- -
- -
- -
- -## Just React - -At the end of the day, it's just React. Ionic React uses open web standards and built-in browser capabilities, so it's compatible with any of the millions of web libraries out there. - -
- -
- -
- -
- -## Installation - -```shell-session -$ npm install -g @ionic/cli -$ ionic start myApp tabs --type react - -$ ionic serve █ -``` - -## Resources - - - -

Learn the fundamentals you need to know to start building amazing apps with Ionic Framework.

- - - -

Use individual components or the complete app experience.

- - - -

Learn the basics of navigation inside your app with Ionic and React Router

- - - -

Learn about using Ionic lifecycle events in class components and with hooks

- - - - - diff --git a/docs/react/overview.md b/docs/react/overview.md new file mode 100644 index 00000000000..2eabc376084 --- /dev/null +++ b/docs/react/overview.md @@ -0,0 +1,69 @@ +--- +title: 'Ionic React Overview' +sidebar_label: Overview +--- + + + Ionic React Overview | React Version Support and Tooling + + + +import DocsCard from '@components/global/DocsCard'; +import DocsCards from '@components/global/DocsCards'; + +`@ionic/react` brings the full power of the Ionic Framework to React developers. It offers seamless integration with the React ecosystem, so you can build high-quality cross-platform apps using familiar React tools, components, and best practices. You also get access to Ionic's extensive UI library and native capabilities. + +## React Version Support + +Ionic React supports the latest versions of React. For detailed information on supported versions and our support policy, see the [Ionic React Support Policy](/docs/reference/support#ionic-react). + +## React Tooling + +Ionic React works seamlessly with the React CLI and popular React tooling. You can use your favorite libraries for state management, testing, and more. Ionic React is designed to fit naturally into the React ecosystem, so you can use tools like Create React App, Vite, or Next.js to scaffold and build your apps. + +## Native Tooling + +[Capacitor](https://capacitorjs.com) is the official cross-platform runtime for Ionic Angular, enabling your apps to run natively on iOS, Android, and the web with a single codebase. + +## Installation + +```shell-session +$ npm install -g @ionic/cli +$ ionic start myApp tabs --type react + +$ cd myApp +$ ionic serve █ +``` + +## Resources + + + + +

Quickly set up your first Ionic React app and learn the basics of the framework and CLI.

+ + + +

Learn more about React's core concepts, tools, and best practices from the official React documentation.

+ + + +

Discover how to handle routing and navigation in Ionic React apps using the React Router.

+ + + +

Explore Ionic's rich library of UI components for building beautiful apps.

+ + + +

Learn how to customize the look and feel of your app with Ionic's powerful theming system.

+ + + +

Explore how to access native device features and deploy your app to iOS, Android, and the web with Capacitor.

+ + + diff --git a/docs/react/performance.md b/docs/react/performance.md index 6851f43fef9..01a2b2501ec 100644 --- a/docs/react/performance.md +++ b/docs/react/performance.md @@ -1,6 +1,6 @@ --- -sidebar_label: Performance title: React Performance +sidebar_label: Performance --- diff --git a/docs/react/quickstart.md b/docs/react/quickstart.md index 3361e6df34f..d0242135d51 100644 --- a/docs/react/quickstart.md +++ b/docs/react/quickstart.md @@ -1,394 +1,344 @@ --- -title: Intro Ionic React Quickstart +title: Ionic React Quickstart sidebar_label: Quickstart --- - Intro to Ionic React Quickstart Using Ionic CLI: React Basics + Ionic React Quickstart Using Ionic CLI: React Basics -## What is Ionic Framework? +import DocsCard from '@components/global/DocsCard'; +import DocsCards from '@components/global/DocsCards'; -First off, if you're new here, welcome! Ionic is a free and open source component library for building apps that run on iOS, Android, Electron, and the Web. You write your app once using familiar technologies (HTML, CSS, JavaScript) and deploy to any platform. +Welcome! This guide will walk you through the basics of Ionic React development. You'll learn how to set up your development environment, generate a simple project, explore the project structure, and understand how Ionic components work. This is perfect for getting familiar with Ionic React before building your first real app. -Along with the UI components, Ionic also provides a command line tool for creating new apps, as well as deploying to the various platforms we support. +If you're looking for a high-level overview of what Ionic React is and how it fits into the React ecosystem, see the [Ionic React Overview](overview). -In this guide, we'll go over the basics of both React and Ionic, including any Ionic specific features. If you're familiar with React, enjoy the guide and learn something new about Ionic. If you're not familiar with either, no worries! This guide will cover the basics and provide enough information to get an app up and running. +## Prerequisites -## Creating a project with the Ionic CLI +Before you begin, make sure you have Node.js and npm installed on your machine. +You can check by running: -To get started, let's install the latest version of the Ionic CLI. +```shell +node -v +npm -v +``` + +If you don't have Node.js and npm, [download Node.js here](https://nodejs.org/en/download) (which includes npm). + +## Create a Project with the Ionic CLI + +First, install the latest [Ionic CLI](../cli): ```shell npm install -g @ionic/cli ``` -From here, the global command `ionic` will allow for the creation of a React project with Ionic and any other dependencies. To create a new project, run the following command: +Then, run the following commands to create and run a new project: ```shell -ionic start myApp blank --type=react +ionic start myApp blank --type react + cd myApp +ionic serve ``` -From here, we run `ionic serve` and have our project running in the browser. +After running `ionic serve`, your project will open in the browser. -## A look at a React Component +![Screenshot of the Ionic React Home page](/img/guides/quickstart/home-page.png 'Ionic React Home Component') -The base of our app will be in the `src` directory, and the main entry point will be our `index.tsx`. If we open our project in a code editor and open `src/index.tsx`, we should see the following: +## Explore the Project Structure -```tsx -import React from 'react'; -import ReactDOM from 'react-dom'; -import App from './App'; +Your new app's `src` directory will look like this: -ReactDOM.render(, document.getElementById('root')); +```shell +├── App.tsx +├── components +│   ├── ExploreContainer.css +│   └── ExploreContainer.tsx +├── main.tsx +└── pages +    ├── Home.css +    └── Home.tsx ``` -So what's going on here? Well, the first three lines are pulling in some dependencies. The first being React itself. This allows us to write components in an HTML-like syntax called JSX. We'll talk about JSX a bit later on. +:::info +All file paths in the examples below are relative to the `src/` directory. +::: -The second import is for ReactDOM. The `ReactDOM.render` method is the browser/DOM specific way of taking our components and rendering it to a specified DOM node. +Let's walk through these files to understand the app's structure. -The last import is the root component for our app, simply named `App`. This is our first React component and will be used in the bootstrapping process for our React app. +## View the App Component -If we open `App.tsx`, we should see the following. +The root of your app is defined in `App.tsx`: ```tsx -import React from 'react'; -import { Route } from 'react-router-dom'; -import { IonApp, IonRouterOutlet } from '@ionic/react'; +import { Redirect, Route } from 'react-router-dom'; +import { IonApp, IonRouterOutlet, setupIonicReact } from '@ionic/react'; import { IonReactRouter } from '@ionic/react-router'; import Home from './pages/Home'; -/* Core CSS required for Ionic components to work properly */ -import '@ionic/react/css/core.css'; +// ..CSS imports... + +setupIonicReact(); const App: React.FC = () => ( - - } /> + + + + + + ); -``` -At first glance, it may look like a lot is going on, so let's break it down, starting with the first group of imports. - -```tsx -import React from 'react'; -import { Route } from 'react-router-dom'; -import { IonApp, IonRouterOutlet } from '@ionic/react'; -import { IonReactRouter } from '@ionic/react-router'; -import Home from './pages/Home'; +export default App; ``` -Similar to `index.tsx`, we first must import React to use JSX. - -The next import is from `react-router-dom`. We're importing Route, which is how we’ll match the app’s URL with the components we want to render +This sets up the root of your application, using Ionic's `IonApp` and `IonReactRouter` components. The `IonRouterOutlet` is where your pages will be displayed. -Following ReactRouter, we next have our first imports for Ionic. To use a component in React, you must first import it. So for Ionic, this means anytime we want to use a Button or a Card, it must be added to our imports. In the case of our App component, we're only using `IonApp`, `IonRouterOutlet`, and `IonReactRouter`. +## View Routes -`IonReactRouter` is a component that wraps ReactRouter’s BrowserRouter component. It more or less behaves the same as BrowserRouter with a few differences. We have a deeper guide that goes over these differences in our [React Navigation Docs](navigation.md). - -The last important import is the `Home` component import. This is a component that we will be able to navigate to in our app. We'll look at the navigation part a bit later. - -The CSS import is pulling in the utility styles from Ionic for things like padding, typography, etc. - -After reviewing all of the imports, we now get to our first look at a React Component: +Routes are defined within the `IonRouterOutlet` in `App.tsx`: ```tsx -const App: React.FC = () => ( - - - - - } /> - - - -); + + + + + + + + ``` -This React component sets up the initial routing for our app, as well as include some core Ionic components for animations and layout (IonRouterOutlet and IonApp). One thing that stands out is that in React, to do data-binding, the value is passed in curly braces (`{}`). So in the `Route` component, we can set the value of `component` to the `Home` component from earlier. This is how React will know that that value is not a string, but a reference to a component. - -:::note -What's important to note here is that these are all standard React DOM libraries, meaning there's no custom integration layer or transpilation step. -::: - -## A component with style +When you visit the root URL (`/`), the `Home` component will be loaded. -Now the `App` does not really have a lot to modify here. It's a basic example of a container component. With the Router logic set, all it's responsible for is to render a component that matches the given URL route. Since we already have one component/router setup, let's go ahead and modify our `Home` component. +## View the Home Page -Currently, the `Home` component looks like so: - -![The Home component displayed in a web browser with the text 'The world is your oyster'.](/img/guides/react/first-app/home-route.png 'Ionic React Home Component') +The Home page component, defined in `pages/Home.tsx`, imports the Ionic components and defines the page template: ```tsx import { IonContent, IonHeader, IonPage, IonTitle, IonToolbar } from '@ionic/react'; -import React from 'react'; +import ExploreContainer from '../components/ExploreContainer'; +import './Home.css'; const Home: React.FC = () => { return ( - Ionic Blank + Blank - - The world is your oyster. -

- If you get lost, the{' '} - - docs - {' '} - will be your guide. -

+ + + + Blank + + + ); }; -``` -Much like the `App` component we started with, we have some imports for specific Ionic components, an import for React, and then our React component itself. - -`IonPage` is the base component for all pages (a component with a route/URL), and includes some common building blocks of a full-screen component, like header, title, and content components. - -:::note -When creating your own pages, don't forget to have `IonPage` be the root component for them. Having `IonPage` be the root component is important because it helps ensure transitions work properly as well as provides the base CSS the Ionic components rely on. -::: - -`IonHeader` is a bit self explanatory. It's a component that is meant to exist at the top of the page. `IonHeader` itself doesn't do much by itself, aside from handling some flexbox-based layout. It's meant to hold other components, like `IonToolbar` or `IonSearchbar`. - -`IonContent` is, as its name suggests, the main content area for our page. It's responsible for providing the scrollable content that users will interact with, plus any scroll events that could be used in an app. - -Our current content is relatively simple but does not contain anything that could be used in a real app, so let's change that. - -:::note -For brevity, we're excluding repeating parts of our component, like the function declaration or import statements for other components. -::: - -```tsx - - ... - - - - -

Create Idea

- Run Idea by Brandy - - - 5 Days - - - - - +export default Home; ``` -Here in our `IonContent`, we're adding an `IonList` and a much more involved `IonItem` component. Let's look at `IonItem`, as it's the centerpiece here. +This creates a page with a header and scrollable content area. The `IonPage` component provides the basic page structure and must be used on every page. The second header shows a [collapsible large title](/docs/api/title#collapsible-large-titles) that displays when at the top of the content, then condenses to show the smaller title in the first header when scrolling down. -```tsx - - -

Create Idea

- Run Idea by Brandy - - - 5 Days - - -``` +:::tip Learn More +For detailed information about Ionic layout components, see the [Header](/docs/api/header), [Toolbar](/docs/api/toolbar), [Title](/docs/api/title), and [Content](/docs/api/content) documentation. +::: -Looking at our code, we have a special attribute called `slot`. This is key for letting the `IonItem` know where to place the `IonBadge` when it renders. This is not a React API, but a web standards API, and it is used in many Ionic Framework components. (For more information on slots, [see the MDN docs here](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/slot).) +## Add an Ionic Component -Let's look at another component from Ionic, FAB. Floating Action Buttons are a nice way to provide a main action that is elevated from the rest of an app. For this FAB, we'll need three components: a FAB, a FAB Button, and an Icon. +You can enhance your Home page with more Ionic UI components. For example, import and add a [Button](/docs/api/button) at the end of the `IonContent` in `pages/Home.tsx`: ```tsx -import { add } from ‘ionicons/icons’; -… - - - - ... - +import { IonButton, IonContent, IonHeader, IonPage, IonTitle, IonToolbar } from '@ionic/react'; +// ...existing imports... - - - - - - - -``` - -On our main `IonFab`, we're setting its positioning with the vertical and horizontal attributes. We're also setting the render location to "fixed" with the slot attribute. This will tell `IonFab` to render outside of the scrollable content in `IonContent`. - -Now let's wire up a click handler to this. What we want to do is when we click the button, we'll navigate to a new page (which we'll create in a moment). To do this, we'll need to get access to React Router's `useHistory` hook API. Thankfully the `useHistory` hook makes this easy since it can be imported from the react-router package. - -```tsx -import { add } from 'ionicons/icons'; -import { useHistory } from 'react-router'; -... -const Home: React.FC = () => { - const history = useHistory(); +const Home: React.FC = () => { return ( - ... - - ... - - history.push('/new')}> - - - + + + Blank + + + + {/* ...existing content... */} + + Navigate ); -} -export default Home; -``` - -In our component declaration, we're passing in `props` which is of type `RouteComponentProps` (imported from `react-router`). This `props` object gives us access to the history API from React Router, allowing us to push a new route onto the navigation stack. On our `IonFabButton`, we can add a click handler, and just call `props.history.push` and pass in the new route. In this case, we'll navigate to `new`. - -```tsx - props.history.push('/new')} > -``` - -## Creating a new Route - -Now that we have the pieces in place to navigate in our app, we need to create a new component and add the new route to our router declaration. Let's open our `App.tsx` file and add the new route. - -```tsx -... -import Home from './pages/Home'; +}; -import NewItem from './pages/NewItem'; -... -const App: React.FC = () => { - const isAuthed = true; - return ( - - - - - - - - - - ); -} -export default App; +export default Home; ``` -With our router now having an entry for the route `/new`, we'll create the component needed, `NewItem`. This will exist in `src/pages/NewItem.tsx` +## Add a New Page -Let's fill the `NewItem.tsx` with some placeholder content for the moment. +Create a new page at `pages/New.tsx`: ```tsx import { IonBackButton, IonButtons, IonContent, IonHeader, IonPage, IonTitle, IonToolbar } from '@ionic/react'; -import React from 'react'; -const NewItem: React.FC = () => { +const New: React.FC = () => { return ( - + - New Item + New - + + + + New + + + ); }; -export default NewItem; + +export default New; ``` -:::note -Each view must contain an `IonPage` component. Page transitions will not work correctly without it. See the [IonPage Documentation](navigation.md#ionpage) for more information. +This creates a page with a [Back Button](/docs/api/back-button) in the [Toolbar](/docs/api/toolbar). The back button will automatically handle navigation back to the previous page, or to `/` if there is no history. + +:::warning Important +When creating your own pages, always use `IonPage` as the root component. This is essential for proper transitions between pages, base CSS styling that Ionic components depend on, and consistent layout behavior across your app. ::: -The content here is pretty straight forward and should look similar to the `Home` component. What is new is the `IonBackButton` component. This is used to navigate back to the previous route. Pretty straight forward? Ok, but what if we reload the page? +## Navigate to the New Page -Well, in this case, the in-memory history is lost, so the back button disappears. To address this, we can set the `defaultHref` attribute value to the URL we want to navigate to if there is no history. +To navigate to the new page, create a route for it by first importing it at the top of `App.tsx` after the `Home` import: ```tsx -return ( - - - - - - - New Item - - - - -); +import New from './pages/New'; ``` -Here, when we reload, if there is no app history present, we'll be able to navigate back to our home route. +Then, add its route in `IonRouterOutlet`: -## Adding Icons +```tsx + + + + + + + + + + + +``` -Ionic React comes with (https://ionic.io/ionicons/) pre-installed. All you need to do is import the icon of your choice from the `ionicons` package, and pass it to an `IonIcon` component through the `icon` prop: +Once that is done, update the button in `pages/Home.tsx`: ```tsx -import React from 'react'; -import { IonButton, IonContent, IonIcon } from '@ionic/react'; -import { camera } from 'ionicons/icons'; - -export const IconExample: React.FC = () => { - - - - Take Picture - - ; -}; +Navigate ``` -Note that for React, we are passing the imported SVG reference, **not** the icon name as a string. +:::info +Navigating can also be performed programmatically using React Router's `history` prop. See the [React Navigation documentation](/docs/react/navigation#navigating-using-history) for more information. +::: + +## Add Icons to the New Page + +Ionic React comes with [Ionicons](https://ionic.io/ionicons/) pre-installed. You can use any icon by setting the `icon` property of the `IonIcon` component. -Developers also have the option of setting different icons based upon the mode: +Update the imports in `pages/New.tsx` to import `IonIcon` and the `heart` and `logoIonic` icons: ```tsx -import React from 'react'; -import { IonButton, IonContent, IonIcon } from '@ionic/react'; -import { logoAndroid, logoApple } from 'ionicons/icons'; - -export const IconExample: React.FC = () => { - - - - - ; -}; +import { IonBackButton, IonButtons, IonContent, IonHeader, IonIcon, IonPage, IonTitle, IonToolbar } from '@ionic/react'; +import { heart, logoIonic } from 'ionicons/icons'; ``` -## Build a Native App +Then, include them inside of the `IonContent`: -We now have the basics of an Ionic React app down, including some UI components and navigation. The great thing about Ionic’s components is that they work anywhere, including iOS, Android, and PWAs. To deploy to mobile and beyond, we use Ionic’s cross-platform app runtime [Capacitor](https://capacitorjs.com). It provides a consistent, web-focused set of APIs that enable an app to stay as close to web-standards as possible while accessing rich native device features on platforms that support them. +```tsx + + +``` -Adding native functionality is easy. First, add Capacitor to your project: +Note that we are passing the imported SVG reference, **not** the icon name as a string. -```shell -ionic integrations enable capacitor +For more information, see the [Icon documentation](/docs/api/icon) and the [Ionicons documentation](https://ionic.io/ionicons/). + +## Call Component Methods + +Let's add a button that can scroll the content area to the bottom. + +Update `pages/New.tsx` to add a `ref` on `IonContent` and a button and some items after the existing icons: + +```tsx + + + + + Scroll to Bottom + + {/* Add lots of content to make scrolling possible */} + {Array.from({ length: 50 }, (_, i) => ( + + Item {i + 1} + + ))} + ``` -Next, build the project, then add your platform of choice: +Then, add the imports for the additional components and define the `scrollToBottom` function: + +```tsx +import { useRef } from 'react'; +import { IonButton, IonBackButton, IonButtons, IonContent, IonHeader, IonIcon, IonItem, IonLabel, IonPage, IonTitle, IonToolbar } from '@ionic/react'; +import { heart, logoIonic } from 'ionicons/icons'; + +const New: React.FC = () => { + const content = useRef(null); + + const scrollToBottom = () => { + content.current?.scrollToBottom(300); + }; + + return ( + // ...existing template... + ); +}; + +export default New; +``` + +To call methods on Ionic components: + +1. Create a `ref` for the component +2. Call the method directly on `ref.current` + +This pattern is necessary because React refs store the component instance in the `.current` property. + +You can find available methods for each component in the [Methods](/docs/api/content#methods) section of their API documentation. + +## Run on a Device + +Ionic's components work everywhere: on iOS, Android, and PWAs. To deploy to mobile, use [Capacitor](https://capacitorjs.com): ```shell ionic build @@ -396,55 +346,43 @@ ionic cap add ios ionic cap add android ``` -We use the standard native IDEs (Xcode and Android Studio) to open, build, and run the iOS and Android projects: +Open the native projects in their IDEs: ```shell ionic cap open ios ionic cap open android ``` -Additional details can be found [here](https://capacitorjs.com/docs/getting-started/with-ionic). +See [Capacitor's Getting Started guide](https://capacitorjs.com/docs/getting-started/with-ionic) for more. -Next, check out [all the APIs](https://capacitorjs.com/docs/apis) that are available. There’s some great stuff, including the [Camera API](https://capacitorjs.com/docs/apis/camera). We can implement photo capture functionality in just a few lines of code: +## Explore More -```tsx -import { IonContent, IonHeader, IonPage, IonTitle, IonToolbar, IonButton } from '@ionic/react'; -import React, { useState } from 'react'; -import { Plugins, CameraResultType } from '@capacitor/core'; +This guide covered the basics of creating an Ionic React app, adding navigation, and introducing Capacitor for native builds. To dive deeper, check out: -const Home: React.FC = () => { - const { Camera } = Plugins; - const [photo, setPhoto] = useState(); - const takePhoto = async () => { - const image = await Camera.getPhoto({ - quality: 90, - allowEditing: true, - resultType: CameraResultType.Uri, - }); - setPhoto(image.webPath); - }; - return ( - - - - Ionic Blank - - - - - Take Photo - - - ); -}; + -export default Home; -``` + +

Build a real Photo Gallery app with Ionic React and native device features.

+ + + +

Learn more about React's core concepts, tools, and best practices from the official React documentation.

+ + + +

Discover how to handle routing and navigation in Ionic React apps using the React Router.

+ -## Where to go from here + +

Explore Ionic's rich library of UI components for building beautiful apps.

+ -This guide covered the basics of creating an Ionic React app, adding some basic navigation, and introducing Capacitor as a way of building native apps. To dive deeper into building complete Ionic apps with React and Capacitor, follow our [First App guide](your-first-app.md). + +

Learn how to customize the look and feel of your app with Ionic's powerful theming system.

+ -For a more detailed look at Ionic’s components, check out the [component API pages](https://ionicframework.com/docs/components). For more details on React, review the [React Docs](https://react.dev/). To keep building native features, see the [Capacitor docs](https://capacitorjs.com/docs/). + +

Explore how to access native device features and deploy your app to iOS, Android, and the web with Capacitor.

+ -Happy app building! 🎉 + diff --git a/docs/vue/build-options.md b/docs/vue/build-options.md new file mode 100644 index 00000000000..5a43eaf6fb7 --- /dev/null +++ b/docs/vue/build-options.md @@ -0,0 +1,109 @@ +--- +title: Vue Build Options +sidebar_label: Build Options +--- + + + Vue Build Options: Component Registration and Build Configuration + + + +import DocsCard from '@components/global/DocsCard'; +import DocsCards from '@components/global/DocsCards'; + +Vue gives you several tools to fine tune your application. This guide covers the build options that are most relevant to Ionic Framework. + +## Component Registration Strategies + +### Local Component Registration (Recommended) + +By default, Ionic Framework components are registered locally. With local registration, these components are imported and provided to each Vue component you want to use them in. This is the recommended approach as it allows lazy loading and treeshaking to work properly with Ionic Framework components. + +The one downside to this approach is that it may be tedious to re-import your Ionic Framework components multiple times. However, we feel that the performance benefits you receive in exchange are worth it. + +Also note that locally registered components are not available in subcomponents. You will need to re-import the Ionic Framework components you would like to use in your subcomponent. + +Let's take a look at how local component registration works: + +```html + + + +``` + +In the example above, we are using the `IonPage` and `IonContent` components. To use them, we import them from `@ionic/vue`. From there, we can use the components in our template. + +Note that since we are registering these components locally, neither `IonPage` nor `IonContent` will be available in `SubComponent` unless we register them there as well. + +For more information, see the [Local Registration Vue Documentation](https://v3.vuejs.org/guide/component-registration.html#local-registration). + +### Global Component Registration + +The other option for registering components is to use global registration. Global registration involves importing the components you want to use in `main.ts` and calling the `component` method on your Vue app instance. + +While this makes it easier to add Ionic Framework components to your Vue app, global registration often is not ideal. To quote the Vue documentation: "If you're using a build system like Webpack, globally registering all components means that even if you stop using a component, it could still be included in your final build. This unnecessarily increases the amount of JavaScript your users have to download". + +Let's take a look at how global component registration works: + +**main.ts** + +```ts +import { IonContent, IonicVue, IonPage } from '@ionic/vue'; + +const app = createApp(App).use(IonicVue).use(router); + +app.component('ion-content', IonContent); +app.component('ion-page', IonPage); +``` + +**MyComponent.vue** + +```html + + + +``` + +In the example above, we are using the `IonPage` and `IonContent` components. To use them, we first import them from `@ionic/vue` in `main.ts`. From there, we call the `component` method on our app instance and pass it the tag name as well as the component definition. After we do that, we can use the components in the rest of our application without having to import them into each Vue component. + +For more information, see the [Global Registration Vue Documentation](https://v3.vuejs.org/guide/component-registration.html#global-registration). + +## Build Optimization + +### Prefetching Application JavaScript + +By default, the Vue CLI will automatically generate prefetch hints for the JavaScript in your application. Prefetching utilizes the browser idle time to download documents that the user might visit in the near future. When the user visits a page that requires the prefetched document, it can be served quickly from the browser's cache. + +Prefetching consumes bandwidth, so if you have a large app, you may want to disable it. You can do this by modifying or creating your `vue.config.js` file: + +**vue.config.js** + +```js +module.exports = { + chainWebpack: (config) => { + config.plugins.delete('prefetch'); + }, +}; +``` + +The configuration above will prevent all files from being prefetched and, instead, will be loaded when they are needed. You can also select certain chunks to prefetch. Check out the [Vue CLI Docs on Prefetching](https://cli.vuejs.org/guide/html-and-static-assets.html#prefetch) for more examples. diff --git a/docs/vue/overview.md b/docs/vue/overview.md index 045cb75b123..b9004523d42 100644 --- a/docs/vue/overview.md +++ b/docs/vue/overview.md @@ -14,30 +14,21 @@ sidebar_label: Overview import DocsCard from '@components/global/DocsCard'; import DocsCards from '@components/global/DocsCards'; -`@ionic/vue` combines the core Ionic Framework experience with the tooling and APIs that are tailored to Vue Developers. +`@ionic/vue` brings the full power of the Ionic Framework to Vue developers. It offers seamless integration with the Vue ecosystem, so you can build high-quality cross-platform apps using familiar Vue tools, components, and best practices. You also get access to Ionic's extensive UI library and native capabilities. ## Vue Version Support -Ionic Vue is built on top of Vue 3.0.0. If you've built an app with early versions of Ionic Vue, you'll want to upgrade to the latest release and upgrade your Vue dependencies. +Ionic Vue v8 supports Vue 3.x. For detailed information on supported versions and our support policy, see the [Ionic Vue Support Policy](/docs/reference/support#ionic-vue). ## Vue Tooling -Ionic Vue projects ship with the same tooling as regular Vue CLI projects. Meaning you'll be building with the Vue CLI and all of it's features. In addition, starter projects also ship with few features enabled by default, like Routing and TypeScript support. +Ionic Vue projects use the same tooling as standard Vue CLI projects, so you can take advantage of the full Vue CLI feature set for building, testing, and deploying your apps. Starter projects come with useful features enabled by default, such as Vue Router for navigation and TypeScript support for type safety and improved developer experience. ## Native Tooling -[Capacitor](https://capacitorjs.com) is the official cross-platform app runtime used to make your `Ionic Vue` web app run natively on iOS, Android, and the web. +[Capacitor](https://capacitorjs.com) is the official cross-platform runtime for Ionic Vue, enabling your apps to run natively on iOS, Android, and the web with a single codebase. -While there are no known technical limitations to using `Ionic Vue` with [Cordova](https://cordova.apache.org/) plugins, Capacitor is officially recommended. There are no plans to support a Cordova integration for `Ionic Vue` in the [Ionic CLI tooling](../cli.md) at this time. For more details, please [see here](https://capacitorjs.com/docs/cordova). - -## From the Community - - - -- [Using Vue.js with Ionic & Capacitor](https://dev.to/aaronksaunders/using-vue-js-v3-beta-with-ionic-components-capacitor-plugins-2b6f) - Aaron Saunders -- [Building Mobile Apps With Vue3 and Ionic](https://soshace.com/building-mobile-apps-with-vue3-and-ionic/) - Oluwaseun Raphael Afolayan - - +While you can use many [Cordova](https://cordova.apache.org/) plugins with Ionic Vue, Capacitor is the recommended and fully supported solution. The [Ionic CLI](../cli.md) does not provide official Cordova integration for Ionic Vue projects. For more information on using Cordova plugins with Capacitor, see the [Capacitor documentation](https://capacitorjs.com/docs/cordova). ## Installation @@ -45,22 +36,36 @@ While there are no known technical limitations to using `Ionic Vue` with [Cordov $ npm install -g @ionic/cli $ ionic start myApp tabs --type vue +$ cd myApp $ ionic serve █ ``` ## Resources - -

Learn the fundamentals you need to know to start building amazing apps with Ionic Framework.

- - -

Learn the basics of navigation inside your app with Ionic and Vue Router

+ +

Quickly set up your first Ionic Vue app and learn the basics of the framework and CLI.

+ + + +

Learn more about Vue's core concepts, tools, and best practices from the official Vue documentation.

+ + + +

Discover how to handle routing and navigation in Ionic Vue apps using the Vue Router.

+ + + +

Explore Ionic's rich library of UI components for building beautiful apps.

+ + + +

Learn how to customize the look and feel of your app with Ionic's powerful theming system.

 - -

Learn about using Ionic lifecycle events in class components and with hooks

+ +

Explore how to access native device features and deploy your app to iOS, Android, and the web with Capacitor.

 diff --git a/docs/vue/performance.md b/docs/vue/performance.md index 6bdfd52346f..e5f7ebc3575 100644 --- a/docs/vue/performance.md +++ b/docs/vue/performance.md @@ -1,4 +1,5 @@ --- +title: Vue Performance sidebar_label: Performance --- diff --git a/docs/vue/platform.md b/docs/vue/platform.md index 74900001f5d..d1fc625812c 100644 --- a/docs/vue/platform.md +++ b/docs/vue/platform.md @@ -1,3 +1,8 @@ +--- +title: Vue Platform +sidebar_label: Platform +--- + # Platform ## isPlatform @@ -81,7 +86,3 @@ type PlatformConfig = { tablet?: ((win: Window) => boolean) | undefined; }; ``` - -``` - -``` diff --git a/docs/vue/quickstart.md b/docs/vue/quickstart.md index b8d46d14c84..8ff548436d1 100644 --- a/docs/vue/quickstart.md +++ b/docs/vue/quickstart.md @@ -4,95 +4,77 @@ sidebar_label: Quickstart --- - Vue QuickStart Global Component for Generating Ionic Vue Apps + Ionic Vue Quickstart Using Ionic CLI: Vue Basics -## What is Ionic Framework? +import DocsCard from '@components/global/DocsCard'; +import DocsCards from '@components/global/DocsCards'; -First off, if you're new here, welcome! Ionic Framework is a free and open source component library for building apps that run on iOS, Android, Electron, and the Web. Write your app once using familiar technologies (HTML, CSS, JavaScript) and deploy to any platform. +Welcome! This guide will walk you through the basics of Ionic Vue development. You'll learn how to set up your development environment, generate a simple project, explore the project structure, and understand how Ionic components work. This is perfect for getting familiar with Ionic Vue before building your first real app. -Along with the UI components, Ionic Framework also provides a command line tool for creating new apps, as well as deploying to the various platforms we support. +If you're looking for a high-level overview of what Ionic Vue is and how it fits into the Vue ecosystem, see the [Ionic Vue Overview](overview). -In this guide, we will go over the basics of both Vue and Ionic Framework, including any Ionic Framework specific features. If you are familiar with Vue, enjoy the guide and learn something new about Ionic Framework. If you are not familiar with either, no worries! This guide will cover the basics and provide enough information to get an app up and running. +## Prerequisites -## Creating a project with the Ionic CLI - -To get started, let's install the latest version of the Ionic CLI. - -```shell -npm install -g @ionic/cli@latest -``` - -From here, the global command `ionic` will allow for the creation of a Vue project with Ionic Framework and any other dependencies. To create a new project, run the following command: +Before you begin, make sure you have Node.js and npm installed on your machine. +You can check by running: ```shell -ionic start myApp blank --type vue -cd myApp +node -v +npm -v ``` -From here, we run `ionic serve` and have our project running in the browser. - -## Build your way with TypeScript or JavaScript +If you don't have Node.js and npm, [download Node.js here](https://nodejs.org/en/download) (which includes npm). -We love TypeScript at Ionic, and have believed for quite some time now that it’s a great tool for building scalable apps. That said, we know how much the Vue community values simplicity – in their tooling, languages, and more. In fact, it’s likely what drew you to Vue in the first place. Start simple – then scale up as needed. +## Create a Project with the Ionic CLI -So, if you’d prefer to use JavaScript instead of TypeScript, you can. After generating an Ionic Vue app, follow these steps: - -1. Remove TypeScript dependencies: +First, install the latest [Ionic CLI](../cli): ```shell -npm uninstall --save typescript @types/jest @typescript-eslint/eslint-plugin @typescript-eslint/parser @vue/cli-plugin-typescript @vue/eslint-config-typescript vue-tsc +npm install -g @ionic/cli ``` -2. Change all `.ts` files to `.js`. In a blank Ionic Vue app, this should only be `src/router/index.ts` and `src/main.ts`. If you're using tests, also change the extension of files in the `tests` directory. +Then, run the following commands to create and run a new project: -3. In `index.html`, change the imported ` ``` -Let's break it down, starting with the imports. +This sets up the root of your application, using Ionic's `ion-app` and `ion-router-outlet` components. The router outlet is where your pages will be displayed. -```html - -``` - -To use a component in Vue, you must first import it. So for Ionic Framework, this means anytime we want to use a Button or a Card, it must be added to our imports. In the case of our `App` component, we are using `IonApp` and `IonRouterOutlet`. Vue's [`script setup` syntax](https://vuejs.org/api/sfc-script-setup.html) gives the template access to those components as `` and ``. +## View Routes -You can also register components globally if you find yourself importing the same components repeatedly. This comes with performance tradeoffs that we cover in [Optimizing Your Build](#optimizing-your-build). +Routes are defined in `router/index.ts`: -From there, let's look at the template. - -```html - -``` - -All Vue components must have a `