PepperXGrid

The official frontend counterpart for QueryForge.

Part of the PepperX ecosystem — high-performance, enterprise-grade engines and tools for the .NET & JS ecosystems.

A framework-agnostic data grid core — with a fluent query builder, a typed Query / QueryResult<T> contract, and first-class React bindings today (Vue and Angular next). Point it at any backend that returns a compatible QueryResult<T> shape, or connect it to QueryForge with zero extra config via @pepperx/pepperxgrid-adapter-queryforge.

Product	Layer	Status
QueryForge	Backend (.NET / Dapper)	✅ Released
PepperXGrid	Frontend (JS/TS core, React, Vue, Angular)	🔧 In development

Why PepperXGrid

• 🧩 Framework-agnostic core. @pepperx/pepperxgrid-core owns the wire contract and a fluent query builder — no rendering opinions, no framework lock-in. @pepperx/pepperxgrid-react is a thin binding on top of it.
• 🔌 Zero-config QueryForge pairing. Point @pepperx/pepperxgrid-adapter-queryforge at any PepperX.QueryForge.Dapper endpoint and it just works — same vocabulary as the C# DapperQueryBuilder, so switching between backend and frontend code feels familiar.
• 🛡️ Contract-verified against the QueryForge source. Every enum and every response shape in core was checked directly against PepperX.QueryForge's C# models — including edge cases like numeric enum serialization and how grouped vs. flat results are shaped on the wire.
• 🪶 Small and dependency-light. ESM + CJS builds, full type declarations, tree-shakeable (sideEffects: false).

Packages

Package	Version	Description
@pepperx/pepperxgrid-core		Query/QueryResult contract, fluent QueryForgeBuilder, transport layer
@pepperx/pepperxgrid-react		React bindings — useGrid hook and <PepperXGrid /> component
@pepperx/pepperxgrid-adapter-queryforge		Zero-config data source for PepperX.QueryForge.Dapper endpoints

packages/
  core/                       @pepperx/pepperxgrid-core
  adapters/
    queryforge/               @pepperx/pepperxgrid-adapter-queryforge
  react/                      @pepperx/pepperxgrid-react
  # vue/, angular/            (coming next)
apps/
  demo/                       Vite + React demo — runs on an in-memory
                              mock by default, or a real QueryForge
                              backend via VITE_QUERYFORGE_URL (see
                              apps/demo/README.md)

Grid-library adapters for other UI libraries (DevExtreme, AG Grid, Kendo) will live alongside the QueryForge adapter under packages/adapters/, each translating that library's own loadOptions format into a Query.

Quick start

npm install @pepperx/pepperxgrid-core @pepperx/pepperxgrid-react @pepperx/pepperxgrid-adapter-queryforge

import { PepperXGrid, type ColumnDef } from '@pepperx/pepperxgrid-react';
import { queryForgeSource } from '@pepperx/pepperxgrid-adapter-queryforge';
import '@pepperx/pepperxgrid-react/styles.css';

interface User {
  userId: number;
  firstName: string;
  lastName: string;
  score: number;
}

const columns: ColumnDef<User>[] = [
  { field: 'firstName', headerName: 'First name', width: 140 },
  { field: 'lastName', headerName: 'Last name', width: 140 },
  { field: 'score', headerName: 'Score', width: 100 },
];

export function UsersGrid() {
  return (
    <PepperXGrid<User>
      dataSource={queryForgeSource({ url: '/api/users/query' })}
      columns={columns}
      rowKey={(row) => row.userId}
      defaultPageSize={10}
    />
  );
}

<PepperXGrid /> handles paging, sorting, and per-column filtering out of the box, driving them through @pepperx/pepperxgrid-core's QueryForgeBuilder under the hood. Prefer to own your own UI? Use the lower-level useGrid hook directly:

import { useGrid } from '@pepperx/pepperxgrid-react';
import { queryForgeSource } from '@pepperx/pepperxgrid-adapter-queryforge';
import { QueryForgeBuilder, SortOrder } from '@pepperx/pepperxgrid-core';

const source = queryForgeSource({ url: '/api/users/query' });
const { data, loading, error, run } = useGrid<User>(source);

run(
  QueryForgeBuilder.new()
    .sort({ columnName: 'score', sortOrder: SortOrder.Descending })
    .page(10, 1)
    .build(),
);

Any backend — not just QueryForge — works as a data source, as long as it implements:

interface PepperXGridDataSource {
  load<T>(query: Query): Promise<QueryResult<T>>;
}

Local development

pnpm install
pnpm build   # builds core → adapters/react in dependency order (via turbo)
pnpm test

Try the demo app (runs on an in-memory mock with no backend required):

pnpm build
cd apps/demo
pnpm dev

See apps/demo/README.md to point it at a real QueryForge backend instead.

Releasing

Versioning and npm publishing are automated with Changesets via GitHub Actions — see .github/workflows/release.yml. Contributors add a changeset per change (pnpm changeset); merging to main opens or updates a "Version Packages" PR, and merging that PR publishes to npm and cuts a GitHub Release automatically.

Status

Early stage. core, react, and the QueryForge adapter are functional with passing tests and a working demo against a live QueryForge.Dapper endpoint. Vue and Angular bindings, plus additional grid-library adapters (DevExtreme, AG Grid, Kendo), are next on the roadmap.

Found a bug or have an idea? Open an issue — we read all of them.

License

MIT © PepperX-Dev