tapcart-project

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Tapcart Project

Tapcart 项目

Project-wide operations for a Tapcart CLI project. All commands run from the root of the Tapcart project directory.

You (the agent) run all commands directly unless noted otherwise.

Tapcart CLI项目的全局操作说明。所有命令均需在Tapcart项目目录的根目录下运行。

除非另有说明，否则所有命令均由你（Agent）直接执行

First-Time Setup

首次设置

Walk through these steps in order to get the user from nothing to a working local environment.

按照以下步骤操作，帮助用户从无到有搭建可运行的本地环境。

Step 1 — Check Node.js

步骤1 — 检查Node.js版本

bash

node --version

Node 23 or higher is required. If missing or outdated, tell the user to install it from https://nodejs.org (latest LTS ≥ 23). Node.js is a one-time system prerequisite — wait for them to confirm it is installed before continuing.

bash

node --version

要求Node.js版本为23或更高。若未安装或版本过低，请告知用户从https://nodejs.org下载安装（最新LTS版本需≥23）。Node.js是一次性系统前置依赖，请等待用户确认安装完成后再继续。

Step 2 — Install the Tapcart CLI globally

步骤2 — 全局安装Tapcart CLI

bash

npm install -g @tapcart/tapcart-cli

Verify it installed:

bash

tapcart --version

bash

npm install -g @tapcart/tapcart-cli

验证安装情况：

bash

tapcart --version

Step 3 — Get the App ID

步骤3 — 获取App ID

Ask the user for their Tapcart App ID. They can find it at: https://app.tapcart.com/settings → Tapcart CLI API Key section

向用户索要其Tapcart App ID。用户可在以下位置找到： https://app.tapcart.com/settings → Tapcart CLI API Key 区域

Step 4 — Create the project (skip if one already exists)

步骤4 — 创建项目（已有项目则跳过）

Check whether a

tapcart.config.json

already exists in the current directory. If it does, skip to Step 5.

If no project exists, create one:

bash

npm init @tapcart/tapcart-app@latest -- -a <app-id> -f <folder-name>
cd <folder-name>
npm install

检查当前目录下是否已存在

tapcart.config.json

文件。若存在，直接跳至步骤5。

若项目不存在，执行以下命令创建：

bash

npm init @tapcart/tapcart-app@latest -- -a <app-id> -f <folder-name>
cd <folder-name>
npm install

Step 5 — Authenticate

步骤5 — 身份认证

Run this command — it opens a browser window automatically and blocks until the user completes the OAuth login:

bash

tapcart auth login

Once the command exits, authentication is complete. Continue to the next step.

运行以下命令——它会自动打开浏览器窗口，直到用户完成OAuth登录后才会停止阻塞：

bash

tapcart auth login

命令执行完成后，身份认证即完成。继续下一步。

Step 6 — Pull existing blocks and components

步骤6 — 拉取现有区块与组件

bash

tapcart block pull -a
tapcart component pull -a

The project is now ready.

bash

tapcart block pull -a
tapcart component pull -a

至此，项目搭建完成。

Auth

身份认证

bash

undefined

bash

undefined

Log in (opens browser automatically, blocks until complete)

登录（自动打开浏览器，完成后停止阻塞）

tapcart auth login

Log out

登出

tapcart auth logout


Credentials are stored locally and persist across sessions.

---

tapcart auth logout


凭证会存储在本地，并在会话间持久化保存。

---

Dependencies

依赖管理

Dependencies are npm packages that can be imported inside blocks. They must be added locally and pushed to the remote app config before they work in the dashboard or mobile app.

bash

undefined

依赖是可在区块中导入的npm包。必须先在本地添加，再推送到远程应用配置中，才能在控制台或移动应用中生效。

bash

undefined

Add a dependency

添加依赖

tapcart dependency add lodash 4.17.21

Remove a dependency

移除依赖

tapcart dependency remove lodash

List local dependencies

列出本地依赖

tapcart dependency list

Pull dependencies from remote app config

从远程应用配置拉取依赖

tapcart dependency pull

Push local dependency list to remote app config

将本地依赖列表推送到远程应用配置

tapcart dependency push


After adding a dependency, remind the user to add the package name to the relevant block's `config.json` under `"dependencies": []`, then run `tapcart dependency push`.

---

tapcart dependency push


添加依赖后，请提醒用户将包名添加到对应区块的`config.json`文件的`"dependencies": []`数组中，然后运行`tapcart dependency push`。

---

Lint

代码检查

Run lint and show the output to the user:

bash

undefined

运行代码检查并将结果展示给用户：

bash

undefined

Lint all blocks and components

检查所有区块与组件

tapcart lint --all

Lint specific blocks

检查指定区块

tapcart lint -b MyBlock -b AnotherBlock

Lint specific components

检查指定组件

tapcart lint -c ProductCard

Lint with auto-fix (writes changes to disk)

自动修复问题（会将修改写入磁盘）

tapcart lint --all --fix tapcart lint -b MyBlock --fix


Show the lint output to the user and confirm before running with `--fix`.

---

tapcart lint --all --fix tapcart lint -b MyBlock --fix


执行`--fix`前，请先向用户展示代码检查结果并确认。

---

Logs

日志查看

bash

tapcart log

bash

tapcart log

Layout Dev Server

布局开发服务器

Run the layout dev server in the background and tell the user it is running. Keep it running until the user asks you to stop it.

bash

undefined

在后台启动布局开发服务器，并告知用户服务器已运行。保持服务器运行，直到用户要求停止。

bash

undefined

Prompts interactively for layout type if not provided

若未指定布局类型，会交互式提示用户选择

tapcart layout dev

Specify layout type

指定布局类型

tapcart layout dev -l home

Specify layout type and a particular layout ID

指定布局类型和特定布局ID

tapcart layout dev -l home -v <layoutId>

Override specific blocks with their local version

用本地版本覆盖指定区块

tapcart layout dev -l home -b MyBlock -b AnotherBlock

Override all blocks with local versions

用本地版本覆盖所有区块

tapcart layout dev -l home -a

Custom port (default is 4995)

自定义端口（默认端口为4995）

tapcart layout dev -l home -p 4995


By default the dev server renders blocks using the live dashboard version. Use `-b <BlockFolderName>` to use a local block instead, or `-a` to use all local blocks.

When the user asks to stop the dev server, terminate the process.

tapcart layout dev -l home -p 4995


默认情况下，开发服务器会使用控制台中的线上版本渲染区块。使用`-b <BlockFolderName>`参数可改用本地区块，或使用`-a`参数改用所有本地区块。

当用户要求停止开发服务器时，终止该进程。