Skip to main content

Creating and Maintaining Custom Blocks via Tapcart CLI

Custom blocks let your team build bespoke app experiences in React that sit alongside Tapcart Design Blocks on any screen. After the React Native migration, custom blocks run inside the app WebView using Tapcart's App Studio SDK and are managed with the Tapcart CLI (or the Dev tab in App Studio).

This guide is for developers and technical merchants on Tapcart Enterprise. For configuring Tapcart-provided Design Blocks without code, see Building with Design Blocks.

Availability: Custom blocks and the Tapcart CLI require the Tapcart Enterprise plan. If you do not see the Dev tab or CLI options, contact your Tapcart account team.

What changed after the React Native migration?

  • Custom blocks are written in React (JSX), not the older HTML/vanilla JS custom block editor.

  • Blocks use Tapcart packages such as @tapcart/mobile-components and interact with the native app through WebBridge actions and variables (for example open product, add to cart, read customer/cart state).

  • You develop locally with the CLI, push versions to App Studio, then set a version live when ready.

  • Pushing is not the same as going live. A push creates a new remote version. Merchants see the live version only after you publish it (or push with --live).

Two ways to work on custom blocks

Dev tab in App Studio (in-dashboard)

On any block, open Edit and use the Dev tab to work with the underlying React code directly in the dashboard. This is useful for smaller edits and for teams that prefer not to set up a local project. See Building with Design Blocks for how the AI / Visual / Dev tabs work.

Tapcart CLI (recommended for ongoing development)

The CLI is the standard workflow for creating, reviewing, iterating, and versioning custom blocks in a real Git-friendly project. Full developer docs: Tapcart CLI and App Studio Quick Start.

Set up the Tapcart CLI

  1. Install the CLI (see current install steps on npm):

npm install -g @tapcart/tapcart-cli
tapcart --version

  1. Log in:

tapcart auth login

  1. Get your App ID in App Studio: shop name (top right) → Settings → App Settings → Tapcart CLI / Application ID section.

  2. Create a local project:

tapcart project create -a YOUR_APP_ID -p my-tapcart-project
cd my-tapcart-project

Or use the interactive create flow with tapcart project create (no flags).

Create a new custom block

tapcart block create HelloWorld
tapcart block dev -b HelloWorld

This scaffolds a block under blocks/HelloWorld/ and starts a local preview (default http://localhost:4995).

Block folder structure

Each block contains:

  • code.jsx — React source for the block

  • config.json — block metadata (label, tags, dependencies only)

  • manifest.json — controls shown in the App Studio right rail (text, colors, toggles, destinations, and more)

  • manifestConfig.json — saved dashboard values / overrides for the manifest defaults

Project-level mockData.json powers local preview data (cart, customer, product, and so on). Hot reload updates code automatically; refresh the browser after changing mock data or some manifesto files.

Manifest field reference: Manifest Options for Custom Blocks.

Pull existing blocks from App Studio

If custom blocks already exist in your app, sync them locally before editing:

tapcart block pull -a
# or a single block:
tapcart block pull -b MyBlockName

You can also pull a specific historical version:

tapcart block pull -b MyBlockName -v 3

Push and publish (set live)

Push a new version (does not go live by default)

tapcart block push -b HelloWorld
tapcart block push -b HelloWorld -m "Fix CTA spacing"

Push runs a non-blocking lint pass and creates a new remote version in App Studio.

Review versions and set one live

tapcart block versions list -b HelloWorld
tapcart block versions set -b HelloWorld -v 2

Or push and publish in one step when you are ready:

tapcart block push -b HelloWorld --live

Important: Setting a block version live updates every screen layout that uses that block. Always preview on a test device or soft-launch with display conditions before publishing broadly.

Maintain an existing custom block

Recommended loop for ongoing work:

  1. Pull the latest (or a known-good) version so local files match App Studio.

  2. Develop with tapcart block dev -b BlockName (or full-screen context with layout/dev workflows in the CLI docs).

  3. Push a new version without --live.

  4. Review the new version in App Studio (and on device when needed).

  5. Set live only after review (tapcart block versions set ... or a push with --live).

  6. Rollback by setting an earlier version live if something looks wrong.

Soft-launch updates safely

Every block supports dashboard-level display conditions (customer tags, user groups, device targeting, and more). Use these to limit a new or updated block to internal testers first, then remove the gate after verification. You do not need a code change for this type of rollout.

Review or customize a Tapcart Design Block

To inspect or extend a Tapcart-provided block as editable React code:

  1. In App Studio, save the Design Block as a template (this creates a custom-block copy in your block bank).

  2. Pull it locally with the CLI.

  3. Edit, push, and set live like any other custom block.

Note: templated copies are snapshots. They will not automatically receive future updates Tapcart makes to the original Design Block.

Coding essentials for custom blocks

  • Allowed imports in block runtime: react, @tapcart/mobile-components, and @tapcart/app-studio-components. Extra npm packages will fail when the block runs in the app.

  • Use useTapcart() for actions and variables (preferred over older useActions / useVariables patterns).

  • Call native features with actions, for example Tapcart?.action?.('product/open', { productId }) or Tapcart?.action?.('cart/add', { lineItems: [...] }).

  • Follow React Rules of Hooks — call all hooks before any early returns to avoid render crashes.

  • Render HTML through Tapcart's Html component — do not use dangerouslySetInnerHTML.

  • Prefer Brand Kit tokens for colors and fonts so the block stays consistent with the rest of the app.

  • Never hardcode secrets (Admin API tokens, private third-party keys) in block code. Storefront tokens should come from runtime app data, not pasted into source.

Component library / storybook: Tapcart mobile components. Broader developer docs: Blocks, Components, Debugging.

Pre-publish checklist

  • Block preview looks correct in local CLI preview and App Studio

  • No hardcoded Admin API tokens or private secrets in code

  • No debug logs that print customer PII

  • Manifest controls work for the settings merchants will edit in the Visual tab

  • New version pushed, reviewed, then set live intentionally

  • Optional soft-launch via display conditions for testers first

Optional: AI-assisted block development

Tapcart publishes agent skills and an MCP server so AI coding tools can help with CLI workflows. See AI Agent Skills and MCP Server. Remote write operations should stay in a reviewable plan mode until a human confirms.

Need help?

Reach out through LiveChat in your Tapcart dashboard or email [email protected].

Related Articles
Did this answer your question?