rustams/develop-b24-frontend

Develop Битрикс24 Frontend

Design & UI: B24 Libraries Only

ALWAYS use B24 UI Kit (@bitrix24/b24ui-nuxt) and b24icons (@bitrix24/b24icons-vue) for all design, layout, styling, and UI components. Do NOT use Nuxt UI, Tailwind UI, custom design systems, or other component libraries — even when the task says "improve design" or "make it prettier". B24 components ensure consistency with the Битрикс24 portal and correct iframe behavior.

Quick Start

The frontend is built with Nuxt 3 and uses @bitrix24/b24ui-nuxt (UI Kit) and @bitrix24/b24jssdk-nuxt (JS SDK).

Key Directories

• frontend/app/pages/: Application pages (must end with .client.vue for client-side rendering).
• frontend/app/components/: Reusable components.
• frontend/app/stores/: Pinia stores for state management.
• frontend/app/composables/: Shared logic (e.g., useApiStore, useAppInit, useSetupHelpers).

Битрикс24 UI Kit

ALWAYS use B24 prefixed components from @bitrix24/b24ui-nuxt. Do NOT use standard HTML elements or other UI libraries if a B24 component exists.

Common Components

<template>
  <B24App> <!-- Mandatory wrapper -->
    <B24Card>
      <template #header>
        <h3 class="text-lg font-semibold">Title</h3>
      </template>
      
      <B24Form :state="state" @submit="onSubmit">
        <B24FormField label="Name" name="name" required>
          <B24Input v-model="state.name" />
        </B24FormField>
        
        <B24Button type="submit" color="air-primary" :loading="isLoading">
          Save
        </B24Button>
      </B24Form>
    </B24Card>
  </B24App>
</template>

• Buttons: <B24Button color="air-primary" />
• Inputs: <B24Input />, <B24Select />, <B24Textarea />
• Layout: <B24Card>, <B24Container>, <B24SidebarLayout>
• Feedback: <B24Toast /> (use useToast()), <B24Modal />, <B24Alert />

Битрикс24 JS SDK

Use the SDK to interact with Битрикс24.

Initialization

// In a component or composable
const { $initializeB24Frame } = useNuxtApp()
const $b24 = await $initializeB24Frame()

API Calls

// Single method
const result = await $b24.callMethod('crm.deal.get', { id: 123 })

// Batch method
const batch = await $b24.callBatch({
  deals: { method: 'crm.deal.list', params: { select: ['ID', 'TITLE'] } },
  users: { method: 'user.get', params: { ID: 1 } }
})
const data = batch.getData()

UI Interaction

// Open slider
const url = $b24.slider.getUrl('/crm/deal/details/123/')
await $b24.slider.openPath(url)

// Select user
const user = await $b24.dialog.selectUser()

State Management (Pinia)

Use stores for API interaction and global state.

// stores/api.ts
const apiStore = useApiStore()
await apiStore.init($b24) // Initialize with B24 frame
const data = await apiStore.getList() // Call backend API

Backend Interaction

• Frontend -> Backend: Use $api (wrapper around $fetch with JWT).
• Authentication: Handled automatically by apiStore and useAppInit.
• Base URL: Proxied in dev, relative in prod.

Setup: media template / full update (stages)

If full update of the media template succeeds on a second run but custom stages (e.g. MEDIA_EXPIRING) are missing or warnings appear on the first run on a new smart process, treat this as a backend CRM stage sync issue, not a missing frontend snapshot. Typical Bitrix message (RU): cannot create an intermediate stage after a successful one — caused by SORT of template intermediates vs portal SUCCESS/FAIL SORT, fixed in Python (media_template_apply._apply_stages clamp). See develop-b24-python skill section CRM smart-process stages (media template installer) for cause, code locations, tests, and Docker logging notes. When investigating, use API response warnings / backend logs rather than guessing empty template data in the UI alone.

Best Practices

1. Client-only: All pages must be .client.vue as the app runs in an iframe.
2. B24App: Always wrap the root of your page/layout in <B24App>.
3. Error Handling: Use try/catch and useToast() to show errors.
4. Icons: Import from @bitrix24/b24icons-vue.