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
- Node.js (latest LTS) installed.
- Ionic CLI installed globally (
npm install -g @ionic/cli
- For iOS development: Xcode installed.
- For Android development: Android Studio installed.
Agent Behavior
- Ask before creating. Before running , 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:
If the command fails or is not found, install it:
bash
npm install -g @ionic/cli
If the user has the legacy
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.
2.2: Framework
Ask the user which JavaScript framework to use:
| value | Framework |
|---|
| Angular (NgModules) |
| Angular (Standalone Components) |
| React |
| Vue |
2.3: Starter Template
Ask the user which starter template to use:
| Template | Description |
|---|
| An empty project with a single page |
| A tabs-based layout |
| A side menu-based layout |
The user can also run
to see all available templates for the selected framework.
2.4: Capacitor Integration
Ask the user if Capacitor should be integrated:
- — Include Capacitor integration (recommended for native mobile apps).
2.5: Package ID
If Capacitor integration was selected, ask the user for the bundle identifier in reverse-DNS notation:
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 |
|---|
| Skip installing npm dependencies after project creation |
| Do not initialize a Git repository |
| Custom slug for directory name and package name |
Default: None of these flags are applied.
Step 3: Create the App
Assemble the
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:
If
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
command already installs
,
, and creates
. Switch to the
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
- : 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
- fails with network error: Check internet connectivity. The CLI downloads starter templates from GitHub.
- fails with "directory already exists": A directory with the chosen project name already exists. Either choose a different name or delete the existing directory.
- 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 manually in the project directory. If it still fails, check for Node.js version incompatibilities.
- Template not found: Run to view all available templates for the selected framework. The user may have misspelled the template name.
Related Skills
- — Continue Capacitor setup after Ionic app creation (adding platforms, live updates, CI/CD).
- — General Ionic development guidance.
- — Angular-specific Ionic patterns.
- — React-specific Ionic patterns.
- — Vue-specific Ionic patterns.
- — Set up live updates, native builds, and app store publishing with Capawesome Cloud.