@tapcart/tapcart-cli v0.1.10

Tapcart CLI

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

Installation

• Install the Tapcart CLI globally:

npm install -g @tapcart/tapcart-cli

Get started developing Blocks

Pre-requisites

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

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.

1. Create your project

cd ~/Desktop # or anywhere on your device
tapcart project create

• 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

2. (Optional) Pull down existing blocks

Now pull down the blocks

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.

3. Create a new block

tapcart block create HelloWorld

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

tapcart block dev 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:

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:

tapcart dependency push

This will push the dependencies to your application configuration.

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

tapcart block push 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 HelloWorld
✔ Block versions:
┌─────────┬──────────────────────────┬──────────────┬──────────────┐
│ Version │ ID                       │ LocalVersion │ RemoteVersion│
├─────────┼──────────────────────────┼──────────────┼──────────────┤
│ 1       │ 679d443708d1e5fa9938651a │ active       │ -            │
└─────────┴──────────────────────────┴──────────────┴──────────────┘

tapcart block versions set HelloWorld 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 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:

tapcart component dev 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:

tapcart component push ProductCard

You can also push multiple components at once:

tapcart component push ProductCard Button

Or push all components:

tapcart component push -a

Pulling Components

Pull down the latest version of a component:

tapcart component pull ProductCard

Pull a specific version of a component:

tapcart component pull ProductCard --version 2

Pull multiple components:

tapcart component pull ProductCard Button

Or pull all components:

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 MyComponent

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

# Set a specific version as the active version locally without changing the server
tapcart component pull 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).

Help

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

# Examples
tapcart -h
tapcart project --help
tapcart block -h
tapcart component -h

CLI Version

See your version of the Tapcart CLI.

# Example
tapcart -v # shorthand for --version