Skip to content

Commit f95905c

Browse files
brandyscarneybrandyscarney
committed
docs(angular): add a guide for adding to existing projects
1 parent 43542f0 commit f95905c

File tree

2 files changed

+335
-0
lines changed

2 files changed

+335
-0
lines changed

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

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

‎sidebars.js‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -83,6 +83,7 @@ module.exports = {
8383
'angular/your-first-app/distribute',
8484
],
8585
},
86+
'angular/add-to-existing',
8687
'angular/build-options',
8788
'angular/lifecycle',
8889
'angular/navigation',

0 commit comments

Comments
 (0)