Get Started

Filter API

Typed filter architecture used to compose kit features into apps with high modularity.

What It Does

The Filter API is the composition layer between reusable packages (kit/*) and app runtime wiring (apps/*).

Instead of hardcoding integrations inside each app, packages enqueue typed filter callbacks and apps initialize them at stable entrypoints.

Why It Matters

Keeps package logic modular and reusable.
Lets apps add/remove behavior by initialization wiring, not by forking package code.
Gives AI and humans a deterministic integration contract (FilterList + init files).

Source of Truth

All filter names, parameters, and return types are declared in kit/utils/src/filters/list.ts.

Core Model

Concept	Purpose	Source
`FilterList`	Typed contract for all filter slugs, params, and return values	`kit/utils/src/filters/list.ts`
`FilterEngine`	Runtime add/remove/apply + priority ordering	`kit/utils/src/filters/filter-engine.ts`
Filter callback	`(value, options) => nextValue`	`FilterCallback` / `AsyncFilterCallback`
Priority	Lower values run earlier	`priority` on enqueue object

Environments and APIs

Environment	API	Typical usage
Client (web/mobile)	`@kit/utils/filters`	UI composition, provider wrappers, page-level runtime behavior
Server	`@kit/utils/filters/server`	settings schema/provider registration, redirect logic, server query constraints
Cross-env	`@kit/utils/filters/cross-env`	package translation namespaces and translation dictionary resolution

Initialization Entry Points

How To Add a New Filter

Declare the typed filter contract.

Add your slug in FilterList with explicit params and return type.

kit/utils/src/filters/list.ts

your_new_filter: {
  myParam: string;
  return: string[];
};

Register/enqueue from a package filter module.

useEnqueueFilter('your_new_filter', {
  name: 'myFilterRegistration',
  fn: (value, { myParam }) => [...value, myParam],
});

For server or cross-env filters, use enqueueServerFilter or enqueueCrossEnvFilter.

Initialize in app entrypoints.

Client hooks in hooks/use-filters.ts
Server wiring in lib/init-server-filters.ts
Cross-env wiring in lib/init-cross-env-filters.ts
i18n resolver usage in config/i18n.config.ts (applyCrossEnv*)

Consume the filter.

Client: useApplyFilter, applyFilter, applyAsyncFilter
Server: applyServerFilter, applyServerAsyncFilter
Cross-env: applyCrossEnvFilter, applyCrossEnvAsyncFilter

MCP Context


capability: filter_api_architecture
entrypoints:
  - kit/utils/src/filters/list.ts
  - kit/utils/src/filters/filter-engine.ts
  - kit/utils/src/filters/client/use-filters.tsx
  - kit/utils/src/filters/server.ts
  - kit/utils/src/filters/cross-env.ts
  - apps/dashboard/hooks/use-filters.ts
  - apps/dashboard/lib/init-server-filters.ts
  - apps/dashboard/lib/init-cross-env-filters.ts
  - apps/dashboard/config/i18n.config.ts
  - apps/mobile/hooks/use-filters.ts
  - apps/mobile/config/i18n.config.ts
inputs:
  - target_feature_behavior
  - filter_namespace
outputs:
  - typed_filter_registration_and_app_wiring
constraints:
  - filter slug/params/return must match FilterList
  - app init entrypoints must enqueue required package filters
side_effects:
  - runtime behavior is composed from package filters at app boot time

Agent Recipe

Identify filter namespace (client, server, cross-env) before editing code.
Confirm typed signature in FilterList.
Register filter in package module and initialize it in app entrypoints.
Verify consumption path (useApplyFilter / applyServerFilter / applyCrossEnv*).
Update feature docs with filter parameters when the integration changes.

Troubleshooting

Behavior missing in one app usually means missing filter initialization in that app’s init files.
Wrong execution order means priorities are conflicting.
Filter not called often means slug mismatch between enqueue and apply calls.

Configuration

Core config files that control behavior across the web apps.

Scripts

Root-level commands you will run every day.

How is this guide?

Last updated on 3/27/2026