capawesome-team/ionic-app-creation

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:

ionic --version

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

npm install -g @ionic/cli

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

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:

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

Example:

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:

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.