8000 minilake/ui/README.md at v1.9.1 · dmux/minilake · GitHub
[go: up one dir, main page]
Skip to content

README.md

Latest commit

 

History

History
70 lines (59 loc) · 3.16 KB

README.md

File metadata and controls

70 lines (59 loc) · 3.16 KB
Raw

minilake web UI

The SQL workspace minilake serves at /ui. Next.js 16 (App Router, static export), React 19, Tailwind v4, shadcn/ui on the base-nova style, Monaco for the editor.

User-facing documentation, including the Athena mapping and the dev-server setup, lives in ../docs/ui.md. This file covers the code.

Commands

pnpm install
pnpm dev        # dev server on :3000 (needs the API — see ../docs/ui.md)
pnpm build      # static export into ./out
pnpm lint
pnpm typecheck
pnpm test       # vitest, over the pure helpers in src/lib

pnpm build and pnpm dev both run scripts/copy-monaco.mjs first.

Layout

src/
├── app/                  one route per workspace view; every page is a client component
├── components/
│   ├── layout/           sidebar, header, warehouse picker, theme toggle
│   ├── editor/           tabs, Monaco wrapper, toolbar, SQL completion provider
│   ├── results/          grid, chart, stats, the tabbed results panel
│   ├── catalog/          Unity Catalog tree and the DDL dialog
│   └── ui/               shadcn components (generated — regenerate, don't hand-edit)
├── hooks/                react-query wrappers and the execution hook
├── lib/
│   ├── api/              one module per API group, over a shared fetch client
│   ├── sql-identifier.ts quoting, table refs, auto-limit
│   ├── csv.ts            CSV/JSON export
│   └── ddl.ts            CREATE TABLE generation
└── stores/               zustand: editor tabs and workspace preferences

Conventions

  • Server state is server state. Anything the API owns goes through @tanstack/react-query; only per-browser preferences and open editor tabs live in zustand's persist. Query history and saved queries are deliberately not local — they are real minilake APIs.
  • All API calls go through lib/api/client.ts, which resolves the base URL and turns {error_code, message} bodies into MinilakeApiError. Never call fetch from a component.
  • No CDN dependencies. The container image is offline-capable; anything the page loads must be served from this origin. That is why Monaco is copied into public/ at build time.
  • Themes are three-state. next-themes with attribute="class". Read resolvedTheme, never theme, when the value drives rendering — theme is the literal string "system" until the user picks one.
  • Base UI, not Radix. The base-nova shadcn style composes with render={...} where Radix would use asChild.
  • pnpm dlx shadcn@latest add <component> for new primitives, so they stay regenerable.

Notes

  • next.config.ts sets output: "export", basePath: "/ui" and trailingSlash: true. The last one matters: it emits out/<route>/index.html, which is what FastAPI's StaticFiles(html=True) serves for a directory.
  • react-resizable-panels v4 takes orientation (not direction), and a bare number size means pixels — sizes here are percentage strings.
  • AGENTS.md in this directory is generated by next dev; commit it with your changes rather than deleting it.
0