Creating a new block

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

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

• mockData.json

  • This file is for development purposes only. It will be read when developing locally and inject variables that will be available for the block via the useVariables prop in the block. Here's an example:
    
  code.jsxmockData.json

  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",
      }
  }

  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:

yarn tapcart block pull -a

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

yarn tapcart block pull -b BlockName

This will sync the live version of the block to your local machine. To pull a specific version of a block, run:

yarn tapcart block pull -b 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

yarn tapcart block dev

This will start a local development server (by default at http://localhost:4995) where you can preview your block as you’re developing. 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:

yarn tapcart block push -b BlockName

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

yarn tapcart block push --all

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

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:

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

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

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

📘

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:

yarn 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