Tapcart Project

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.

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

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.

Step 2 — Install the Tapcart CLI globally

npm install -g @tapcart/tapcart-cli

Verify it installed:

tapcart --version

Step 3 — Get the 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

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

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:

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

Step 5 — Authenticate

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

tapcart auth login

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

Step 6 — Pull existing blocks and components

tapcart block pull -a
tapcart component pull -a

The project is now ready.

Auth

# Log in (opens browser automatically, blocks until complete)
tapcart auth login

# Log out
tapcart auth logout

Credentials are stored locally and persist across sessions.

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.

# 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.

Lint

Run lint and show the output to the user:

# 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.

Logs

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.

# 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
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)
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-project