Documentation

Setup Guide

Get Cinder up and running in minutes with this comprehensive setup guide.

Installation

1

Clone the Repository

Get the latest source code from GitHub.

git clone https://github.com/Michael-Obele/cinder-sv.git
cd cinder-sv
2

Install Dependencies

Use Bun for faster installation and better performance.

bun install

Note: If using npm or pnpm, adjust the commands accordingly.

3

Configure Environment Variables

Copy the example environment file and update it with your backend details.

cp .env.example .env.local

Edit .env.local with:

PRIVATE_CINDER_BACKEND_URL=http://localhost:8000
PRIVATE_CINDER_API_KEY=your-api-key-here
4

Start Development Server

Launch the frontend development server.

bun run dev

The app will be available at http://localhost:5173

Development Commands

dev

bun run dev

Start development server with hot module reloading.

check

bun run check

Run TypeScript checks and find type errors. Essential after edits.

build

bun run build

Create production build.

preview

bun run preview

Preview production build locally.

format

bun run format

Format code with Prettier.

Backend Configuration

Backend Checklist
Cinder Go backend is running and accessible
Backend URL is set correctly in PRIVATE_CINDER_BACKEND_URL
API key is valid and set in PRIVATE_CINDER_API_KEY
CORS is properly configured (if running on different domain)
Network connectivity between frontend and backend is working

Project Structure Overview

cinder-sv/
├── src/
│   ├── lib/
│   │   ├── components/
│   │   │   ├── ui/          # shadcn-svelte components
│   │   │   └── blocks/      # Feature blocks
│   │   ├── utils.ts         # Utilities
│   │   └── assets/
│   ├── remote/
│   │   └── cinder.remote.ts # Backend RPC calls
│   ├── routes/
│   │   ├── +layout.svelte
│   │   ├── +page.svelte
│   │   ├── playground/
│   │   └── docs/
│   ├── app.html
│   └── app.d.ts
├── static/                  # Static assets
├── frontend_plan/           # Documentation
├── .env.example
├── svelte.config.js
├── vite.config.ts
├── tsconfig.json
├── tailwind.config.ts
└── package.json

Key files: src/remote/cinder.remote.ts (backend calls), src/routes/layout.css (theme configuration).

Troubleshooting

Port Already in Use

If port 5173 is already in use, Vite will use the next available port automatically. Check the terminal output for the actual URL.

Backend Connection Failed

1. Verify the backend is running

2. Check PRIVATE_CINDER_BACKEND_URL is correct

3. Ensure API key is valid

4. Check network connectivity and firewall rules

Type Errors After Changes

Always run bun run check after making changes to catch errors early.

Dependencies Not Found

Try deleting node_modules and reinstalling:

bun install --force

Next Steps

→ Explore Features

Learn about Scrape, Crawl, and Search capabilities.

→ Try the Playground

Test the frontend with your backend.

→ Understand Architecture

Deep dive into how everything works together.