Build Your Own Block

This guide shows how to turn Base Kit components into a maintainable, installable, and optionally contributable business block. The running example is an anonymized filter bar with no real APIs, credentials, private URLs, or internal ticket IDs.

Installable Blocks

REGISTRY BLOCKS

See the interface, then generate the source

Every card comes from a real mini-program Block: Headless owns state and interaction, while the Base Kit owns visuals. Review the interface, then copy one command to generate the source and recursive dependencies.

13 BLOCKS

Showing 13 BlocksPreviews are captured from the running Weapp surface

WeappH5

login-form

Login Form

business

Phone, password, remember, error, and loading states.

Weapppnpm dlx @varo-ui/cli add --target weapp blocks/login-form

View code and usageExpand

Generate with one commandRun at the project root. The CLI writes the Block and required component source recursively.

Usage examplesrc/components/blocks/login-form.vue

<script setup lang="ts">
import LoginForm from '@/components/blocks/login-form.vue'

function handleLogin(credentials: unknown) {
  console.log(credentials)
}
</script>

<template>
  <LoginForm @submit="handleLogin" />
</template>

WeappH5

profile-card

Profile Card

business

Avatar, identity status, statistics, and edit action.

Weapppnpm dlx @varo-ui/cli add --target weapp blocks/profile-card

View code and usageExpand

Generate with one commandRun at the project root. The CLI writes the Block and required component source recursively.

Usage examplesrc/components/blocks/profile-card.vue

<script setup lang="ts">
import ProfileCard from '@/components/blocks/profile-card.vue'

const user = { name: 'Varo User', status: 'Active' }
const stats = [{ label: 'Orders', value: 12 }]
function openEditor() {}
</script>

<template>
  <ProfileCard :user="user" :stats="stats" @edit="openEditor" />
</template>

WeappH5

profile-edit

Profile Edit

business

Name, phone, searchable city, biography, and submit state.

Weapppnpm dlx @varo-ui/cli add --target weapp blocks/profile-edit

View code and usageExpand

Generate with one commandRun at the project root. The CLI writes the Block and required component source recursively.

Usage examplesrc/components/blocks/profile-edit.vue

<script setup lang="ts">
import ProfileEdit from '@/components/blocks/profile-edit.vue'

const cities = [{ label: '杭州', value: 'hangzhou' }]
function saveProfile(profile: unknown) {
  console.log(profile)
}
</script>

<template>
  <ProfileEdit :cities="cities" @submit="saveProfile" />
</template>

WeappH5

product-list

Product List

business

Products, inventory, pricing, empty state, selection, and cart actions.

Weapppnpm dlx @varo-ui/cli add --target weapp blocks/product-list

View code and usageExpand

Generate with one commandRun at the project root. The CLI writes the Block and required component source recursively.

Usage examplesrc/components/blocks/product-list.vue

<script setup lang="ts">
import ProductList from '@/components/blocks/product-list.vue'

const products = []
function addToCart(payload: unknown) {
  console.log(payload)
}
</script>

<template>
  <ProductList :items="products" @add-to-cart="addToCart" />
</template>

WeappH5

order-filter

Order Filter

business

Status selection, amount validation, reset, and apply events.

Weapppnpm dlx @varo-ui/cli add --target weapp blocks/order-filter

View code and usageExpand

Generate with one commandRun at the project root. The CLI writes the Block and required component source recursively.

Usage examplesrc/components/blocks/order-filter.vue

<script setup lang="ts">
import OrderFilter from '@/components/blocks/order-filter.vue'

function loadOrders(filters: unknown) {
  console.log(filters)
}
</script>

<template>
  <OrderFilter :result-count="128" @apply="loadOrders" />
</template>

WeappH5

agent-chat

Agent Chat

agent

Incremental Markdown, tool state, approvals, and composer.

Weapppnpm dlx @varo-ui/cli add --target weapp blocks/agent-chat

View code and usageExpand

Generate with one commandRun at the project root. The CLI writes the Block and required component source recursively.

