ionic-app-creation

What this skill does

# Ionic App Creation

Create a new Ionic app using the Ionic CLI — project scaffolding, framework integration (Angular, React, Vue), Capacitor integration, and Tailwind CSS setup.

## Prerequisites

1. **Node.js** (latest LTS) installed.
2. **Ionic CLI** installed globally (`npm install -g @ionic/cli`). If not installed, install it as part of the procedure.
3. For **iOS development**: Xcode installed.
4. For **Android development**: Android Studio installed.

## Agent Behavior

- **Ask before creating.** Before running `ionic start`, gather all configuration choices from the user. Present available options clearly and wait for confirmation.
- **One decision at a time.** When a step requires user input, ask that single question, wait for the answer, then continue.
- **Present clear options.** Provide concrete choices (e.g., "Which framework: Angular, React, or Vue?") instead of open-ended questions.
- **Guide step-by-step.** Walk the user through the process one step at a time. Never present multiple unrelated questions at once.

## Procedures

### Step 1: Verify the Ionic CLI

Check if the Ionic CLI is installed:

```bash
ionic --version
```

If the command fails or is not found, install it:

```bash
npm install -g @ionic/cli
```

If the user has the legacy `ionic` package installed, uninstall it first:

```bash
npm uninstall -g ionic
npm install -g @ionic/cli
```

### Step 2: Gather Project Configuration

Before creating the app, ask the user the following questions **one at a time**. Present the available options and defaults for each.

#### 2.1: Project Name

Ask the user for the project name. This determines the directory name and the project identifier.

- Example: `my-app`

#### 2.2: Framework

Ask the user which JavaScript framework to use:

| `--type` value        | Framework                          |
| --------------------- | ---------------------------------- |
| `angular`             | Angular (NgModules)                |
| `angular-standalone`  | Angular (Standalone Components)    |
| `react`               | React                              |
| `vue`                 | Vue                                |

Default: `angular`.

#### 2.3: Starter Template

Ask the user which starter template to use:

| Template   | Description                          |
| ---------- | ------------------------------------ |
| `blank`    | An empty project with a single page  |
| `tabs`     | A tabs-based layout                  |
| `sidemenu` | A side menu-based layout             |

The user can also run `ionic start --list` to see all available templates for the selected framework.

Default: `blank`.

#### 2.4: Capacitor Integration

Ask the user if Capacitor should be integrated:

- `--capacitor` — Include Capacitor integration (recommended for native mobile apps).

Default: Yes (include `--capacitor`).

#### 2.5: Package ID

If Capacitor integration was selected, ask the user for the bundle identifier in reverse-DNS notation:

- `--package-id=<id>` — e.g., `com.example.myapp`

This sets the app's bundle ID for both iOS and Android.

#### 2.6: Additional Options

Inform the user about these additional flags and ask if any should be applied:

| Flag               | Description                                                  |
| ------------------ | ------------------------------------------------------------ |
| `--no-deps`        | Skip installing npm dependencies after project creation      |
| `--no-git`         | Do not initialize a Git repository                           |
| `--project-id=<slug>` | Custom slug for directory name and package name          |

Default: None of these flags are applied.

### Step 3: Create the App

Assemble the `ionic start` command from the collected configuration and run it:

```bash
ionic start <name> <template> --type=<framework> --capacitor --package-id=<package-id>
```

Example:

```bash
ionic start my-app blank --type=angular-standalone --capacitor --package-id=com.example.myapp
```

Wait for the command to complete. The Ionic CLI installs dependencies and scaffolds the project.

### Step 4: Verify the Project

Change into the project directory and verify the project was created correctly:

```bash
cd <name>
ionic serve
```

If `ionic serve` starts the development server without errors, the project was created successfully. Stop the server after verification.

### Step 5: Set Up Tailwind CSS (Optional)

Ask the user if they want to add Tailwind CSS to the project.

If yes, read `references/tailwind-css-setup.md` and apply the Tailwind CSS configuration for the user's chosen framework.

### Step 6: Continue with Capacitor Setup

If Capacitor integration was selected in Step 2.4, inform the user that the basic Ionic app with Capacitor has been created. The `ionic start --capacitor` command already installs `@capacitor/core`, `@capacitor/cli`, and creates `capacitor.config.ts`. Switch to the **`capacitor-app-creation`** skill and continue from **Step 5** (Build the Web App) onward to add native platforms, sync, run the app, and configure optional integrations (live updates, CI/CD).

If Capacitor was **not** selected, the skill is complete.

## Error Handling

- **`ionic: command not found`**: The Ionic CLI is not installed globally. Run `npm install -g @ionic/cli`.
- **Permission errors during global install**: The user may need to configure npm for elevated privilege-free global installs, or use `sudo npm install -g @ionic/cli`.
- **`ionic start` fails with network error**: Check internet connectivity. The CLI downloads starter templates from GitHub.
- **`ionic start` fails with "directory already exists"**: A directory with the chosen project name already exists. Either choose a different name or delete the existing directory.
- **`ionic serve` fails with port conflict**: Another process is using port 8100. Stop the conflicting process or run `ionic serve --port=<other-port>`.
- **Dependency installation fails**: Run `npm install` manually in the project directory. If it still fails, check for Node.js version incompatibilities.
- **Template not found**: Run `ionic start --list` to view all available templates for the selected framework. The user may have misspelled the template name.

## Related Skills

- **`capacitor-app-creation`** — Continue Capacitor setup after Ionic app creation (adding platforms, live updates, CI/CD).
- **`ionic-app-development`** — General Ionic development guidance.
- **`ionic-angular`** — Angular-specific Ionic patterns.
- **`ionic-react`** — React-specific Ionic patterns.
- **`ionic-vue`** — Vue-specific Ionic patterns.
- **`capawesome-cloud`** — Set up live updates, native builds, and app store publishing with Capawesome Cloud.