@elcrm/router

React state router для elCRM: глобальное состояние (Router.data), опциональный URL поверх него, ленивая загрузка чанков (import.meta.glob / Vite), шифрованный persist в sessionStorage.

Это не полный аналог React Router: URL — опциональный слой. Есть GuardRoute, RouteLoader, RouterOutletStack, LoadRoute.

Содержание

• Установка
• Быстрый старт
• Router.createRouter — опции
• API состояния
• Типизация
• Загрузка чанков и paths
• URL-router
• Опционально: guard, loader, outlet
• Сессия и шифрование
• Сборка UMD
• Тестовый стенд
• Подробнее про импорт чанков
• Лицензия

Установка

npm install @elcrm/router @elcrm/crypto react

react-dom подключает приложение (тот же major, что у react).

Быстрый старт

Минимум для Vite: glob и createRouter.

import { Router, LoadRoute } from "@elcrm/router";

const glob = import.meta.glob("./{features,pages}/**/*.{tsx,ts,jsx,js}", {
    eager: false,
});

Router.createRouter({
    defaults: {
        page: "Home",
        feature: "Dashboard",
        id: 0,
    },
    auth: "Login",
    glob,
});

export function App() {
    return (
        <LoadRoute variant="page" defaultName="Home">
            <span aria-hidden />
        </LoadRoute>
    );
}

Дальше: Router.useRouter, setRouter, mergeRouter, LoadRoute, RouterOutletStack — см. таблицы ниже.

Идея: после createRouter вызываются восстановление сессии (Load) и при необходимости разбор URL (urlTemplate). useRouter / emitRouter реагируют на обновления data.

Router.createRouter — опции

Все поля опциональны; при повторном вызове подмешиваются значения из текущего конфига.

Сегменты из URL попадают в Router.data как в строке (регистр библиотека не нормализует).

API состояния

Объект Router и одноимённые функции: setRouter, getRouter, mergeRouter, matchesRouter, hasRouter, prevRouter, getRouterData, pickRouter, useRouter, emitRouter, resetRouter, flushPersistToSession, createImportLoader, getImportLoader, requireImportLoader, importFromRouter.

Типизация

Один раз опишите RouterDataMap: ключ = имя сегмента (то же, что variant / stateKey в LoadRoute), тип значения = допустимые значения (страницы, секции, произвольное число для id и т.д.).

declare module "@elcrm/router" {
    interface RouterDataMap {
        page: "login" | "recover" | "passkey" | "main";
        modules:
            | "home"
            | "promotions"
            | "calendar"
            | "telegram"
            | "inn"
            | "requests"
            | "companies"
            | "questions"
            | "analytics"
            | "users"
            | "settings";
        settingsSection: "profile" | "notifications" | "ui" | "security";
        id: number;
    }
}

LoadRoute и paths в createRouter получают проверку variant по ключам этой схемы. Отдельный RouterLoadSegmentKinds не нужен (он только резерв, если RouterDataMap не задаёте — тогда доступны встроенные page | feature).

Кастомные папки для чанков:

Router.createRouter({
    defaults: { page: "main", modules: "home", settingsSection: "profile" },
    paths: {
        page: "./pages",
        modules: "./modules/{segment}/index",
        settingsSection: "./settings/{segment}/index",
    },
    glob,
});

createRouterApi<T>() — типизированный API без глобального augmentation. defineRouterConfig = createRouter.

Загрузка чанков и paths

• LoadRoute: variant задаёт шаблон пути (paths в createRouter; по умолчанию page → pages/{segment}, feature → features/{segment}/index).
• Либо строковый путь + importLoader, либо resolveLazyPage (см. docs/load-route-and-import.md).
• createPageLazyResolverFromImportMeta(import.meta.url, { segmentKind: "page" }) учитывает paths.

Рекомендуется import.meta.glob и поле glob в createRouter. Для корректных относительных импортов из приложения — createImportLoaderFromImportMeta(import.meta.url).

URL-router

Непустой urlTemplate в createRouter включает синхронизацию с history. Утилиты: matchUrlTemplate, buildUrlFromTemplate, syncDataToUrl, applyPathnameToRouterData.

Опционально: guard, loader, outlet

• GuardRoute — условия, редирект, watchKey (см. GuardRouteProps).
• RouteLoader — асинхронные данные в Router.data.
• RouterOutletStack — цепочка LoadRoute по массиву { stateKey, variant }.

Лицензия

MIT — файл LICENSE.

Полный список типов и экспортов — в автодополнении IDE и в dist/*.d.ts после сборки.