How ukrbublik/react-awesome-query-builder works
Project type and purpose
• This is a monorepo library/project built with pnpm workspace.
• It provides a core query-builder engine (packages/core) plus a UI layer (packages/ui) and multiple theme/skin packages (packages/antd, packages/mui, packages/bootstrap, packages/fluent, packages/material).
• It also includes import/export adapters (packages/sql), demo apps (packages/examples, packages/sandbox, packages/sandbox_simple, packages/sandbox_next), test suite (packages/tests), and build/config scripts.
• Purpose: let front-end and back-end teams build, render, import/export, validate complex queries in React and Node.js
File-structure analysis
• Top-level:
• pnpm-workspace.yaml, package.json: define workspace packages
• .github/workflows: CI steps (lint, tests, publishing)
• scripts/: shared helper scripts
• packages/: the monorepo modules
• packages/core: core query-tree logic & import/export/validation utilities (no React)
• packages/ui: core React components (<Query>, <Builder>) and vanilla widgets, CSS
• packages/{antd,mui,bootstrap,fluent,material}: each wraps ui to provide theme-specific widgets/config
• packages/sql: SQL adapter to import/export SQL queries
• packages/tests: Karma/Mocha tests exercising core, ui, themes
• packages/examples & sandboxes: demo apps showing library usage (React, Vite, Next.js)
Key README insights
• Usage patterns: import @react-awesome-query-builder/<skin> in your app
• Core vs UI vs theme separation: server-side only needs core; front-end apps need ui or a specific skin
a. Components:
• Monorepo root (workspace)
• Core package (@react-awesome-query-builder/core)
• UI package (@react-awesome-query-builder/ui)
• Theme packages (AntD, MUI, Bootstrap, Fluent, Material)
• SQL adapter (@react-awesome-query-builder/sql)
• Demo apps
• examples (TS + hot-reload + multi-skin)
• sandbox (Vite, TS, MUI)
• sandbox_simple (Vite, JS, vanilla)
• sandbox_next (Next.js, SSR API)
• Test suite (Karma, specs)
• External services & tools
• pnpm, Babel, TypeScript, Webpack/Vite, Next.js
• GitHub Actions (CI/CD)
• Codecov, CodeSandbox, Codespaces
b. Relationships & interactions:
• Core exports logic & utils → UI imports core
• UI re-exports core, provides React components + CSS
• Each skin package imports from UI and provides themed widgets/config → re-exports UI APIs
• SQL package imports core for SQL import/export
• Demo apps import either:
• a specific skin package → render query builder in different frameworks
• UI (vanilla) or core (server) only
• Tests reference core + ui + skins to validate functionality
• CI pipelines run lint/tests/build & publish to npm
c. Architectural patterns & principles:
• Monorepo with workspace packages & shared scripts/config
• Separation of concerns: core logic vs UI rendering vs theme styling
• Re-exporting pattern: theme packages re-export UI (which re-exports core)
• Demo apps as isolation environments: local dev & CI smoke
• Import/export adapters decoupled from UI
• Peer-dependencies for UI frameworks (AntD, MUI, etc.)
d. Technologies & frameworks:
• Node.js, pnpm workspace, TypeScript, Babel, Webpack, Vite, Next.js
• React, Immutable.js in UI
• Testing: Karma, Mocha/Jest, Cypress-like specs
• CI: GitHub Actions, Codecov
• CSS: SCSS modules in each package, shared CSS in UI
Essential architectural elements
• Monorepo root orchestrates through pnpm-workspace.yaml
• Core ← UI ← theme packages
• Demo apps → consume themes or UI or core
• SQL adapter ← core
• Tests exercise all layers
• CI/CD pipelines building, testing, publishing each package