Skip to content

Commit 230ec4c

Browse files
brandyscarneybrandyscarney
committed
docs(vue): add a guide for adding to existing projects
1 parent f95905c commit 230ec4c

File tree

2 files changed

+340
-0
lines changed

2 files changed

+340
-0
lines changed

‎docs/vue/add-to-existing.md‎

Lines changed: 339 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,339 @@
1+
---
2+
title: Add to Existing Vue Project
3+
sidebar_label: Add to Existing
4+
---
5+
6+
import DocsCard from '@components/global/DocsCard';
7+
import DocsCards from '@components/global/DocsCards';
8+
9+
<head>
10+
<title>Add Ionic Vue to Existing Project: Integration Guide</title>
11+
<meta
12+
name="description"
13+
content="Learn how to add Ionic Vue to your existing Vue project. Step-by-step guide for integrating Ionic components and features into an existing Vue application."
14+
/>
15+
</head>
16+
17+
This guide covers how to add Ionic Vue to an existing Vue project. If you're looking to start a new project from scratch, check out the [Ionic Vue Quickstart](/docs/vue/quickstart.md) guide. For an overview of how Ionic Vue works with Vue, including version support and tooling, check out the [Ionic Vue Overview](/docs/vue/overview.md).
18+
19+
:::tip
20+
21+
This guide uses JavaScript examples. If you're using TypeScript, the setup process is the same, but you'll use `.ts` file extensions instead of `.js`.
22+
23+
:::
24+
25+
## Setup
26+
27+
Follow these steps to add Ionic Vue to your existing Vue project:
28+
29+
#### 1. Install the Packages
30+
31+
```bash
32+
npm install @ionic/vue @ionic/vue-router vue-router
33+
```
34+
35+
#### 2. Configure Ionic Vue
36+
37+
Update `src/main.js` to include `IonicVue` and import the required Ionic Framework stylesheets:
38+
39+
```javascript title="src/main.js"
40+
import { createApp } from 'vue';
41+
import { IonicVue } from '@ionic/vue';
42+
43+
import App from './App.vue';
44+
45+
/* Core CSS required for Ionic components to work properly */
46+
import '@ionic/vue/css/core.css';
47+
48+
/* Basic CSS for apps built with Ionic */
49+
import '@ionic/vue/css/normalize.css';
50+
import '@ionic/vue/css/structure.css';
51+
import '@ionic/vue/css/typography.css';
52+
53+
createApp(App).use(IonicVue).mount('#app');
54+
```
55+
56+
These stylesheets are required for Ionic Framework components to render properly.
57+
58+
## Using Individual Components
59+
60+
After completing the setup above, you can start using Ionic components in your existing Vue app. Here's an example of how to use them:
61+
62+
Update `src/App.vue` to the following:
63+
64+
```vue title="src/App.vue"
65+
<template>
66+
<ion-button>Button</ion-button>
67+
<ion-datetime></ion-datetime>
68+
</template>
69+
70+
<script setup lang="ts">
71+
import { IonButton, IonDatetime } from '@ionic/vue';
72+
</script>
73+
```
74+
75+
Visit the [components](/docs/components.md) page for all of the available Ionic components.
76+
77+
## Using Ionic Pages
78+
79+
If you want to use Ionic pages with full navigation and page transitions, follow these additional setup steps.
80+
81+
#### 1. Add Additional Ionic Framework Stylesheets
82+
83+
Update the imported stylesheets in `src/main.js`:
84+
85+
```javascript title="src/main.js"
86+
/* Core CSS required for Ionic components to work properly */
87+
import '@ionic/vue/css/core.css';
88+
89+
/* Basic CSS for apps built with Ionic */
90+
import '@ionic/vue/css/normalize.css';
91+
import '@ionic/vue/css/structure.css';
92+
import '@ionic/vue/css/typography.css';
93+
94+
/* Optional CSS utils that can be commented out */
95+
import '@ionic/vue/css/padding.css';
96+
import '@ionic/vue/css/float-elements.css';
97+
import '@ionic/vue/css/text-alignment.css';
98+
import '@ionic/vue/css/text-transformation.css';
99+
import '@ionic/vue/css/flex-utils.css';
100+
import '@ionic/vue/css/display.css';
101+
```
102+
103+
These stylesheets set up the overall page structure and provide [CSS utilities](/docs/layout/css-utilities.md) for faster development. Some stylesheets are optional. For details on which stylesheets are required, check out [Global Stylesheets](/docs/layout/global-stylesheets.md).
104+
105+
#### 2. Set up Theming
106+
107+
Create a `src/theme/variables.css` file with the following content:
108+
109+
```css title="src/theme/variables.css"
110+
/* For information on how to create your own theme, please refer to:
111+
http://ionicframework.com/docs/theming/ */
112+
```
113+
114+
Then, import the file and the dark palette stylesheet in `src/main.js`:
115+
116+
```javascript title="src/main.js"
117+
import { createApp } from 'vue';
118+
import App from './App.vue';
119+
120+
import { IonicVue } from '@ionic/vue';
121+
122+
/* Core CSS required for Ionic components to work properly */
123+
import '@ionic/vue/css/core.css';
124+
125+
/* Basic CSS for apps built with Ionic */
126+
import '@ionic/vue/css/normalize.css';
127+
import '@ionic/vue/css/structure.css';
128+
import '@ionic/vue/css/typography.css';
129+
130+
/* Optional CSS utils that can be commented out */
131+
import '@ionic/vue/css/padding.css';
132+
import '@ionic/vue/css/float-elements.css';
133+
import '@ionic/vue/css/text-alignment.css';
134+
import '@ionic/vue/css/text-transformation.css';
135+
import '@ionic/vue/css/flex-utils.css';
136+
import '@ionic/vue/css/display.css';
137+
138+
/**
139+
* Ionic Dark Mode
140+
* -----------------------------------------------------
141+
* For more info, please refer to:
142+
* https://ionicframework.com/docs/theming/dark-mode
143+
*/
144+
145+
/* @import '@ionic/vue/css/palettes/dark.always.css'; */
146+
/* @import '@ionic/vue/css/palettes/dark.class.css'; */
147+
import '@ionic/vue/css/palettes/dark.system.css';
148+
149+
/* Theme variables */
150+
import './theme/variables.css';
151+
152+
createApp(App).use(IonicVue).mount('#app');
153+
```
154+
155+
The `variables.css` file can be used to create custom Ionic Framework themes. The `dark.system.css` import enables [dark mode support](/docs/theming/dark-mode.md) for your Ionic app when the system is set to prefer a dark appearance. You can customize the theming behavior by uncommenting different dark palette imports or adding custom CSS variables to `theme/variables.css`.
156+
157+
#### 3. Update the App Component
158+
159+
Update `src/App.vue` to the following:
160+
161+
```vue title="src/App.vue"
162+
<template>
163+
<ion-app>
164+
<ion-router-outlet></ion-router-outlet>
165+
</ion-app>
166+
</template>
167+
168+
<script setup lang="ts">
169+
import { IonApp, IonRouterOutlet } from '@ionic/vue';
170+
</script>
171+
```
172+
173+
#### 4. Create a Home Page
174+
175+
Create a new file at `src/views/HomePage.vue` with the following:
176+
177+
```vue title="src/views/HomePage.vue"
178+
<template>
179+
<ion-page>
180+
<ion-header :translucent="true">
181+
<ion-toolbar>
182+
<ion-title>Home</ion-title>
183+
</ion-toolbar>
184+
</ion-header>
185+
186+
<ion-content :fullscreen="true">
187+
<ion-header collapse="condense">
188+
<ion-toolbar>
189+
<ion-title size="large">Home</ion-title>
190+
</ion-toolbar>
191+
</ion-header>
192+
193+
<div id="container">
194+
<strong>Ready to create an app?</strong>
195+
<p>
196+
Start with Ionic
197+
<a target="_blank" rel="noopener noreferrer" href="https://ionicframework.com/docs/components"
198+
>UI Components</a
199+
>
200+
</p>
201+
</div>
202+
</ion-content>
203+
</ion-page>
204+
</template>
205+
206+
<script setup lang="ts">
207+
import { IonContent, IonHeader, IonPage, IonTitle, IonToolbar } from '@ionic/vue';
208+
</script>
209+
210+
<style scoped>
211+
#container {
212+
text-align: center;
213+
214+
position: absolute;
215+
left: 0;
216+
right: 0;
217+
top: 50%;
218+
transform: translateY(-50%);
219+
}
220+
221+
#container strong {
222+
font-size: 20px;
223+
line-height: 26px;
224+
}
225+
226+
#container p {
227+
font-size: 16px;
228+
line-height: 22px;
229+
230+
color: #8c8c8c;
231+
232+
margin: 0;
233+
}
234+
235+
#container a {
236+
text-decoration: none;
237+
}
238+
</style>
239+
```
240+
241+
#### 5. Set up Routing
242+
243+
Add a file at `src/router/index.js` defining the routes:
244+
245+
```javascript title="src/router/index.js"
246+
import { createRouter, createWebHistory } from '@ionic/vue-router';
247+
import HomePage from '../views/HomePage.vue';
248+
249+
const routes = [
250+
{
251+
path: '/',
252+
redirect: '/home',
253+
},
254+
{
255+
path: '/home',
256+
name: 'Home',
257+
component: HomePage,
258+
},
259+
];
260+
261+
const router = createRouter({
262+
history: createWebHistory(import.meta.env.BASE_URL),
263+
routes,
264+
});
265+
266+
export default router;
267+
```
268+
269+
Update `src/main.js` to include the router:
270+
271+
```javascript title="src/main.js"
272+
import { createApp } from 'vue';
273+
import App from './App.vue';
274+
import router from './router';
275+
276+
import { IonicVue } from '@ionic/vue';
277+
278+
/* Core CSS required for Ionic components to work properly */
279+
import '@ionic/vue/css/core.css';
280+
281+
/* Basic CSS for apps built with Ionic */
282+
import '@ionic/vue/css/normalize.css';
283+
import '@ionic/vue/css/structure.css';
284+
import '@ionic/vue/css/typography.css';
285+
286+
/* Optional CSS utils that can be commented out */
287+
import '@ionic/vue/css/padding.css';
288+
import '@ionic/vue/css/float-elements.css';
289+
import '@ionic/vue/css/text-alignment.css';
290+
import '@ionic/vue/css/text-transformation.css';
291+
import '@ionic/vue/css/flex-utils.css';
292+
import '@ionic/vue/css/display.css';
293+
294+
/**
295+
* Ionic Dark Mode
296+
* -----------------------------------------------------
297+
* For more info, please refer to:
298+
* https://ionicframework.com/docs/theming/dark-mode
299+
*/
300+
301+
/* @import '@ionic/vue/css/palettes/dark.always.css'; */
302+
/* @import '@ionic/vue/css/palettes/dark.class.css'; */
303+
import '@ionic/vue/css/palettes/dark.system.css';
304+
305+
/* Theme variables */
306+
import './theme/variables.css';
307+
308+
const app = createApp(App).use(IonicVue).use(router);
309+
310+
router.isReady().then(() => {
311+
app.mount('#app');
312+
});
313+
```
314+
315+
You're all set! Your Ionic Vue app is now configured with full Ionic page support. Run `npm run dev` to start your development server and view your app.
316+
317+
## Next Steps
318+
319+
Now that you have Ionic Vue integrated into your project, check out:
320+
321+
<DocsCards>
322+
323+
<DocsCard header="Navigation" href="navigation" icon="/icons/component-navigation-icon.png">
324+
<p>Discover how to handle routing and navigation in Ionic Vue apps using the Vue Router.</p>
325+
</DocsCard>
326+
327+
<DocsCard header="Components" href="/docs/components" icon="/icons/guide-components-icon.png">
328+
<p>Explore Ionic's rich library of UI components for building beautiful apps.</p>
329+
</DocsCard>
330+
331+
<DocsCard header="Theming" href="/docs/theming/basics" icon="/icons/guide-theming-icon.png">
332+
<p>Learn how to customize the look and feel of your app with Ionic's powerful theming system.</p>
333+
</DocsCard>
334+
335+
<DocsCard header="Capacitor Documentation" href="https://capacitorjs.com/docs/" icon="/icons/guide-capacitor-icon.png">
336+
<p>Explore how to access native device features and deploy your app to iOS, Android, and the web with Capacitor.</p>
337+
</DocsCard>
338+
339+
</DocsCards>

‎sidebars.js‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -174,6 +174,7 @@ module.exports = {
174174
'vue/your-first-app/distribute',
175175
],
176176
},
177+
'vue/add-to-existing',
177178
'vue/build-options',
178179
'vue/lifecycle',
179180
'vue/navigation',

0 commit comments

Comments
 (0)