Skip to content

docs(quickstart): fix JavaScript initialization and update guides to include full file paths #4322

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 8 commits into
base: main
Choose a base branch
from
+365 −365
Open

docs(quickstart): fix JavaScript initialization and update guides to include full file paths #4322

Show file tree
Hide file tree
Changes from 5 commits
Commits
Show all changes
8 commits
Select commit Hold shift + click to select a range
9bc2371
docs(javascript): update the quickstart to fix npm run preview
brandyscarney Nov 12, 2025
eeeb9c9
docs(vue): update quickstart to include file names and start file pat…
brandyscarney Nov 12, 2025
5f8ef03
docs(angular): update quickstart to include file names and start file…
brandyscarney Nov 12, 2025
f6a2c1c
docs(react): update quickstart to include file names and start file p…
brandyscarney Nov 12, 2025
aec2b7f
style: lint
brandyscarney Nov 12, 2025
1662836
Merge branch 'main' into docs/quickstart-updates
brandyscarney Nov 13, 2025
329a1d5
docs(quickstart): only use full file path in the code title
brandyscarney Nov 13, 2025
5b2128b
docs(quickstart): update links to include md extension
brandyscarney Nov 13, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
86 changes: 44 additions & 42 deletions docs/angular/quickstart.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -55,31 +55,33 @@ After running `ionic serve`, your project will open in the browser.

## Explore the Project Structure

Your new app's `src/app` directory will look like this:
Your new app's 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
└── src/
└── app
├── 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.
All file paths in the examples below are relative to the project root 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`:
The root of your app is defined in `src/app/app.component.ts`:
Copy link
Member Author

@brandyscarney brandyscarney Nov 13, 2025 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I thought it would be more clear to put the full path but if we want to only show the full path in the title of the code block I'm fine with that.

Copy link
Contributor

@thetaPC thetaPC Nov 13, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I would prefer the full path under the title. The same goes for the rest.

But I'm not a stickler on this so I'm good with leaving it as is.

Suggested change
The root of your app is defined in `src/app/app.component.ts`:
The root of your app is defined in `app.component.ts`:

Copy link
Member Author

@brandyscarney brandyscarney Nov 13, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I agree. I think it's easier to follow and then you can still find the full path on top of the code: 329a1d5


```ts
```ts title="src/app/app.component.ts"
import { Component } from '@angular/core';
import { IonApp, IonRouterOutlet } from '@ionic/angular/standalone';

Expand All @@ -93,9 +95,9 @@ export class AppComponent {
}
```

And its template in `app.component.html`:
And its template in `src/app/app.component.html`:

```html
```html title="src/app/app.component.html"
<ion-app>
<ion-router-outlet></ion-router-outlet>
</ion-app>
Expand All @@ -105,9 +107,9 @@ This sets up the root of your application, using Ionic's `ion-app` and `ion-rout

## View Routes

Routes are defined in `app.routes.ts`:
Routes are defined in `src/app/app.routes.ts`:

```ts
```ts title="src/app/app.routes.ts"
import { Routes } from '@angular/router';

