# n6k server

Arrow/Parquet REST server with React page serving.

## Prerequisites

- Python 3.12+
- [uv](https://docs.astral.sh/uv/)
- [Bun](https://bun.sh/)

## Install

```bash
uv sync
```

## Quick start

### 1. Initialize the UI

```bash
uv run n6k init demo.app:app
```

This will:
- Create the `ui/` directory with scaffolding (tailwind, esbuild, shadcn config)
- Install JS dependencies via `bun install`
- Import your app to discover `page()` calls and write `.astro` files
- Detect required shadcn components and prompt to install them

### 2. Run the server

```bash
uv run uvicorn demo.app:app --reload
```

### 3. Visit

- `http://localhost:8000/` — simple page
- `http://localhost:8000/form` — page with shadcn components
- `http://localhost:8000/tables/demo` — Arrow data endpoint

## Usage

### Data endpoints

```python
from n6k_server.app import create_app, data

app = create_app()

@data(app, "my_table")
def my_table():
    return pd.DataFrame({"id": [1, 2, 3]})
```

Serves at `GET /tables/my_table` in Arrow IPC, Arrow File, or Parquet format (content-negotiated via `Accept` header).

### Pages

```python
from n6k_server.app import create_app, page

app = create_app()

page(app, "/", "<div>Hello</div>")

page(app, "/dashboard", """
    <div className="flex gap-2 p-8">
      <Button>Click me</Button>
    </div>
""")
```

Pages are JSX snippets. shadcn components (`<Button>`, `<Checkbox>`, etc.) are auto-detected and imported at build time.

On first request, all pages are bundled together via esbuild with code splitting — shared dependencies (React, Radix, etc.) are extracted into chunks.

### Adding components

After adding new shadcn components to your pages, re-run init to install them:

```bash
uv run n6k init demo.app:app
```

Or add them directly:

```bash
bun run --cwd ui shadcn add button card dialog
```

## Project structure

```
src/n6k_server/       # library source
demo/app.py           # example application
ui/                   # generated by `n6k init`
  pages/              # .astro snippet files (written by page() calls)
  components/ui/      # shadcn components (installed via shadcn CLI)
  build/              # esbuild output (generated on first request)
  build.mjs           # esbuild config with n6k plugin
  globals.css         # tailwind + design tokens
  lib/utils.ts        # cn() utility
tests/
```

## Tests

```bash
uv run pytest tests/ -v
```
