@victorylabs/kit

Opinionated distribution layer for the @victorylabs/* framework. Composes plugins via defineApp(), builds HTTP clients via defineClient(), authors scaffolds via defineScaffold(), and enforces a shared Biome config.

If you're building an app, start here. defineApp() accepts a tuple of withXModule(...) factories and returns a typed App<TModules> surface — app.<module>.<member> exposes each composed module's hooks and callables.

Install

pnpm add @victorylabs/kit

Quick start

import { defineApp } from '@victorylabs/kit'
import { withAuthModule } from '@victorylabs/kit/auth'
import { withNotificationModule } from '@victorylabs/kit/notification'
import { withRouterModule } from '@victorylabs/kit/router'
import { withThemeModule } from '@victorylabs/kit/theme'
import { withTokenModule } from '@victorylabs/kit/token'
import { withUserModule } from '@victorylabs/kit/user'

import { App } from './App'
import { routes } from './routes'

export const app = defineApp({
  target: '#app',
  root: <App />,
  modules: [
    withTokenModule(),
    withUserModule(),
    withRouterModule({ routes }),
    withThemeModule({ defaultMode: 'system' }),
    withNotificationModule({ autoDismissMs: 3000 }),
    withAuthModule({ strategy: myAuthStrategy }),
  ],
})

await app.bootstrap()

// Optional ergonomic single-liners — extract once for frequent callables:
export const { notify } = app.notification
export const { useAuth } = app.auth

Each withXModule(...) factory is the only static-import edge for its plugin class — modules you don't compose never enter the bundle. Skip a module by simply leaving it out of the tuple.

Modules vs. plugins

• modules: [withXModule(...)] — kit's first-class domains (auth, router, theme, …). Each contributes a typed leaf to app.<module>.<member>.
• plugins: readonly Plugin[] — consumer-authored plugins. Registered on Core, NOT on the typed app.<module> surface. Reach via custom hooks you author or app.core.get(MyPluginToken).

Key exports

• defineApp(options) — composes an App<TModules> from a modules tuple plus an optional plugins array. Registers MountReactPlugin last so React-provider contributions are collected before mount.
• defineClient(options) — opinionated wrapper over FetchPlugin.createClient. Combines withAuth() + withErrorToast() with your custom middleware.
• defineScaffold(scaffold) — typed identity helper for authoring scaffolds consumed by @victorylabs/cli.
• KitModule, MODULE_BRAND, getActiveCore, resetActiveCore — public extension points for authoring custom-domain withXModule factories.

Subpath re-exports

Every kit module has a subpath export (@victorylabs/kit/<plugin>) that ships the withXModule factory, the underlying plugin class + token, the React companion (where applicable), and helper factories. Hooks (useAuth, useTheme, useNotification, …) live on the typed app.<module> surface — extract them once in your app/core.tsx if you want single-import ergonomics across files.

import { withThemeModule, ThemeMode } from '@victorylabs/kit/theme'
import { withFetchModule, onStatus, onSlow } from '@victorylabs/kit/fetch'
import { withAuthModule, withAuth, jwtStrategy } from '@victorylabs/kit/auth'

Plugin defaults (logger/token/fetch/theme/etc.) are applied inside each withXModule factory. Override by passing options through the factory (withThemeModule({ defaultMode: 'dark' })).

See also

• @victorylabs/core — the plugin primitives kit builds on (auto-installed alongside kit; only declare it directly if you need to import core under a strict-pnpm setup)
• @victorylabs/cli — project scaffolding CLI (consumes kit's scaffolds)