Back to Details

ionic-app-creation

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Ionic App Creation

Ionic应用创建

Create a new Ionic app using the Ionic CLI — project scaffolding, framework integration (Angular, React, Vue), Capacitor integration, and Tailwind CSS setup.
使用Ionic CLI创建新的Ionic应用——涵盖项目脚手架搭建、框架集成（Angular、React、Vue）、Capacitor集成以及Tailwind CSS配置。

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.
  1. Node.js（最新LTS版本）已安装。
  2. Ionic CLI已全局安装（
    npm install -g @ionic/cli
    ）。如果未安装，可在操作流程中完成安装。
  3. 若进行iOS开发：已安装Xcode。
  4. 若进行Android开发：已安装Android Studio。

Agent Behavior

Agent行为规范

  • 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.
  • 创建前确认：运行
    ionic start
    前，需收集用户的所有配置选择，清晰展示可用选项并等待用户确认。
  • 单次决策：当某一步需要用户输入时，仅提出单个问题，等待答复后再继续。
  • 选项清晰明确：提供具体的选择项（例如："选择哪个框架：Angular、React 还是 Vue？"），而非开放式问题。
  • 分步引导：一步步引导用户完成流程，禁止一次性提出多个不相关的问题。

Procedures

操作流程

Step 1: Verify the Ionic CLI

步骤1：验证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
检查是否已安装Ionic CLI：
bash
ionic --version
如果命令执行失败或提示找不到命令，请执行安装：
bash
npm install -g @ionic/cli
如果用户安装了旧版
ionic
包，请先卸载：
bash
npm uninstall -g ionic
npm install -g @ionic/cli

Step 2: Gather Project Configuration

步骤2：收集项目配置

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

2.1：项目名称

Ask the user for the project name. This determines the directory name and the project identifier.
  • Example: 
    my-app
询问用户项目名称，该名称将决定目录名和项目标识符。
  • 示例：
    my-app

2.2: Framework

2.2：框架选择

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
.
询问用户使用哪个JavaScript框架：
--type
值		框架
angular
Angular (NgModules)
angular-standalone
Angular (Standalone Components)
react
React
vue
Vue
默认值：
angular
。

2.3: Starter Template

2.3：启动模板

Ask the user which starter template to use:
TemplateDescription
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
.
询问用户使用哪个启动模板：
模板描述
blank
仅包含单个页面的空项目
tabs
基于标签栏的布局
sidemenu
基于侧边菜单的布局
用户也可以运行
ionic start --list
查看所选框架支持的所有可用模板。
默认值：
blank
。

2.4: Capacitor Integration

2.4：Capacitor集成

Ask the user if Capacitor should be integrated:
  • --capacitor
    — Include Capacitor integration (recommended for native mobile apps).
Default: Yes (include 
--capacitor
).
询问用户是否需要集成Capacitor：
  • --capacitor
    — 包含Capacitor集成（原生移动应用开发推荐）。
默认值：是（添加
--capacitor
参数）。

2.5: Package ID

2.5：包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.
如果用户选择了Capacitor集成，询问用户反向DNS格式的包标识符：
  • --package-id=<id>
    — 例如：
    com.example.myapp
该值将同时设置iOS和Android端应用的包ID。

2.6: Additional Options

2.6：额外选项

Inform the user about these additional flags and ask if any should be applied:
FlagDescription
--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.
告知用户以下额外参数，并询问是否需要启用：
参数描述
--no-deps
项目创建完成后跳过npm依赖安装
--no-git
不初始化Git仓库
--project-id=<slug>
自定义目录名和包名的slug
默认值：不启用以上任何参数。

Step 3: Create the App

步骤3：创建应用

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.
根据收集到的配置拼接
ionic start
命令并运行：
bash
ionic start <name> <template> --type=<framework> --capacitor --package-id=<package-id>
示例：
bash
ionic start my-app blank --type=angular-standalone --capacitor --package-id=com.example.myapp
等待命令执行完成，Ionic CLI将安装依赖并搭建项目脚手架。

Step 4: Verify the Project

步骤4：验证项目

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.
进入项目目录，验证项目是否创建成功：
bash
cd <name>
ionic serve
如果
ionic serve
能正常启动开发服务且无报错，说明项目创建成功。验证完成后停止服务即可。

Step 5: Set Up Tailwind CSS (Optional)

步骤5：配置Tailwind CSS（可选）

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.
询问用户是否需要在项目中添加Tailwind CSS。
如果是，读取
references/tailwind-css-setup.md
文件，根据用户选择的框架完成Tailwind CSS配置。

Step 6: Continue with Capacitor Setup

步骤6：继续完成Capacitor配置

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.
如果在步骤2.4中选择了集成Capacitor，告知用户带Capacitor的基础Ionic应用已创建完成。
ionic start --capacitor
命令已安装
@capacitor/core
、
@capacitor/cli
并创建了
capacitor.config.ts
文件。切换到**
capacitor-app-creation
技能，从步骤5**（构建Web应用）继续操作，添加原生平台、同步数据、运行应用、配置可选集成（实时更新、CI/CD）。
如果未选择集成Capacitor，本技能流程结束。

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.
  • ionic: command not found
    ：Ionic CLI未全局安装，运行
    npm install -g @ionic/cli
    。
  • 全局安装时权限错误：用户可能需要配置npm实现无需提升权限的全局安装，或使用
    sudo npm install -g @ionic/cli
    。
  • ionic start
    执行失败并提示网络错误    ：检查网络连接，CLI需要从GitHub下载启动模板。
  • ionic start
    执行失败并提示"directory already exists"    ：所选项目名称对应的目录已存在，可选择其他名称或删除现有目录。
  • ionic serve
    执行失败并提示端口冲突    ：其他进程正在占用8100端口，停止冲突进程或运行
    ionic serve --port=<其他端口>
    。
  • 依赖安装失败：在项目目录下手动运行
    npm install
    ，如果仍失败，检查Node.js版本是否兼容。
  • 模板未找到：运行
    ionic start --list
    查看所选框架的所有可用模板，可能是用户拼写错误导致模板找不到。

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.
  • capacitor-app-creation
     — Ionic应用创建完成后继续完成Capacitor配置（添加平台、实时更新、CI/CD）。
  • ionic-app-development
     — 通用Ionic开发指南。
  • ionic-angular
     — 针对Angular的Ionic开发模式。
  • ionic-react
     — 针对React的Ionic开发模式。
  • ionic-vue
     — 针对Vue的Ionic开发模式。
  • capawesome-cloud
     — 使用Capawesome Cloud配置实时更新、原生构建和应用商店发布。