Skip to content
Tutorials Center
My learning

Topics

Lesson 2 of 37 ยท Getting Started

Your First Ionic App with the CLI

Install the Ionic CLI, scaffold a starter app, run it with live reload in the browser, and understand the commands you will use every day.

The Ionic CLI is the command-line tool that creates, serves and builds Ionic projects. In this lesson you install it, generate a starter app, run it in the browser with live reload and learn the handful of commands you will use daily. Everything here is read-only: the commands run on your own machine, not in the site's sandbox.

Prerequisites

You need Node.js (an active LTS release) and npm. Check them first:

Terminal
node --version
npm --version

You do not need Xcode or Android Studio yet. Those only matter when you run on devices (chapter 5 and later). A browser is enough to learn Ionic: the app runs as a normal web page.

Install the CLI

Terminal
npm install -g @ionic/cli
ionic --version

On Linux or macOS, if npm install -g complains about permissions, configure a user-level npm prefix instead of using sudo.

Create an app

The ionic start command takes a name, a starter template and a framework:

Terminal
ionic start photoNotes tabs --type=react

If you omit the options, the CLI asks interactively. Starter templates you will see:

Starter What you get
blank One empty page, the smallest start
list A master/detail list of messages
sidemenu A menu that slides in from the side
tabs A tab bar with three pages

And the framework choices are --type=angular, --type=react and --type=vue. This course explains concepts first and shows all three flavours where code differs. If you are unsure, pick the framework you already know best.

Daily commands

ionic start Create a project
ionic serve Live reload in the browser
ionic build Make production files

Three commands cover the first week.

1 / 2

Run it with live reload

Terminal
cd photoNotes
ionic serve

The CLI starts a dev server (usually http://localhost:8100 for Angular, 5173 for Vite-based React and Vue), opens your browser and reloads on every file save. Use the browser's device toolbar (Chrome or Edge DevTools, "Toggle device toolbar") to see the phone layout. Ionic reads the simulated device and picks the ios or md style automatically.

You can see both styles by adding a query string to the URL while developing:

TEXT
http://localhost:8100/?ionic:mode=ios
http://localhost:8100/?ionic:mode=md

Anatomy of the first page

The tabs starter produces three tab pages. The first one is a page component. In React it looks like this:

JSX
import {
  IonContent, IonHeader, IonPage, IonTitle, IonToolbar,
} from '@ionic/react';

const Tab1: React.FC = () => (
  <IonPage>
    <IonHeader>
      <IonToolbar>
        <IonTitle>Tab 1</IonTitle>
      </IonToolbar>
    </IonHeader>
    <IonContent fullscreen>
      <IonHeader collapse="condense">
        <IonToolbar>
          <IonTitle size="large">Tab 1</IonTitle>
        </IonToolbar>
      </IonHeader>
    </IonContent>
  </IonPage>
);

export default Tab1;

The Angular version of the same page is an HTML template with ion-header, ion-toolbar, ion-title and ion-content, plus a TypeScript class. The Vue version is a single-file component. In all three the structure is identical. Note the second header with collapse="condense": on iOS the big title collapses into the small one as you scroll.

Edit and see the result

Change the title text, save, and the browser updates without a refresh. Then add a button below the large title:

JSX
<IonContent className="ion-padding">
  <IonButton onClick={() => alert('Hello')}>Click me</IonButton>
</IonContent>

The utility class ion-padding adds standard padding. You will meet more of these utilities in layout, grid and utilities.

A stand-in for live reload

Live reload feels magical, but the idea is simple: watch the files, and when one changes, tell the page to reload. The block below is a stand-in that models the loop with a fake file system; it is not the Ionic dev server.

JS Stand-in: a tiny watch-and-rebuild loop

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Common problems

  • Port already in use. Run ionic serve --port=8200.
  • A blank page after ionic serve. Open the browser console. A missing import of an Ionic component is the most common cause in React and Vue.
  • ionic: command not found. The global npm bin folder is not on your PATH. Re-open the terminal or add it.
  • Old Node version. Upgrade Node; the CLI and the build tools need a current LTS.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Which command starts a dev server with live reload?

    ionic serve runs the dev server and reloads when files change; ionic start creates a project and ionic build makes production files.
  2. 2. What does the tabs starter give you?

    The tabs starter builds a tab bar with three example pages.
  3. 3. How can you preview the iOS look in a desktop browser?

    The ionic:mode query parameter forces a style mode during development.
  4. 4. Do you need Xcode or Android Studio to complete this lesson?

    The app runs as a web page in the browser; native tools matter only for device builds.

Summary

  • Install the CLI with npm install -g @ionic/cli.
  • ionic start name template --type=angular|react|vue creates a project; blank, list, sidemenu and tabs are the starters.
  • ionic serve runs a live-reload server in the browser.
  • Every page is ion-header + ion-toolbar + ion-content.
  • You can force ios or md styling with ?ionic:mode=.

Next: Project Structure and Pages