Frontend development in TypeScript for 1C-Bitrix

Frontend Development with TypeScript for 1C-Bitrix

The gap between the 1C-Bitrix PHP backend and a vanilla JavaScript frontend is a familiar story. Catalog components, shopping cart, filters, user account — each of these entities lives at the intersection of PHP logic and client-side code. TypeScript closes the gaps at this boundary: the contract between PHP and JS is described in types, and the compiler catches mismatches before deployment.

Frontend Development with TypeScript for 1C-Bitrix

Frontend architecture of a 1C-Bitrix project

Two polar approaches to 1C-Bitrix frontend:

1. MPA (Multi-Page Application) — the classic approach. PHP renders pages; TypeScript adds interactivity: AJAX filters, REST-based cart, galleries, maps. Each component is a separate isolated TS module.

2. SPA/Headless — React or Vue on TypeScript consumes 1C-Bitrix as an API. The entire frontend is written in TypeScript; PHP provides only data and business logic.

Most projects use the first approach with elements of the second in critical sections (catalog, cart).

Frontend structure in a 1C-Bitrix template

/local/templates/my_site/
├── src/
│   ├── components/
│   │   ├── catalog/
│   │   │   ├── CatalogFilter.ts
│   │   │   ├── ProductCard.ts
│   │   │   └── CartButton.ts
│   │   ├── cart/
│   │   │   ├── CartDrawer.ts
│   │   │   └── CartCounter.ts
│   │   └── common/
│   │       ├── Modal.ts
│   │       └── Tooltip.ts
│   ├── api/
│   │   ├── catalog.ts
│   │   ├── cart.ts
│   │   └── user.ts
│   ├── types/
│   │   ├── bitrix.d.ts
│   │   └── api.ts
│   ├── utils/
│   │   ├── http.ts
│   │   └── format.ts
│   └── main.ts
├── dist/
├── package.json
├── tsconfig.json
└── vite.config.ts

Cart component in TypeScript

A complete cart component example with types:

// api/cart.ts
interface CartItem {
    id:       number;
    name:     string;
    price:    number;
    quantity: number;
    img:      string | null;
}

interface CartState {
    items:      CartItem[];
    totalPrice: number;
    totalCount: number;
    currency:   string;
}

interface AddToCartPayload {
    productId: number;
    quantity:  number;
    properties?: Record<string, string>;
}

export async function addToCart(payload: AddToCartPayload): Promise<CartState> {
    const formData = new FormData();
    formData.append('sessid',     BX.bitrix_sessid());
    formData.append('action',     'addItem');
    formData.append('product_id', String(payload.productId));
    formData.append('quantity',   String(payload.quantity));

    if (payload.properties) {
        Object.entries(payload.properties).forEach(([k, v]) => {
            formData.append(`props[${k}]`, v);
        });
    }

    const res = await fetch('/local/ajax/cart.php', {
        method: 'POST',
        body:   formData,
    });

    if (!res.ok) throw new Error(`Cart error: ${res.status}`);

    const json = await res.json();
    if (json.status !== 'success') throw new Error(json.error ?? 'Cart error');

    return json.cart as CartState;
}

// components/cart/CartButton.ts
import { addToCart }   from '@/api/cart';
import { updateCartUI } from './CartCounter';

export function initAddToCartButtons(): void {
    document.querySelectorAll<HTMLButtonElement>('[data-action="add-to-cart"]')
        .forEach(btn => btn.addEventListener('click', handleAddToCart));
}

async function handleAddToCart(e: MouseEvent): Promise<void> {
    const btn = e.currentTarget as HTMLButtonElement;
    const productId = Number(btn.dataset['productId']);
    if (!productId) return;

    btn.disabled = true;
    btn.classList.add('loading');

    try {
        const cart = await addToCart({ productId, quantity: 1 });
        updateCartUI(cart.totalCount, cart.totalPrice);
        showAddedFeedback(btn);
    } catch (err) {
        console.error('Add to cart failed:', err);
        showError(btn);
    } finally {
        btn.disabled = false;
        btn.classList.remove('loading');
    }
}

Integration with PHP components via data attributes

Passing data from PHP to TypeScript without global variables:

// template.php of the catalog component
<div
    id="catalog-app"
    data-section-id="<?= (int)$arResult['SECTION']['ID'] ?>"
    data-iblock-id="<?= (int)$arParams['IBLOCK_ID'] ?>"
    data-initial-filter='<?= htmlspecialchars(
        json_encode($arResult['FILTER_PARAMS']), ENT_QUOTES
    ) ?>'
>
    <?php // SSR markup for initial load ?>
</div>

// TypeScript reads data in a typed way
const appEl = document.getElementById('catalog-app');
if (!appEl) throw new Error('#catalog-app not found');

const sectionId  = Number(appEl.dataset['sectionId']);
const iblockId   = Number(appEl.dataset['iblockId']);
const rawFilter  = appEl.dataset['initialFilter'] ?? '{}';
const initFilter = JSON.parse(rawFilter) as FilterState;

State management without React: EventEmitter pattern

For MPA projects, React is not always necessary. A lightweight EventEmitter synchronizes components:

// utils/EventBus.ts
type Handler<T> = (payload: T) => void;

class EventBus {
    private handlers: Map<string, Handler<unknown>[]> = new Map();

    on<T>(event: string, handler: Handler<T>): void {
        const list = this.handlers.get(event) ?? [];
        list.push(handler as Handler<unknown>);
        this.handlers.set(event, list);
    }

    emit<T>(event: string, payload: T): void {
        this.handlers.get(event)?.forEach(h => h(payload as unknown));
    }
}

export const bus = new EventBus();

// Usage: cart notifies the header
bus.emit<CartState>('cart:updated', newCartState);
bus.on<CartState>('cart:updated', (cart) => {
    updateCartCounter(cart.totalCount);
});

Build and deployment

// vite.config.ts
import { defineConfig } from 'vite';

export default defineConfig({
    root:  'src',
    build: {
        outDir:          '../dist',
        emptyOutDir:     true,
        rollupOptions: {
            input: {
                main:    'src/main.ts',
                catalog: 'src/pages/catalog.ts',
                cart:    'src/pages/cart.ts',
            },
        },
    },
    resolve: {
        alias: { '@': '/src' },
    },
});

Separate entrypoints for each site section — only the required JS loads on each page.

Timelines