Usage examplesrc/components/blocks/agent-chat.vue

<script setup lang="ts">
import AgentChat from '@/components/blocks/agent-chat.vue'

const messages = [{ id: 'welcome', role: 'assistant', content: '你好' }]
function runAgent(prompt: string) {
  console.log(prompt)
}
</script>

<template>
  <AgentChat :messages="messages" @submit="runAgent" />
</template>

Weapp

retail-home

Retail Home

retail

Search, categories, featured products, and cart entry.

Weapppnpm dlx @varo-ui/cli add --target weapp blocks/retail-home

View code and usageExpand

Generate with one commandRun at the project root. The CLI writes the Block and required component source recursively.

Usage examplesrc/components/blocks/retail-home.vue

<script setup lang="ts">
import RetailHome from '@/components/blocks/retail-home.vue'

const categories = []
const products = []
</script>

<template>
  <RetailHome :categories="categories" :products="products" />
</template>

Weapp

retail-category

Retail Category

retail

Two-column category navigation, product grid, and cart actions.

Weapppnpm dlx @varo-ui/cli add --target weapp blocks/retail-category

View code and usageExpand

Generate with one commandRun at the project root. The CLI writes the Block and required component source recursively.

Usage examplesrc/components/blocks/retail-category.vue

<script setup lang="ts">
import { shallowRef } from 'wevu'
import RetailCategory from '@/components/blocks/retail-category.vue'

const activeId = shallowRef('women')
const categories = []
const products = []
</script>

<template>
  <RetailCategory v-model:active-id="activeId" :categories="categories" :products="products" />
</template>

Weapp

retail-cart

Retail Cart

retail

Selection, quantity, totals, empty state, and checkout.

Weapppnpm dlx @varo-ui/cli add --target weapp blocks/retail-cart

View code and usageExpand

Generate with one commandRun at the project root. The CLI writes the Block and required component source recursively.

Usage examplesrc/components/blocks/retail-cart.vue

<script setup lang="ts">
import RetailCart from '@/components/blocks/retail-cart.vue'

const cartItems = []
const total = 0
function checkout() {}
</script>

<template>
  <RetailCart :items="cartItems" :total="total" @checkout="checkout" />
</template>

Product Detail Block interface screenshot

Weapp

retail-product-detail

Product Detail

retail

Product image, pricing, stock, quantity, cart, and buy actions.

Weapppnpm dlx @varo-ui/cli add --target weapp blocks/retail-product-detail

View code and usageExpand

Generate with one commandRun at the project root. The CLI writes the Block and required component source recursively.

Usage examplesrc/components/blocks/retail-product-detail.vue

<script setup lang="ts">
import { shallowRef } from 'wevu'
import RetailProductDetail from '@/components/blocks/retail-product-detail.vue'

const quantity = shallowRef(1)
const product = {}
</script>

<template>
  <RetailProductDetail v-model:quantity="quantity" :product="product" />
</template>

Weapp

retail-checkout

Retail Checkout

retail

Address, products, coupons, invoice, totals, and order submission.

Weapppnpm dlx @varo-ui/cli add --target weapp blocks/retail-checkout

View code and usageExpand

Generate with one commandRun at the project root. The CLI writes the Block and required component source recursively.

Usage examplesrc/components/blocks/retail-checkout.vue

<script setup lang="ts">
import RetailCheckout from '@/components/blocks/retail-checkout.vue'

const address = {}
const items = []
const total = 0
function submitOrder() {}
</script>

<template>
  <RetailCheckout :address="address" :items="items" :total="total" @submit="submitOrder" />
</template>

Weapp

retail-order-list

Retail Order List

retail

Order status, product summaries, and fulfillment actions.

Weapppnpm dlx @varo-ui/cli add --target weapp blocks/retail-order-list

View code and usageExpand

Generate with one commandRun at the project root. The CLI writes the Block and required component source recursively.

Usage examplesrc/components/blocks/retail-order-list.vue

<script setup lang="ts">
import RetailOrderList from '@/components/blocks/retail-order-list.vue'

