# sheets **Repository Path**: WChengHe/sheets ## Basic Information - **Project Name**: sheets - **Description**: No description available - **Primary Language**: Unknown - **License**: Apache-2.0 - **Default Branch**: main - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 1 - **Created**: 2026-11-17 - **Last Updated**: 2026-11-17 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README
# Casual Sheets **Open-source self-hosted web spreadsheet with `.xlsx` round-trip and real-time co-editing — an alternative to Google Sheets, Excel Online, and OnlyOffice you run on your own server.** [![CI](https://github.com/CasualOffice/sheets/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/CasualOffice/sheets/actions/workflows/ci.yml) [![Deploy](https://github.com/CasualOffice/sheets/actions/workflows/deploy-pages.yml/badge.svg?branch=main)](https://github.com/CasualOffice/sheets/actions/workflows/deploy-pages.yml) [![Docker Pulls](https://img.shields.io/docker/pulls/casualoffice/sheets?logo=docker)](https://hub.docker.com/r/casualoffice/sheets) [![Image Size](https://img.shields.io/docker/image-size/casualoffice/sheets/latest?logo=docker&label=image)](https://hub.docker.com/r/casualoffice/sheets) [![E2E Tests](https://img.shields.io/badge/e2e-398%20passing-brightgreen?logo=playwright)](./tests/e2e) [![Unit Tests](https://img.shields.io/badge/unit-235%20passing-brightgreen)](./apps) [![Version](https://img.shields.io/badge/version-v0.3.2-blue)](./CHANGELOG.md) [![License](https://img.shields.io/badge/license-Apache--2.0-blue)](./LICENSE) [**Live Demo →**](https://sheet.casualoffice.org/)  ·  [Docker Hub →](https://hub.docker.com/r/casualoffice/sheets)  ·  [Architecture →](./docs/ARCHITECTURE.md)  ·  [Embed / SDK →](./docs/SDK_ARCHITECTURE.md)  ·  [Comparisons →](https://casualoffice.org/vs/)
[![Casual Sheets — the editor with a populated budget](./docs/media/hero.png)](https://sheet.casualoffice.org/)
--- Casual Sheets is a **self-hostable, browser-based spreadsheet** that looks and behaves like Microsoft Excel — ribbon UI, formula bar, file-centric workflow — with **real-time multi-user co-editing** built in. Upload an `.xlsx` file, share a link, and edit together instantly. **No accounts, no Microsoft / Google login, no lock-in** — your data stays on your own server, in one Docker container. ### Who is this for? Teams that need a **self-hosted spreadsheet editor embedded inside their own product** — an intranet, file manager, LMS, CRM, or private cloud — without sending data to Google or Microsoft. Use it as a standalone app or [embed the editor as an SDK](./docs/SDK_ARCHITECTURE.md). > **Maturity** — `0.x`: production-ready for small / self-hosted deployments; still evolving for enterprise-scale workloads. One box scales to thousands of concurrent editors ([load-tested](./docs/LOAD_TEST.md)); see the [CHANGELOG](./CHANGELOG.md) for what's stable. **Compares to:** [Google Sheets](https://casualoffice.org/vs/sheets-vs-google-sheets/) · [Excel Online](https://casualoffice.org/vs/sheets-vs-excel-online/) · [OnlyOffice](https://casualoffice.org/vs/sheets-vs-onlyoffice/) Built on [Univer OSS](https://github.com/dream-num/univer) (Apache-2.0) — the OSS variant, **never the Pro package** — with a custom Office-style shell layered on top. Sister projects: [Casual Editor](https://github.com/CasualOffice/docs) (`.docx`) and [Casual Slides](https://github.com/CasualOffice/slides) (`.pptx`). --- ## ✨ What's Inside ### Core editor - **Google-Docs-style title bar** — logo + filename + classic menus (File / Edit / View / Insert / Format / Data) in a single chrome strip, right-edge **panel rail** for Tables / Charts / Outline / Comments / History - **Formula bar** with an editable Name Box (jump to any cell by typing its address) - Cell editing: inline edit, F2, formula entry, multi-line paste, cross-sheet references with autocomplete - Fonts, colors, fill, borders (7 modes + color picker), alignment, wrap, merge/unmerge - Rows + columns: hide/unhide, group/outline (collapse/expand), resize - **Freeze panes** — top row, first column, or freeze at any selection - **Sort** (single and multi-column dialog), **Filter** (AutoFilter + re-apply), **Tables** (Format as Table, named tables panel) - **Comments** with corner indicator markers - **Conditional formatting**, **data validation**, **drawings** — fully round-tripped and co-edit synced ### Charts, pivots & analysis - **Charts** — 8 types, drag-to-resize, format dialog with **trendlines**, **date-axis detection**, **per-series colour overrides**; collab-synced; PNG embed in `.xlsx` - **Pivot tables** — group-by + multi-aggregations, **filter fields**, **Refresh PivotTables**, **drill-down to source rows** (Ctrl+Shift+D), Insert dialog - **Sparklines** — in-cell mini-charts (line / column / win-loss) via Insert → Sparkline, persist through the `__casual_sheets_sparklines__` resource - **Analysis tools** — Name Manager (Ctrl+F3), Flash Fill (Ctrl+E), Goal Seek (iterative solver) - **Show Formulas** (Ctrl+`) — non-destructive overlay paints formula source on every formula cell - **Print Area** — A1 field in Page Setup + File-menu "Set / Clear Print Area" - **Paste Special** (Ctrl+Alt+V) — All / Values / Formulas / Formats / Column widths / All except borders - **Recent Files** — IndexedDB landing screen surfaces the last 10 workbooks on a blank `Untitled` - **Version history** — auto-snapshots every ~10 min while dirty + "Save version…" manual entries; preview a snapshot then Restore (captures a "before restore" crumb for undo) - **Dark theme** — title-bar sun/moon toggle, bridged to Univer's `ThemeService` so the canvas chrome flips too - **Status-bar customisation** — right-click selection stats to toggle which appear (Average / Count / Sum / Min / Max / Numerical Count) - Sheet tabs: add, rename, delete, reorder, color; tab strip refreshes live when peers act - **Autosave** to IndexedDB with a restore banner if the tab closes unexpectedly - Dynamic workbook growth — starts at 1024×26, expands to 8192×1024 on demand - File → Properties dialog, Help → Report a Bug (GitHub issue prefill) - **Inline SVG icons** (~155 components) — sharp at every size, no font-load delay ### File I/O | Format | Open | Save / Export | | --------------- | :--: | :-----------: | | `.xlsx` | ✅ | ✅ | | `.ods` | ✅ | ✅ | | `.csv` / `.tsv` | ✅ | ✅ | - Parsed and serialised entirely in **Web Workers** — the main thread never blocks on multi-MB files - ODS round-trip: styles, dimensions, freeze, hyperlinks, comments, defined names - xlsx round-trip: conditional formatting, data validation, drawings, tab colors, named ranges, hyperlinks (inline `cell.p` encoding), chart PNGs ### Excel Keyboard Shortcuts 40+ canonical shortcuts wired: Ctrl+1 (Format Cells), Shift+F8 (Add to Selection), Ctrl+Shift+L (AutoFilter), **Ctrl+Alt+L** (re-apply filter), Alt+= (AutoSum), F9 (recalculate), Ctrl+W (close), Alt+F1 (chart), **Ctrl+E** (Flash Fill), **Ctrl+F3** (Name Manager), **Ctrl+Alt+V** (Paste Special), **Ctrl+`** (Show Formulas), **Ctrl+[ / Ctrl+]** (precedents / dependents), **Ctrl+Shift+D** (pivot drill-down), number-format shortcuts, hide/unhide rows/columns, border combos. ### Co-editing Available in the Docker image. Single-user on the hosted demo. - **Share dialog** — File → Share for co-editing. Set a password, choose edit or view-only, get two copyable URLs - **Presence avatars** — title-bar avatar stack with "Active now / Last seen Ns ago" tooltips; idle peers fade - **Live cursors** — each peer's selection range in their color, with a name label, tracking scroll and frozen panes - **Live-typing ghost** — characters appear in the peer's cell as they type, not just on commit - **Full mutation sync** — cell values, styles, structure, conditional formatting, data validation, drawings, workbook metadata (tab colors, zoom, freeze, sheet visibility) all propagate cross-peer - **View-only enforcement** at the Univer engine layer — view-only joiners cannot mutate the workbook, not just at the UI level - **Session-history panel** — per-room op log with timestamps; review or revert any change - **Divergence detection** — amber "Out of sync" pill when state vectors diverge; "Waiting to reconnect" banner on WebSocket drop - **Password-protected rooms** — SHA-256 + constant-time compare; wrong password → HTTP 401 on the WS upgrade - **Op-log compaction** — long-lived rooms compact the Yjs update log on `requestIdleCallback` to keep memory bounded - **Joiner fast-path** — gzip-streamed pre-parsed snapshot from the server; joiners skip the xlsx parse entirely See [`docs/CO-EDITING.md`](./docs/CO-EDITING.md) for the full architecture. --- ## 🔒 Security model - **Your data stays on your server.** No third-party calls, no telemetry, no Google / Microsoft account required. Files live in your container / volume (or Redis when persistence is on). - **Co-editing rooms** are password-gated: **SHA-256** hashing with a constant-time compare; a wrong password fails the WebSocket upgrade with HTTP 401 (never a partial join). - **View-only is enforced at the Univer engine layer**, not just the UI — view-only joiners physically cannot mutate the workbook. - **Personal mode** (multi-user) uses a **bcrypt** users table (SQLite) with per-user file scoping and an admin panel — see [`docs/self-hosting/personal-mode.md`](./docs/self-hosting/personal-mode.md). - **WOPI mode** verifies host **JWT** tokens and honours Lock/Unlock + token refresh — see [`docs/STORAGE_MODES.md`](./docs/STORAGE_MODES.md). - Apache-2.0, fully auditable; built only on Univer **OSS** (never the closed Pro package). --- ## 🐳 Self-Host with Docker A single multi-arch image (`linux/amd64` + `linux/arm64`). Web, Hocuspocus, and Fastify run in one container; Redis runs alongside for room persistence. ### Quick start (in-memory, no persistence) ```sh docker run --rm -p 3000:3000 casualoffice/sheets:latest ``` Open `http://localhost:3000`. **Anonymous mode** — no signup, no persistence; close the container and everything's gone. Good for kicking the tyres. ### Recommended: personal mode + Redis persistence Paste this `docker-compose.yml` and run `docker compose up -d`: ```yaml services: app: image: casualoffice/sheets:latest restart: unless-stopped ports: ['3000:3000'] volumes: - casual-data:/data environment: # Phase C — sign up, save, reopen across restarts. CASUAL_STORAGE: local CASUAL_LOCAL_PATH: /data CASUAL_PERSONAL_MODE: single # Y.Doc snapshots for co-edit rooms. REDIS_URL: redis://redis:6379 ROOM_TTL_MIN: '60' depends_on: redis: condition: service_healthy redis: image: redis:7.4-alpine restart: unless-stopped command: ['redis-server', '--appendonly', 'yes'] volumes: - redis-data:/data healthcheck: test: ['CMD', 'redis-cli', 'ping'] interval: 10s timeout: 3s retries: 5 volumes: casual-data: redis-data: ``` Open `http://localhost:3000`, sign up — your account + workbooks live in the `casual-data` volume and survive `docker compose down`. `CASUAL_PERSONAL_MODE=multi` keeps signup open if you want more than one account on the same instance; `none` reverts to the anonymous shape. For an admin without manual signup, set `CASUAL_BOOTSTRAP_USER=admin:hunter2` once in your `.env` — silently no-ops after the users table has a row. Full reference: [`docs/ENV.md`](./docs/ENV.md), [`docs/self-hosting/personal-mode.md`](./docs/self-hosting/personal-mode.md). ### Try co-editing 1. Open `http://localhost:3000`. **File → Share for co-editing…** to set a password and get two share URLs. 2. Paste either URL into another browser or device — the joiner connects in under a second. 3. Move your selection — peers see your named cursor follow it. Type in a cell — peers see characters appear live. ### API surface | Method | Path | Description | | ------ | ------------------------- | ------------------------------------------------------------ | | `GET` | `/` | Serves the built web app | | `GET` | `/r/:roomId` | Same SPA; bridges into the named Y.Doc | | `POST` | `/api/rooms` | Create a room; body `{password?}` | | `GET` | `/api/rooms/:id/info` | Pre-flight: `{needsPassword, hasSeed, hasSnapshot, clients}` | | `POST` | `/api/rooms/:id/seed` | Multipart `.xlsx` upload — the room's starting workbook | | `GET` | `/api/rooms/:id/seed` | Download the seed file | | `POST` | `/api/rooms/:id/snapshot` | Gzipped JSON snapshot — joiner fast-path upload | | `GET` | `/api/rooms/:id/snapshot` | Joiner snapshot fetch (immutable-cached) | | `GET` | `/api/rooms` | Diagnostic: live rooms + client counts | | `GET` | `/health` | Liveness probe — `{ok, ts, rooms}` | | `WS` | `/yjs` | Hocuspocus sync; `?room=&p=` | ### Configuration Copy `.env.example` to `.env`; `docker compose up` picks it up automatically. | Env var | Scope | Default | Description | | --------------------- | ------ | ------------ | ------------------------------------------------------------------- | | `PORT` | server | `3000` | HTTP + WebSocket listen port | | `HOST` | server | `0.0.0.0` | Bind address | | `REDIS_URL` | server | _unset_ | Redis connection string; enables Y.Doc persistence with a 7-day TTL | | `ROOM_TTL_MIN` | server | `15` | Minutes a room stays alive after the last client leaves | | `MAX_UPLOAD_MB` | server | `100` | Upload cap for xlsx seed + gzipped snapshot | | `VITE_COLLAB_ENABLED` | build | `1` in image | Include co-edit code in the bundle | | `VITE_MAX_OPEN_MB` | build | `100` | Hard reject threshold for File → Open / drag-drop | | `VITE_SOFT_WARN_MB` | build | `25` | Shows a "large file" hint before opening | `VITE_*` vars are baked in at build time. Pass them with `--build-arg` on `docker build`, or via the `args:` block in `docker-compose.yml`. The full env-var matrix (storage backends, networking, admin, JWT, webhooks, more) is documented in [`docs/ENV.md`](./docs/ENV.md) — that's the canonical reference the admin panel reads from too. ### 🧩 Embed the editor (SDK) The editor ships as an npm package — **`@casualoffice/sheets@0.9.0`** — that you mount as a single React component. The SDK stores nothing; it hands you the data on save/exit and you persist it. Collaboration is opt-in; no backend to embed. > **Early `0.x`, still evolving.** `@casualoffice/sheets` is the new > Excalidraw-model editor SDK; the restructure continues (Office chrome slots + > storage/collab adapters are still landing). The older `@schnsrw/casual-sheets` > is a pre-restructure line without this API — install `@casualoffice/sheets`. ```tsx import { CasualSheets } from '@casualoffice/sheets/sheets'; import '@casualoffice/sheets/styles'; persist(snap)} />; ``` Full guide — install, props, `CasualSheetsAPI`, xlsx import, opt-in collab: [`docs/INTEGRATION.md`](./docs/INTEGRATION.md). Sandboxed `