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). If not installed, install it as part of the procedure. - For iOS development: Xcode installed.
- 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:
bashionic --version
If the command fails or is not found, install it:
bashnpm install -g @ionic/cli
If the user has the legacy ionic package installed, uninstall it first:
bashnpm 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:
bashionic start <name> <template> --type=<framework> --capacitor --package-id=<package-id>
Example:
bashionic 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:
bashcd <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. Runnpm 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 startfails with network error: Check internet connectivity. The CLI downloads starter templates from GitHub.ionic startfails with "directory already exists": A directory with the chosen project name already exists. Either choose a different name or delete the existing directory.ionic servefails with port conflict: Another process is using port 8100. Stop the conflicting process or runionic serve --port=<other-port>.- Dependency installation fails: Run
npm installmanually in the project directory. If it still fails, check for Node.js version incompatibilities. - Template not found: Run
ionic start --listto 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.
