|
| 1 | +# CLAUDE.md |
| 2 | + |
| 3 | +This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. |
| 4 | + |
| 5 | +## Project Overview |
| 6 | + |
| 7 | +Celestite is a Crystal library that enables server-side rendering (SSR) of Svelte 5 components. It spawns a Bun/Vite render server that handles SSR requests via HTTP, allowing Crystal web applications to use Svelte as their view layer. |
| 8 | + |
| 9 | +## Commands |
| 10 | + |
| 11 | +### Install Dependencies |
| 12 | +```bash |
| 13 | +shards install # Installs Crystal deps and runs bun install via postinstall hook |
| 14 | +``` |
| 15 | + |
| 16 | +### Run Tests |
| 17 | +```bash |
| 18 | +crystal spec # Run all tests |
| 19 | +crystal spec spec/celestite_spec.cr # Run specific test file |
| 20 | +``` |
| 21 | + |
| 22 | +### Build for Production |
| 23 | +```bash |
| 24 | +# From svelte-scripts directory with proper env vars: |
| 25 | +make build COMPONENT_DIR=/path/to/views BUILD_DIR=/path/to/public/celestite |
| 26 | +``` |
| 27 | + |
| 28 | +### Development |
| 29 | +The project is a shard (Crystal library) - no standalone run command. Tests spawn a Bun SSR server that must start within 20 seconds. |
| 30 | + |
| 31 | +## Architecture |
| 32 | + |
| 33 | +### Crystal Side (`src/celestite/`) |
| 34 | +- **celestite.cr** - Main module entry point. Manages renderer lifecycle, handles SIGTERM for graceful shutdown. |
| 35 | +- **renderer.cr** - Core SSR logic. Spawns Bun process via Make, communicates over HTTP to render components. |
| 36 | +- **config.cr** - Configuration options: port (default 4000), vite_port (default 5173), env, component/layout/build directories, dev_secure (HTTPS mode), disable_a11y_warnings. |
| 37 | +- **engine.cr** - Engine enum (currently only Svelte). Maps engines to their script directories. |
| 38 | +- **amber.cr** - Framework adapters. Provides `celestite_render` macro for Amber and Kemal. |
| 39 | + |
| 40 | +### Bun/Vite Side (`src/svelte-scripts/`) |
| 41 | +- **vite-render-server.js** - Bun HTTP server using Vite for Svelte 5 SSR. Handles SSR with hydration support. |
| 42 | +- **vite.config.js** - Vite configuration for production builds. Auto-discovers entry points from COMPONENT_DIR. |
| 43 | +- **Makefile** - Launches render server with environment variables. Targets: `development`, `development_secure`, `staging`, `production`, `build`. |
| 44 | + |
| 45 | +### Request Flow |
| 46 | +1. Crystal app calls `Celestite.render(component, context)` |
| 47 | +2. HTTP POST request sent to Bun server on configured port |
| 48 | +3. Vite compiles and renders Svelte component (dev) or loads pre-built SSR module (production) |
| 49 | +4. HTML returned with hydration script and CSS injected |
| 50 | +5. Client-side hydration via Vite dev server (port 5173 in dev) or bundled assets (production) |
| 51 | + |
| 52 | +### Key Configuration Options |
| 53 | +```crystal |
| 54 | +Celestite.initialize( |
| 55 | + engine: Celestite::Engine::Svelte, |
| 56 | + component_dir: "./src/views/", # Svelte components |
| 57 | + build_dir: "./public/celestite/", # Output for client bundles |
| 58 | + port: 4000, # Bun SSR server port |
| 59 | + vite_port: 5173, # Vite dev server port (development only) |
| 60 | + dev_secure: false, # Enable HTTPS mode |
| 61 | + disable_a11y_warnings: false # Suppress Svelte a11y warnings |
| 62 | +) |
| 63 | +``` |
| 64 | + |
| 65 | +## Testing Notes |
| 66 | + |
| 67 | +Tests start actual Bun processes. The `run_spec_server` helper in `spec/spec_helper.cr` handles server lifecycle with timeout handling. Tests wait for "SSR renderer listening" in output before proceeding. |
0 commit comments