App Studio Guide
App Studio Guide

Blocks

Creating a new block

The CLI will scaffold out a new block for you - just run

tapcart block create BlockName

This will output a new block into the directory /blocks/BlockName.

Block Structure

Your custom blocks are populated in your Tapcart project under /blocks directory located at the root of your project. Each block is nested under this directory. Each block contains these four files:

  • code.jsx
    • The source code for your block
  • config.json
    • A configuration file for block metadata
    • Supported fields are: label, tags, dependencies
  • manifest.json
    • A file to house block configurations. These configurations populate the right rail of App Studio when configuring a block. This allows users to customize the block’s appearance and more without any code changes. Documentation on available manifest configurations is available here .
  • manifestConfig.json
    • This file contains overrides to the defaults in manifest.

Every project also has exactly one mockData.json, at the project root — there is no per-block mock data file. tapcart project create and tapcart block create will create it automatically if it doesn't already exist (and never overwrite it if it does). It's read whenever you preview any block, component, or layout with tapcart dev, and lets you override cart, customer, product, collection, and other app data for local preview. Here's an example:

export default function MyBlock({
    useVariables,
}) {
    const variables = useVariables();
    const customer = variables?.customer || {};

    return (
        <Text type={'h1'}>Hello {customer.firstName} from the CLI!</Text>
    );
}
{
    "customer": {
        "id": "uuid-1234-5678-9012-345678901234",
        "firstName": "Ryan"
    }
}

The structure should match the schema at .tapcart/types/mockData.schema.json, which also powers editor IntelliSense for the file. Available variables are documented here.

📘

Note:

The local development server cannot hot reload the variables - you'll need to refresh the page to get any mock data updates.

Pulling Blocks

If your application already has custom blocks, it’s easy to sync them to your local Tapcart project.

In the Tapcart project directory you created, run:

tapcart block pull --all

If you’d like to sync a specific block, you can run

tapcart block pull BlockName

You can also pull by block ID (tapcart block pull 507f1f77bcf86cd799439011), or pull several at once (tapcart block pull BlockName OtherBlock). This will sync the live version of the block to your local machine. To pull a specific version of a block, run:

tapcart block pull BlockName -v VERSION_NUMBER

For more on versioning, see the Publishing section.

Developing Blocks

Once you have your blocks pulled or created, you can run

tapcart dev block BlockName

This will start a local development server (by default at http://localhost:4995) where you can preview your block as you’re developing. Run tapcart dev with no target to launch the dev server and pick a block, component, or layout from a picker in the browser instead. The development server by default has hot reloading of the code, but not of the manifest.json and manifestConfig.json files.

Pushing Blocks

When you’re ready to deploy blocks to App Studio, you can use the tapcart push command by running:

tapcart block push BlockName

Or, if you’d like to push all local blocks:

tapcart block push --all

You can also attach a custom message describing the update, which shows up in the versions table:

tapcart block push BlockName -m "Fix CTA spacing"

block push also runs a non-blocking ESLint pass over the block(s) first and prints any warnings/errors — it never blocks the push. This will push the blocks onto the server. Now, you’re ready to publish them.

👍

Note

Pushing blocks does not make them live by default. If you’d like to push and publish all in one command, please add the --live (-l) flag. Pushing live will prompt you to confirm — pass --yes (-y) to skip the prompt for non-interactive/CI/agent use.

Publishing Blocks

To publish a block and make it live on App Studio, you can use the tapcart block versions command.

To get remote and local versioning information of a block, run:

tapcart block versions list BlockName
✔ Block versions:
┌─────────┬───────────────┬──────────────────┬──────────────────────────┬──────────────┬──────────────┐
│ Version │ Date Modified │ Message           │ ID                       │ LocalVersion │ RemoteVersion│
├─────────┼───────────────┼──────────────────┼──────────────────────────┼──────────────┼──────────────┤
│ 1       │ 6/1/2026, ... │ Tapcart CLI push  │ 679d443708d1e5fa9938651a │ active       │ -            │
└─────────┴───────────────┴──────────────────┴──────────────────────────┴──────────────┴──────────────┘

The versions table is interactive — use ↑/↓ to scroll, PgUp/PgDn to jump a page, q to quit. LocalVersion refers to the version of the block on the local machine. RemoteVersion refers to the version that is currently live on App Studio.

🚧

Warning

The Tapcart CLI local versioning system does not keep track of any local changes. If you're unsure if you're in sync with the remote copy of your local version, run tapcart block pull BlockName -v VERSION_NUMBER.

You can preview the version you’d like to publish by running tapcart block pull BlockName --version VERSION_NUMBER.

Once you’re confident the block acts as intended, you can run tapcart block versions set BlockName -v VERSION_NUMBER.

You should now see the version you selected live in App Studio.

Or, to push and publish in one step:

tapcart block push BlockName --live

📘

Note

Publishing a block will also propagate changes to any layout that includes the block.

Using Custom Components

You can develop a custom App Studio Component using the CLI as well, and import them into blocks:

tapcart component create MyComponent

You then can import them into a block's code like this:

import * as React from 'react';
import { Text } from '@tapcart/mobile-components';
import { MyComponent } from '@tapcart/app-studio-components'; // <-- import component you created

export default function HelloWorld({
    blockConfig,
    tapcartData,
    translations,
    pageState,
    useActions,
}) {

    const containerStyles = {
        padding: '50px 20px',
        margin: '10px',
        backgroundColor: '#ccc',
        textAlign: 'center',
    };

    return (
        <div style={containerStyles}>
            <Text type={'h1'}>Hello from the CLI! V3</Text>
            <Text>Hi from CLI!</Text>
            <MyComponent someProp={123} /> // <-- use component here
        </div>
    );
}

For more on components, see Components

Updated about 1 month ago

Did this page help you?