@vkma.dev/router
v0.2.0
Published
VK Mini Apps router on top of TanStack Router — VKUI views/panels/modals/popouts, VK history and bridge sync
Readme
@vkma.dev/router
A VK Mini Apps router on top of TanStack Router. Views, panels, modals and popouts are URL-driven and rendered by @vkontakte/vkui hosts, with typed handles instead of string ids, VK history and host sync (VKWebAppSetLocation, VKWebAppChangeFragment), and native swipe-back management. Feature parity with @vkontakte/vk-mini-apps-router, not API parity. The migration guide maps the old API to the new one.
Docs: https://vkma.dev/router
Install
npm install @vkma.dev/router @tanstack/react-router
# or: pnpm add / yarn add / bun add
# peers: @tanstack/react-router ^1.170, @vkontakte/vkui ^8 (optional), react ^18 | ^19Use
Declare a view hub, its panels and overlays, then mount the router:
// panels/profile/profile.panel.ts, the one place the "profile" view key is written
import { defineView } from "@vkma.dev/router/preset";
export const profileView = defineView("profile");
// "index" owns "/", "$id" declares a typed path param
export const profilePanel = profileView.panel("index", {}, () => import("./profile.ui"));
export const profileSettingsPanel = profileView.panel(
"settings",
{
// loaders run before the panel mounts; read them with usePanelLoaderData(profilePanel)
loader: async () => ({ user: await bridge.send("VKWebAppGetUserInfo") }),
},
() => import("./profile.ui"),
);import { createRouter } from "@tanstack/react-router";
// app.tsx, the app tree + the router
import { createApp, AppRootShell } from "@vkma.dev/router/preset";
export const app = createApp({
root: AppRootShell, // or your own shell (Epic/Tabbar, SplitCol sidebar…)
views: [profileView /* … */],
modals: {/* keyed entries */},
popouts: {/* keyed entries */},
});
export const router = createRouter({
routeTree: app.routeTree,
history: createVkHistory({ mode: "hash" }).history, // or "hash-param"
defaultNotFoundComponent: NotFound,
});
declare module "@tanstack/react-router" {
interface Register {
router: typeof router;
}
}// main.tsx, mount + the host contract
import bridge from "@vkma.dev/bridge";
import { createBridgeSync, createSwipeBackManager } from "@vkma.dev/router";
void bridge.send("VKWebAppInit");
createBridgeSync({ history: router.history, bridge });
createSwipeBackManager({ history: router.history, bridge });
createRoot(document.getElementById("root")!).render(
<StrictMode>
<RouterProvider router={router} />
</StrictMode>,
);In components, navigate with typed handles, for example const navigator = useNavigator(); navigator.push(profileSettingsPanel). Render router links out of any component with createVkLink(TabbarItem).
Entry points
| Import | Surface |
| ------------------------- | --------------------------------------------------------------------------------------------------------------------- |
| @vkma.dev/router | core: createVkHistory, panels-stack helpers, createBridgeSync, createSwipeBackManager |
| @vkma.dev/router/react | data hooks (usePanelParams, usePanelSearch, usePanelLoaderData with departing-panel freeze, usePanelsHistory) |
| @vkma.dev/router/vkui | VKUI hosts: VkView, Modals, Popouts, NotFound |
| @vkma.dev/router/preset | the createApp builders + sugar: AppRootShell, useActiveStory, useNavigator, createVkLink, useInflate |
Decisions and design
DESIGN.md in the repo is the source of truth for every decision (the URL/history model, the VkView static-children world, overlay choreography, the v1 scope), with spike verdicts and implementation notes. The package AGENTS.md is the contributor entry.
License
MIT.
