📘

Note

Components are only supported in @tapcart/tapcart-cli^0.1.10

The Tapcart CLI supports developing reusable chunks of code that can be shared across blocks. Each of these components is another React component that can be embedded across many blocks.

Your application's components will live in your project's components/ directory. Note that the command structure is very similar to the block command - you can just substitute component for block 🎉.

Creating components

Create a new App Studio component:

tapcart component create MyComponent

This will create a new component in the components/ directory.

Component Structure

Because a component is just an embeddable React component, it closely mirrors the structure of a block.

Each component contains these four files:

• code.jsx
  • The source code for your component
• config.json
  • A configuration file for component metadata
  • Supported fields are: label, tags, dependencies
• manifest.json
  • A file to house component 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.

Components read mock data from the single project-root mockData.json — there is no per-component mock data file. This is only read when developing the component in isolation; when bundling components into blocks, the block's variables are used instead. See Blocks for more on mockData.json.

Developing a component

Run a local development server for your component:

tapcart dev component MyComponent

This will start a development server where you can preview and test your component with hot-reloading. 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.

Pulling components

Pull down the latest version of a component from the server:

tapcart component pull ProductCard

You can also pull by component ID (tapcart component pull 507f1f77bcf86cd799439011). Pull a specific version of a component:

tapcart component pull ProductCard --version 2

Pull multiple components:

tapcart component pull ProductCard Button

Pull all components:

tapcart component pull --all

🚧

Warning

The Tapcart CLI does not track any local changes. Pulling a component will overwrite any changes with the currently live version of the component

Pushing components

Push your local code to the server, and store as the latest version:

tapcart component push ProductCard

Add the --live/-l flag when pushing to make it live. Otherwise it's just a draft version on the server:

tapcart component push ProductCard --live

Add a custom update message with --message/-m:

tapcart component push ProductCard -m "Bump default price formatting"

component push also runs a non-blocking ESLint pass over the component(s) first and prints any warnings/errors — it never blocks the push. Pushing live will prompt you to confirm — pass --yes/-y to skip the prompt for non-interactive/CI/agent use.

Push multiple components:

tapcart component push ProductCard Button

Push all components:

tapcart component push --all

Component Versioning

List all versions of a component:

tapcart component versions list MyComponent

This will show your local and remote versions (the versions table is interactive — use ↑/↓ to scroll, PgUp/PgDn to jump a page, q to quit):

% tapcart component versions list MyComponent   
✔ Component versions:
┌─────────┬──────────────────────────┬──────────────┬──────────────┐
│ Version │ ID                       │ LocalVersion │ RemoteVersion│
├─────────┼──────────────────────────┼──────────────┼──────────────┤
│ 1       │ 682e718543b1cca504093661 │ -            │ live         │
│ 2       │ 682e717b15ff420ed63d1de3 │ active       │ -            │
│ 3       │ 682e717243b1cca504093654 │ -            │ -            │
└─────────┴──────────────────────────┴──────────────┴──────────────┘
%

Note components' versions table has no Date Modified/Message columns — those are block-only.

Set a specific version as the active version on the server

tapcart component versions set MyComponent -v 2

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