Tapcart Blocks & Components

Manage Tapcart blocks and global components. Blocks and components have identical operations — this skill covers both. All commands run from the root of the Tapcart project directory.

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

Create

Run the create command, then confirm to the user what was created:

# Block
tapcart block create <BlockFolderName>

# Component
tapcart component create <ComponentFolderName>

After creating, tell the user how to start the dev server (see Dev Server below).

Pull

Run the pull command to sync from the Tapcart dashboard to the local ./blocks or ./components folder:

# Pull all blocks
tapcart block pull -a

# Pull specific block(s)
tapcart block pull -b MyBlock
tapcart block pull -b BlockOne -b BlockTwo

# Pull a specific version of a block
tapcart block pull -b MyBlock -v 2

# Pull all components
tapcart component pull -a

# Pull specific component(s)
tapcart component pull -c ProductCard
tapcart component pull -c ProductCard -c Button

# Pull a specific version of a component
tapcart component pull -c ProductCard -v 3

Constraints:

• -a and -b/-c cannot be combined
• -v can only be used with a single block/component name

Push

Before pushing, read the local code.jsx and config.json to confirm the changes look correct, then confirm with the user before running.

# Push a specific block (creates new version, not live)
tapcart block push -b MyBlock

# Push and set the new version live immediately
tapcart block push -b MyBlock --live

# Push multiple blocks
tapcart block push -b BlockOne -b BlockTwo

# Push all blocks
tapcart block push -a

# Push a specific component
tapcart component push -c ProductCard

# Push and set live
tapcart component push -c ProductCard --live

# Push all components
tapcart component push -a

Warning: --live makes the new version immediately visible to all app users. Default to pushing without --live and then using versions set after the user has verified the result.

Dev Server

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

# Block dev server
tapcart block dev -b MyBlock
tapcart block dev -b MyBlock -p 4995   # custom port, default is 4995

# Component dev server
tapcart component dev -c ProductCard
tapcart component dev -c ProductCard -p 4996   # default is 4996

The dev server opens at http://localhost:<port> (block default: 4995, component default: 4996).

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

Versions

List versions

Run this and show the output to the user:

tapcart block versions list -b MyBlock
tapcart component versions list -c ProductCard

Output shows each version number, which is local, and which is live on the dashboard.

Set a version live

Confirm with the user which version to promote, then run:

tapcart block versions set -b MyBlock -v 2
tapcart component versions set -c ProductCard -v 3

Version numbers are 1-based (version 1 is the first push).