export const routes: Routes = [
Expand All @@ -127,9 +129,9 @@ 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:
The Home page component, defined in `src/app/home/home.page.ts`, imports the Ionic components it uses:

```ts
```ts title="src/app/home/home.page.ts"
import { Component } from '@angular/core';
import { IonHeader, IonToolbar, IonTitle, IonContent } from '@ionic/angular/standalone';

Expand All @@ -144,9 +146,9 @@ export class HomePage {
}
```

And the template, in the `home.page.html` file, uses those components:
And the template, in the `src/app/home/home.page.html` file, uses those components:

```html
```html title="src/app/home/home.page.html"
<ion-header [translucent]="true">
<ion-toolbar>
<ion-title> Blank </ion-title>
Expand Down Expand Up @@ -180,17 +182,17 @@ For detailed information about Ionic layout components, see the [Header](/docs/a

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
```html title="src/app/home/home.page.html"
<ion-content>
<!-- existing content -->

<ion-button>Navigate</ion-button>
</ion-content>
```

Then, import the `IonButton` component in `home.page.ts`:
Then, import the `IonButton` component in `src/app/home/home.page.ts`:

```ts
```ts title="src/app/home/home.page.ts"
import { IonButton, IonContent, IonHeader, IonTitle, IonToolbar } from '@ionic/angular/standalone';

@Component({
Expand All @@ -207,11 +209,11 @@ To add a new page, generate it with the CLI:
ionic generate page new
```

A route will be automatically added to `app.routes.ts`.
A route will be automatically added to `src/app/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):
In `src/app/new/new.page.html`, you can add a [Back Button](/docs/api/back-button) to the [Toolbar](/docs/api/toolbar):

```html
```html title="src/app/new/new.page.html"
<ion-header [translucent]="true">
<ion-toolbar>
<ion-buttons slot="start">
Expand All @@ -222,9 +224,9 @@ In your `new/new.page.html`, you can add a [Back Button](/docs/api/back-button)
</ion-header>
```

And import `IonBackButton` and `IonButtons` in `new/new.page.ts`:
And import `IonBackButton` and `IonButtons` in `src/app/new/new.page.ts`:

```ts
```ts title="src/app/new/new.page.ts"
import { IonBackButton, IonButtons, IonContent, IonHeader, IonTitle, IonToolbar } from '@ionic/angular/standalone';

@Component({
Expand All @@ -237,15 +239,15 @@ The `ion-back-button` will automatically handle navigation back to the previous

## Navigate to the New Page

To navigate to the new page, update the button in `home/home.page.html`:
To navigate to the new page, update the button in `src/app/home/home.page.html`:

```html
```html title="src/app/home/home.page.html"
<ion-button [routerLink]="['/new']">Navigate</ion-button>
```

Then, import `RouterLink` in `home/home.page.ts`:
Then, import `RouterLink` in `src/app/home/home.page.ts`:

```ts
```ts title="src/app/home/home.page.ts"
import { RouterLink } from '@angular/router';

@Component({
Expand All @@ -260,9 +262,9 @@ Navigating can also be performed using Angular's Router service. See the [Angula

## 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`:
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 `src/app/new/new.page.html`:

```html
```html title="src/app/new/new.page.html"
<ion-content>
<!-- existing content -->

Expand All @@ -271,9 +273,9 @@ Ionic Angular comes with [Ionicons](https://ionic.io/ionicons/) pre-installed. Y
</ion-content>
```

You'll also need to import and register these icons in `new/new.page.ts`:
You'll also need to import and register these icons in `src/app/new/new.page.ts`:

```ts
```ts title="src/app/new/new.page.ts"
// ...existing imports...
import { IonBackButton, IonButtons, IonContent, IonHeader, IonIcon, IonTitle, IonToolbar } from '@ionic/angular/standalone';
import { addIcons } from 'ionicons';
Expand All @@ -287,7 +289,7 @@ import { heart, logoIonic } from 'ionicons/icons';

Then, update the constructor of the page to use `addIcons`:

```ts
```ts title="src/app/new/new.page.ts"
export class NewPage implements OnInit {
constructor() {
addIcons({ heart, logoIonic });
Expand All @@ -297,17 +299,17 @@ export class NewPage implements OnInit {
}
```

Alternatively, you can register icons in `app.component.ts` to use them throughout your app.
Alternatively, you can register icons in `src/app/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:
Update the `ion-content` in your `src/app/new/new.page.html` to include a button and some items after the existing icons:

```html
```html title="src/app/new/new.page.html"
<ion-content [fullscreen]="true" #content>
<ion-header collapse="condense">
<ion-toolbar>
Expand All @@ -331,7 +333,7 @@ Update the `ion-content` in your `new/new.page.html` to include a button and som

In the component, add the `ViewChild` import, the new component imports and define the `scrollToBottom` function:

```ts
```ts title="src/app/new/new.page.ts"
import { Component, OnInit, ViewChild } from '@angular/core';
import {
IonBackButton,
Expand Down
42 changes: 19 additions & 23 deletions docs/javascript/quickstart.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -87,7 +87,7 @@ npm install vite-plugin-static-copy --save-dev

Add a `vite.config.js` file at the project root with the following:

```js
```js title="vite.config.js"
import { defineConfig } from 'vite';
import { viteStaticCopy } from 'vite-plugin-static-copy';

Expand Down Expand Up @@ -122,18 +122,14 @@ This copies the necessary Ionic files that Capacitor will need to work with lazy

Replace the contents of `src/main.js` with the following:

```js
// Determine if the app is running in Capacitor
const isCapacitor = location.protocol === 'capacitor:' || (window.Capacitor && window.Capacitor.platform !== 'web');

```js title="src/main.js"
// Load Ionic
if (isCapacitor) {
// In Capacitor, import Ionic directly from copied dist files
import(/* @vite-ignore */ location.origin + '/ionic.esm.js');
} else {
// In the browser, use the normal loader
import('@ionic/core/loader').then((m) => m.defineCustomElements(window));
}
(async () => {
// Set the path to a variable to
// prevent Vite from analyzing in dev
const ionicPath = '/ionic.esm.js';
await import(/* @vite-ignore */ ionicPath);
})();

// Core CSS required for Ionic components to work properly
import '@ionic/core/css/core.css';
Expand All @@ -158,7 +154,7 @@ This initializes Ionic based on the environment and then imports all of the avai

Update your `index.html` to configure the metadata and use Ionic components:

```html
```html title="index.html"
<!DOCTYPE html>
<html lang="en" dir="ltr">
<head>
Expand Down Expand Up @@ -190,7 +186,7 @@ This sets up the root of your application, using Ionic's `ion-app`, `ion-router`

Routes are defined in the `index.html` using `ion-route` components inside the `ion-router`:

```html
```html title="index.html"
<ion-router>
<ion-route url="/" component="home-page"></ion-route>
<ion-route url="/new" component="new-page"></ion-route>
Expand All @@ -203,7 +199,7 @@ When you visit the root URL (`/`), the `home-page` component will be loaded. Whe

Create a new directory called `pages` inside the `src` folder, then add a file called `HomePage.js` in that directory with the following content:

```js
```js title="src/pages/HomePage.js"
class HomePage extends HTMLElement {
connectedCallback() {
this.innerHTML = `
Expand Down Expand Up @@ -236,7 +232,7 @@ For detailed information about Ionic layout components, see the [Header](/docs/a

Next, add a `<script>` tag before the `src/main.js` import in `index.html` to import the Home page:

```html
```html title="index.html"
<script type="module">
import './src/pages/HomePage.js';
</script>
Expand All @@ -252,7 +248,7 @@ At this point your browser should be displaying the Home page.

You can enhance your Home page with more Ionic UI components. For example, add a [Button](/docs/api/button) to navigate to another page. Update the `HomePage` component in `src/pages/HomePage.js`:

```js
```js title="src/pages/HomePage.js"
class HomePage extends HTMLElement {
connectedCallback() {
this.innerHTML = `
Expand Down Expand Up @@ -283,7 +279,7 @@ customElements.define('home-page', HomePage);

Add a new file named `NewPage.js` to `src/pages` with the following content:

```js
```js title="src/pages/NewPage.js"
class NewPage extends HTMLElement {
connectedCallback() {
this.innerHTML = `
Expand All @@ -309,7 +305,7 @@ This creates a page with a [Back Button](/docs/api/back-button) in the [Toolbar]

Next, update the `<script>` tag which imports the Home page in the `index.html` file to also import the New page:

```html
```html title="index.html"
<script type="module">
import './src/pages/HomePage.js';
import './src/pages/NewPage.js';
Expand All @@ -320,7 +316,7 @@ Next, update the `<script>` tag which imports the Home page in the `index.html`

To navigate to the new page, update the button in `src/pages/HomePage.js` to be inside of an `ion-router-link`:

```html
```html title="src/pages/HomePage.js"
<ion-router-link href="/new">
<ion-button>Navigate</ion-button>
</ion-router-link>
Expand All @@ -338,7 +334,7 @@ Ionic JavaScript comes with [Ionicons](https://ionic.io/ionicons/) support. To u

Add the necessary imports and register the icons in `src/main.js`:

```js
```js title="src/main.js"
// ...Ionic initialization

// Icon imports
Expand All @@ -352,7 +348,7 @@ addIcons({ heart, logoIonic });

Next, update `src/pages/NewPage.js` to include the icons:

```js
```js title="src/pages/NewPage.js"
class NewPage extends HTMLElement {
connectedCallback() {
this.innerHTML = `
Expand Down Expand Up @@ -383,7 +379,7 @@ For more information, see the [Icon documentation](/docs/api/icon) and the [Ioni

Let's add a button that can scroll the content area to the bottom. Update `src/pages/NewPage.js` to include scrollable content and a scroll button:

```js
```js title="src/pages/NewPage.js"
class NewPage extends HTMLElement {
connectedCallback() {
this.innerHTML = `
Expand Down
Loading