Tapcart CLI

The Tapcart CLI is a command-line interface for managing and developing blocks.

Get started developing Blocks

1. Create your project

cd ~/Desktop # or anywhere on your device
npm init @tapcart/tapcart-app@latest [-- -a <application_id> -f <project_name>]

• Project name: Give it a name, like my-test-store
• Application ID: This is found in the Tapcart Dashboard, on the Setting page, under the "Tapcart CLI API Key" section

This will create a new Tapcart project in a folder named my-test-store (or whatever you named it). The project consists of:

my-test-store/
 |--- .tapcart.config.json # This is where the Tapcart CLI stores its configuration
 |--- blocks/ # This is where your blocks will be stored
 |--- components/ # This is where your global components will be stored
 |--- package.json # This is the package file for your project
 |--- yarn.lock # This is the lock file for your project

2. Install Dependencies

Navigate into your project directory:

cd my-test-store
yarn || npm install

3. Authenticate with the Tapcart CLI

You must authenticate with the Tapcart CLI before you can use it. You can do this by running the following command:

yarn tapcart auth login

This will open a browser window where you can log in to your Tapcart account. After logging in, the CLI will store your authentication token locally, allowing you to use the CLI commands without needing to log in again.

4. (Optional) Pull down existing blocks

Now pull down the blocks

yarn tapcart block pull -a

You'll see all your blocks pulled down into new folders. In them, you'll see the following files:

MyBlock/
 |--- code.jsx
 |--- config.json
 |--- manifest.json
 |--- manifestConfig.json
 |--- mockData.json

• code.jsx: This is the React component code for the block
• config.json: This holds high-level metadata about the block, such as its label and tags. Each block's label is its unique identifier. Supported fields are: label, tags, dependencies.
• manifest.json: This holds core config elements for the block, such as configurable CSS elements. This data will be available in the right rail in the dashboard.
• manifestConfig.json: This holds information about which manifest options are selected.
• mockData.json: This is a JSON file that contains mock data for the block. This will be used when developing the block locally. You should add mock data to this file in a structure that matches our documented app variables.

5. Create a new block

yarn tapcart block create HelloWorld

6. Run the new block (or an existing block that was pulled down)

yarn tapcart block dev -b HelloWorld

This will open http://localhost:4995 by default

Make changes to the block in code.jsx and observe the changes in your browser in real time.

Importing Software Dependencies

You can import software dependencies into your block. This is done by adding the dependencies to your project via tapcart dependency add command. For example:

yarn tapcart dependency add lodash 4.17.21

This will add the lodash library to your app's dependencies. You must specify which blocks you want to add the dependency to. This is done by editing the block's config.json file.

{
  "dependencies": ["lodash"]
}

Then, you can import the dependency in your block's code.jsx file:

import * as _ from 'lodash';

Note: The Tapcart ecosystem does not support React component libraries like @mui/material. For UI components, you should use the Tapcart component library.

Pushing Dependencies

You must push your dependencies to your application configuration before they will work in the dashboard or the mobile app. You can do this by running:

yarn tapcart dependency push

This will push the dependencies to your application configuration.

7. Push the block to your block bank

When you're satisfied with your changes, push the block to your block bank. Then head over to the dashboard where you'll be able to see it.

yarn tapcart block push -b HelloWorld

Pushing your block by default does not make it live. You'll need set the version as live after pushing, or use the --live flag when pushing.

tapcart block versions list -b HelloWorld
✔ Block versions:
┌─────────┬──────────────────────────┬──────────────┬──────────────┐
│ Version │ ID                       │ LocalVersion │ RemoteVersion│
├─────────┼──────────────────────────┼──────────────┼──────────────┤
│ 1       │ 679d443708d1e5fa9938651a │ active       │ -            │
└─────────┴──────────────────────────┴──────────────┴──────────────┘

tapcart block versions set -b HelloWorld -v 1
✔ Block version set to 1
┌─────────┬──────────────────────────┬──────────────┬──────────────┐
│ Version │ ID                       │ LocalVersion │ RemoteVersion│
├─────────┼──────────────────────────┼──────────────┼──────────────┤
│ 1       │ 679d443708d1e5fa9938651a │ active       │ live         │
└─────────┴──────────────────────────┴──────────────┴──────────────┘

Or, to do it all in one step:

tapcart block push -b HelloWorld --live

[!WARNING] Running push --live will create a new version of the block and set it as live. If you push without the --live flag, it is recommended to set the version as live via block versions command to avoid creating duplicate versions.

Working with Global Components

Global components are reusable React components that can be shared across multiple blocks. The Tapcart CLI provides commands to create, develop, push, and pull global components.

Creating a Component

Create a new global component:

tapcart component create ProductCard

This will create a new component in the components directory with the following structure:

components/ProductCard/
 |--- code.jsx
 |--- config.json
 |--- manifest.json
 |--- manifestConfig.json
 |--- mockData.json

Developing a Component

Run a local development server for your component:

yarn tapcart component dev -c ProductCard

This will start a development server where you can preview and test your component with hot-reloading.

Pushing Components

Push your component to the Tapcart dashboard:

yarn tapcart component push -c ProductCard

You can also push multiple components at once:

yarn tapcart component push -c ProductCard Button

Or push all components:

yarn tapcart component push -a

Pulling Components

Pull down the latest version of a component:

yarn tapcart component pull ProductCard

Pull a specific version of a component:

yarn tapcart component pull -c ProductCard --version 2

Pull multiple components:

yarn tapcart component pull -c ProductCard Button

Or pull all components:

yarn tapcart component pull -a

Managing Component Versions

The component versions command has the same structure as the block versions command:

# List all versions of a component
tapcart component versions list -c MyComponent

# Set a specific version as the active version on the server
yarn tapcart component versions set -c MyComponent -v 2

# Set a specific version as the active version locally without changing the server
yarn tapcart component pull -c MyComponent --version 1

Note that the version index is 1-based, so set MyComponent 1 sets the first version as active.

When listing component versions, you'll see both the local version (marked as "active" in the LocalVersion column) and the remote version (marked as "live" in the RemoteVersion column).

Layouts

Layouts are collection of blocks that create a page - for example your home page. You can develop blocks in a layout context using the Tapcart CLI. You can spin up the layout development server with the following command:

yarn tapcart layout dev

yarn tapcart layout dev -s home #layout types are documented in the CLI help menu
yarn tapcart layout dev home -b HelloWorld # Spins up the home layout development server using local HelloWorld block
yarn tapcart layout dev home --all # Spins up the home layout development server using all local blocks

By default, the dev server will render the layout with the server version of blocks. If you want to use the local versions, you can pass the --all|-a flag to override all blocks, or --block=BlockFolder to override a specific block.

Help

Open the help menu for any command with the -h (or --help) option.

# Examples
yarn tapcart -h
yarn tapcart block -h
yarn tapcart component -h
yarn tapcart layout -h

CLI Version

See your version of the Tapcart CLI.

# Example
yarn tapcart -v # shorthand for --version