NebulaKit Documentation

Start Here

If this repo is being used as a template, first complete the customization workflow in docs/INITIAL_CUSTOMIZATION.md. The current repository status file is still set to pending, which means template branding cleanup has not been finished yet.

1. Create your repository from the template.
2. Install dependencies and run the app locally.
3. Apply database migrations locally.
4. Configure OAuth and owner access through the setup flow.
5. Run tests and coverage before shipping changes.

Quick Start

Then clone your repository, run the commands below, and open http://localhost:4277.

Bun is the recommended default for this repo. Switch to npm commands if your environment requires it.

								# Install dependencies
							
								$
									bun install
							
								
							
								# Start development server
							
								$
									bun run dev
							
								
							
								# Apply local D1 migrations
							
								$
									bun run db:migrate:local
							
								
							
								# Build for production
							
								$
									bun run build
							
								
							
								# Type-check and tests
							
								$
									bun run check
							
								$
									bun run test
							
								
							
								# Coverage report
							
								$
									bun run test:coverage
							
								
							
								# Deploy to Cloudflare Pages
							
								$
									bun run deploy
							

What You Get Out of the Box

This starter already ships with the main product surfaces wired together. The fastest way to understand the repo is to think of it as a Cloudflare-first app shell with auth, theming, content management, and AI entry points already in place.

How To Use the App

Use the app in this order if you want the least confusing first run. That sequence matches how the repo is structured and avoids most setup-related false alarms.

1. Open /setup first on a fresh environment and configure owner credentials.
2. Complete /setup before expecting sign-in or AI features to work.
3. Sign in through /auth/login or create an account through /auth/signup.
4. Open the command palette with Ctrl/Cmd + K to move between major routes quickly.
5. Use /chat for AI interactions, /profile for account settings, and /admin for operator tasks.
6. Use the theme toggle to verify light and dark presentation while you customize branding.

Working With AI in This Repo

Treat AI as a fast pair programmer, not as a source of truth. It is useful here because the repo already includes app structure, tests, and strong conventions, which gives the assistant real context to work against.

If you are using an AI coding agent, keep requests concrete: mention the page or failing test, state the desired behavior, and ask for the smallest validating change that solves it.

Core Commands

These scripts are defined in package.json and are the canonical local workflow.

Cloudflare Bindings

NebulaKit is configured for Cloudflare Pages with these bindings in wrangler.toml:

• DB as D1 database binding (database name: nebulakit-db).
• KV as KV namespace for runtime config and flags.
• BUCKET as R2 bucket binding.
• Queue producer binding is documented but commented out by default.

Set app secrets in Cloudflare dashboard or Wrangler secrets for production. Avoid committing raw secrets to source control.

Database Migrations

Migrations are ordered SQL files under migrations/ and tracked by D1. Never edit or delete existing migration files once committed to main.

# Apply pending migrations to local D1
npm run db:migrate:local

# Apply pending migrations to remote D1
npm run db:migrate

# List migration status
npm run db:migrate:list

When schema changes are needed, create a new file with the next sequence number (for example, 0006_add_feature_flag.sql) and use ALTER TABLE or new CREATE statements.

Authentication and Setup Flow

Auth uses @auth/sveltekit with a setup-first workflow. The main routes are /setup, /auth/login, and /reset.

Testing and Quality Gates

NebulaKit follows Test-Driven Development. Write failing tests first, then implementation, then refactor.

# Run all tests
npm run test

# Run tests in watch mode
npm run test:watch

# Check coverage
npm run test:coverage

# Run E2E tests
npm run test:e2e

# Run all tests (unit + E2E)
npm run test:all

Coverage guidance in repository docs is mixed: several files reference 90 percent, while AI assistant workflow instructions enforce 95 percent as a stricter floor. For new work, target 95 percent or higher to satisfy both interpretations safely.

Project Structure

NebulaKit/
├── .github/              # Copilot and workflow instructions
├── src/
│   ├── lib/
│   │   ├── components/     # Reusable UI components
│   │   ├── services/       # Business logic
│   │   ├── stores/         # Svelte stores
│   │   ├── types/          # Shared type definitions
│   │   └── utils/          # Helpers
│   ├── routes/             # SvelteKit routes
│   │   ├── api/            # API endpoints
│   │   ├── auth/           # Authentication pages
│   │   ├── chat/           # Chat UI
│   │   ├── setup/          # First-time setup flow
│   │   └── documentation/  # This page
│   ├── app.css            # Global styles & theme
│   └── app.html           # HTML template
├── tests/                  # unit/integration/e2e tests
├── migrations/             # Immutable D1 migration files
├── docs/                   # Extended project docs
└── wrangler.toml           # Cloudflare bindings/config

Deployment to Cloudflare Pages

1. Push your repository to GitHub.
2. In Cloudflare dashboard, open Pages and connect the repository.
3. Use build command npm run build.
4. Use output directory .svelte-kit/cloudflare.
5. Add D1, KV, and R2 bindings to the Pages project settings.
6. Add required environment variables and secrets.
7. Deploy and verify auth, setup flow, and database connectivity.

The local deploy script already uses wrangler pages deploy .svelte-kit/cloudflare.

Troubleshooting

• If setup API reports KV unavailable, create KV namespaces and update wrangler.toml binding IDs.
• If login fails after setup, confirm OAuth callback URL and ensure GitHub credentials are valid.
• If migrations fail, run npm run db:migrate:list and check migration numbering.
• If command palette entries are missing, verify AI provider status and authentication state.

References

• GitHub repository
• README
• Contributing Guide
• Initial Customization
• Theme System
• Cloudflare Pages plus SvelteKit Guide

Contributing

Use TDD, keep changes small and reviewable, and run tests plus checks before opening a pull request.

• Write tests before implementation changes.
• Run npm run check, npm run test, and npm run test:coverage.
• Prefer Cloudflare-native services and minimal external dependencies.
• Do not edit past migration files; create a new one instead.