const orders = []
function handleOrder(order: unknown) {
  console.log(order)
}
</script>

<template>
  <RetailOrderList :orders="orders" @action="handleOrder" />
</template>

Weapp

retail-profile

Retail Profile

retail

Membership, orders, addresses, coupons, and service entry.

Weapppnpm dlx @varo-ui/cli add --target weapp blocks/retail-profile

View code and usageExpand

Generate with one commandRun at the project root. The CLI writes the Block and required component source recursively.

Usage examplesrc/components/blocks/retail-profile.vue

<script setup lang="ts">
import RetailProfile from '@/components/blocks/retail-profile.vue'

const orderCounts = {}
</script>

<template>
  <RetailProfile name="Varo User" :points="2680" :order-counts="orderCounts" />
</template>

1. Understand the layers

Layer	Owns	Does not own
Primitives	State, events, parts, cross-runtime semantics	Visual tokens, product copy
Base Kit / UI	Copied low-level component source and default styles	Remote data, permissions, domain models
Business wrappers	APIs, authz, field mapping, product copy	Generic interaction state machines
Blocks	Reusable screen sections and local composition	Private backend details, one-off page glue

Rule of thumb: a block should feel like a portable page slice, not a page locked to one product API.

2. Define the block contract

Write the contract before the implementation:

// Example contract for a local filter block
export interface StatusOption {
  label: string
  value: string
  disabled?: boolean
}

export interface FilterBarProps {
  /** Status options injected by the product layer */
  options: StatusOption[]
  /** Controlled selected values */
  modelValue?: string[]
  /** Disabled state */
  disabled?: boolean
}

export interface FilterBarEmits {
  (e: 'update:modelValue', value: string[]): void
  (e: 'change', value: string[]): void
}

Capture:

Inputs: options, defaults, disabled
Outputs: update:modelValue / change
Local state: UI-only temporary state
Dependencies: Base Kit component names such as select
Exclusions: remote dictionaries, auth, analytics SDKs, private domains

3. Choose Base Kit dependencies

Prefer dependencies from the app tree:

text

src/components/ui/*

Do not import registry source paths directly from the block. Keep remote data and product policy in business wrappers.

Install the base component:

bash

pnpm dlx @varo-ui/cli add --target weapp components/select

4. Create the local block

Recommended path:

text

src/components/blocks/status-filter.vue

Minimal implementation:

vue

<script setup lang="ts">
import { computed } from 'vue'
import { VSelect } from '../ui/select'

export interface StatusOption {
  label: string
  value: string
  disabled?: boolean
}

const props = withDefaults(
  defineProps<{
    options: StatusOption[]
    modelValue?: string[]
    disabled?: boolean
    placeholder?: string
  }>(),
  {
    modelValue: () => [],
    disabled: false,
    placeholder: 'Select statuses'
  }
)

const emit = defineEmits<{
  'update:modelValue': [value: string[]]
  'change': [value: string[]]
}>()

const value = computed({
  get: () => props.modelValue,
  set: (next) => {
    const normalized = next ?? []
    emit('update:modelValue', normalized)
    emit('change', normalized)
  }
})
</script>

<template>
  <section class="status-filter">
    <header class="status-filter__head">
      <strong>Status filter</strong>
      <span>{{ value.length }} selected</span>
    </header>
    <VSelect
      v-model:value="value"
      multiple
      :disabled="disabled"
      :options="options"
      :placeholder="placeholder"
    />
  </section>
</template>

Requirements:

typed props and emits
small, readable layout
no hard-coded product APIs

5. Test the block

Cover at least:

initial render
emitted values after interaction
disabled behavior
dependency boundaries (no network, no private env reads)

import { mount } from '@vue/test-utils'
import { describe, expect, it } from 'vitest'
import StatusFilter from '../status-filter.vue'

describe('StatusFilter', () => {
  it('keeps selected statuses under product control', async () => {
    const wrapper = mount(StatusFilter, {
      props: {
        options: [
          { label: 'Pending', value: 'pending' },
          { label: 'Done', value: 'done' }
        ],
        modelValue: []
      }
    })

    await wrapper.setProps({ modelValue: ['pending'] })
    expect(wrapper.props('modelValue')).toEqual(['pending'])
  })
})

6. Use and maintain it locally

vue

<script setup lang="ts">
import { ref } from 'vue'
import StatusFilter from '@/components/blocks/status-filter.vue'

const statuses = ref<string[]>([])
const options = [
  { label: 'Pending', value: 'pending' },
  { label: 'Done', value: 'done' }
]
</script>

<template>
  <StatusFilter v-model="statuses" :options="options" />
</template>

Copied source belongs to the application team. You can change layout, tokens, and interaction without contributing those product decisions back to Varo.

7. Prepare registry metadata

To make the block installable through the CLI:

text

registry/blocks/status-filter/registry.json
registry/blocks/status-filter/status-filter.vue

Example registry.json:

json

{
  "name": "status-filter",
  "type": "block",
  "title": "Status Filter",
  "description": "A local filter bar for selecting multiple anonymized statuses with VSelect.",
  "targets": ["weapp"],
  "dependencies": ["vue"],
  "registryDependencies": ["components/select"],
  "files": [
    {
      "target": "weapp",
      "from": "registry/blocks/status-filter/status-filter.vue",
      "to": "src/components/blocks/status-filter.vue"
    }
  ],
  "docs": "/blocks/status-filter"
}

Key fields:

type: block
targets: for example weapp
registryDependencies: recursive base components
files: from/to mappings
docs: documentation route

8. Add bilingual documentation

Every public block should document:

purpose
dependencies
target
installed file destination
customization boundary / excluded business logic

Existing examples:

9. Verify installation

Suggested checklist:

bash

# types and tests
pnpm typecheck
pnpm test

# pack the CLI and install into a temporary fixture
pnpm --filter @varo-ui/cli build
pnpm dlx @varo-ui/cli add --target weapp blocks/status-filter

Confirm:

dependency components install recursively
existing destinations are not clobbered by default
overwrite requires an explicit force path
installed files contain no private domains, tokens, or internal IDs

10. Contribute to Varo

Privacy and portability checklist:

no real APIs / credentials / private URLs
no internal ticket IDs, customer names, or private domain models
registryDependencies are complete and correctly spelled
bilingual docs exist
unit tests cover the main path
packed CLI installation passes

A contribution usually includes source, registry.json, tests, and bilingual docs.

Troubleshooting

Symptom	Fix
Missing dependency install	Check `registryDependencies` spelling such as `components/select`
Destination conflict	Review the `to` path; default is no-clobber, force only when explicit
Hard to reuse	Move remote data/auth/analytics into a business wrapper
Breaks on mini-program	Remove H5-only APIs and keep the shared contract
Unit tests pass but install fails	Reproduce with packed CLI + temp fixture; verify file mappings

Install existing blocks

bash

pnpm dlx @varo-ui/cli add --target weapp blocks/profile-edit
pnpm dlx @varo-ui/cli add --target weapp blocks/order-filter

After install:

text

src/components/ui/*        # base component source
src/components/blocks/*    # block source
src/components/biz/*       # recommended home for product wrappers

Build Your Own Block ​

Installable Blocks ​

1. Understand the layers ​

2. Define the block contract ​

3. Choose Base Kit dependencies ​

4. Create the local block ​

5. Test the block ​

6. Use and maintain it locally ​

7. Prepare registry metadata ​

8. Add bilingual documentation ​

9. Verify installation ​

10. Contribute to Varo ​

Troubleshooting ​

Install existing blocks ​

Related docs ​

Build Your Own Block

Installable Blocks

1. Understand the layers

2. Define the block contract

3. Choose Base Kit dependencies

4. Create the local block

5. Test the block

6. Use and maintain it locally

7. Prepare registry metadata

8. Add bilingual documentation

9. Verify installation

10. Contribute to Varo

Troubleshooting

Install existing blocks

Related docs