✨ NebulaKit
A cosmic-grade SvelteKit starter template powered by Cloudflare's full stack
NebulaKit is a production-ready SvelteKit template with everything you need to build modern web applications. It comes with Cloudflare Workers integration (D1, KV, R2, Queues, Turnstile), a complete theme system, command palette, LLM chat UI, full authentication, and drag-and-drop that works with a mouse, a finger or a keyboard—all built in from day one.
Before Anything Else
This repository is the site at nebulakit.starspace.group. It was derived from NebulaKit and is no longer a template — see AGENTS.md §5.
🌟 Features
- 🚀 Cloudflare Full Stack: D1 database, KV storage, R2 buckets, Queues, and Turnstile built-in
- 🎨 Theme System: Light/dark modes with extensible CSS variables
- ⌨️ Command Palette: Keyboard-first navigation (Cmd/Ctrl + K)
- 💬 LLM Chat UI: Ready-to-use chat interface for AI integration
- 🔐 Full Authentication: Email/password + SSO (Google, GitHub) with account linking
- 📱 Mobile-First: Responsive layouts optimized for all devices
- 🤖 Agent Ready: robots.txt with AI crawler rules, dynamic sitemap,
.well-known discovery, Markdown content negotiation, and WebMCP tools — all working out of the box
- 🎯 Drag & Drop: Pointer, touch and keyboard dragging, a columned widget board, and a pure reorder engine
- 🧱 Page Builder: Drag-and-drop pages stored as data, with revision history and a public site API (API keys, OpenAPI)
- 🛒 Shop: Products, cart and Stripe checkout, with late and failed payments handled
- ✉️ Email: Receipts and shipping notices through Resend, sent at most once per order
- 🌍 Regional Pricing: Purchasing-power pricing that only ever lowers a price (off by default)
- 👥 Roles and Permissions: Owner, superadmin, admin and user, with per-area access for admins
- 📜 Audit Log: Who changed what, never a secret value; sign-in tracking is opt-in
- ⏰ Scheduled Jobs: A cron Worker with run history and a Run now button
- 🔎 SEO: Site-wide JSON-LD, redirect manager, canonical host handling, security.txt and a Lighthouse admin
- 🛡️ Security Hardening: Security headers, login throttling, encrypted secrets at rest with key rotation, safer OAuth account linking, and a CI check that migrations are never edited
- ⚡ TypeScript: Full type safety with Cloudflare Workers types
- 🎨 UI Components: Beautiful, accessible components out of the box
🚀 Quick Start
Use the Template
Click the "Use this template" button above to create your own repository, or "Open in a codespace" to start coding instantly in the cloud.
Local Development
Recommended: Bun (faster installs and scripts in this repo).
# Install dependencies
bun install
# Start development server
bun run dev
# Build for production
bun run build
# Deploy to Cloudflare Pages
bun run deploy
Prefer npm instead? Use the equivalent commands:
npm install
npm run dev
npm run build
npm run deploy
Visit http://localhost:4278 to see your app!
🚇 Local Tunneling (Cloudflare Tunnel)
Share your local dev server with the outside world — no account needed for the free mode:
# Free public URL via trycloudflare.com (zero config, zero account)
bun run tunnel
# or: npm run tunnel
# Run dev server + tunnel together in one command
bun run dev:tunnel
The tunnel URL (e.g. https://random-words.trycloudflare.com) is printed to the console as soon as the tunnel is up.
Custom domain (e.g. myapp.yourdomain.com):
- Go to Cloudflare Zero Trust → Networks → Tunnels
- Create a tunnel, add a public hostname pointing to
http://localhost:4278
- Copy the tunnel token
- Add your domain to
vite.config.ts → server.allowedHosts (e.g. '.yourdomain.com')
TUNNEL_TOKEN=<your-token> bun run tunnel
Prerequisite: cloudflared must be installed.
What's pre-wired for tunnel use (in vite.config.ts):
allowedHosts includes trycloudflare.com — no Vite 403 rejections on free tunnels- HMR is off by default — WebSocket connections through cloudflared are unreliable and cause page hangs; set
VITE_HMR=true to re-enable for purely local dev
staleDepsFix plugin strips stale ?v= hashes so Vite never returns 504s on first load through a tunneloptimizeDeps.include pre-bundles Svelte at startup so the first tunneled page load doesn't trigger a slow on-demand optimization
The tunnel script lives at scripts/tunnel.js and respects a PORT env var if you change the dev port.
Toolchain
Svelte 5, SvelteKit 2.70, Vite 8, Vitest 4, @sveltejs/adapter-cloudflare 7 and
Node 24 or newer (the same stack as the NebulaKit template, so template code
copies across). The 220 components are still written in Svelte 4 syntax, which
Svelte 5 compiles in legacy mode; there is no need to rewrite them to runes.
Testing notes for the new stack:
- Listen to a
createEventDispatcher event in a test with the mount events
option (render(C, { props, events: { change: fn } })), and update props
with rerender. component.$on and component.$set no longer exist.
- happy-dom hides
Set-Cookie from Response. Route-handler tests that read
it import tests/helpers/server-response.ts first.
🧪 Testing (TDD Required!)
NebulaKit follows Test-Driven Development with 90%+ code coverage requirements:
# Run all tests
npm run test
# Run tests in watch mode
npm run test:watch
# Check coverage (must be ≥90%)
npm run test:coverage
# Run E2E tests
npm run test:e2e
# Run all tests (unit + E2E)
npm run test:all
Important: All features and bug fixes require tests written FIRST. See CONTRIBUTING.md for details.
📚 Documentation
🏗️ Project Structure
NebulaKit/
├── src/
│ ├── lib/
│ │ ├── components/ # Reusable UI components
│ │ ├── stores/ # Svelte stores (theme, etc.)
│ │ ├── server/ # Server-side utilities
│ │ └── utils/ # Helper functions
│ ├── routes/ # SvelteKit routes
│ │ ├── auth/ # Authentication pages
│ │ ├── chat/ # LLM chat interface
│ │ └── demo/ # Feature demonstrations
│ ├── app.css # Global styles & theme
│ └── app.html # HTML template
├── static/ # Static assets
└── wrangler.toml # Cloudflare configuration
🎨 Theming
NebulaKit includes a comprehensive theme system with:
- ✅ WCAG AA compliant colors (4.5:1 contrast minimum)
- 🌓 Light and dark modes with automatic system detection
- 🎨 CSS custom properties for all design tokens
- ♿ Accessibility-first design approach
- 🧪 Automated contrast validation
/* All colors use CSS variables - never hardcode! */
.button {
background-color: var(--color-primary);
color: var(--color-background);
border-radius: var(--radius-md);
padding: var(--spacing-sm) var(--spacing-md);
}
Validate theme contrast:
npm run validate:contrast
See the Theme System Guide for complete documentation.
🔦 Lighthouse
Every public page of the template and of this site scores 100 in all four
Lighthouse categories. The home page shows the table and links a full report per
page; the reports are served from static/lighthouse/.
Regenerate them with both apps built and served — this site on 8810 and the
template on 8820:
bun run lighthouse
The script audits each page three times and publishes the median run, writes one
HTML report per page, and writes the score table to
src/lib/lighthouse-results.json, which the home page renders. It exits non-zero
if any page drops below 100, so the numbers on the page cannot be edited into
being true. Point it at production instead with
--site <origin> --template <origin>.
The auth routes are not audited. robots.txt disallows /auth/, and Lighthouse
scores a crawl block as an SEO failure — correct for a login form, so the
conflict is left alone rather than scored around.
🔐 Authentication
Built-in auth pages with support for:
- Email/password authentication
- OAuth providers (Google, GitHub)
- Session management
- Account linking
Easily extend with @auth/sveltekit for more providers.
💬 Chat UI
The included chat interface is ready to connect to your LLM API:
// In /routes/chat/+page.svelte
async function sendMessage() {
const response = await fetch('/api/chat', {
method: 'POST',
body: JSON.stringify({ message: input })
});
// Handle response
}
☁️ Cloudflare Integration
D1 Database
const result = await platform.env.DB.prepare('SELECT * FROM users WHERE email = ?')
.bind(email)
.first();
KV Storage
await platform.env.KV.put('key', 'value');
const value = await platform.env.KV.get('key');
R2 Storage
await platform.env.BUCKET.put('file.jpg', fileData);
const file = await platform.env.BUCKET.get('file.jpg');
Queues
await platform.env.QUEUE.send({ data: 'message' });
🎯 Drag & Drop
<WidgetBoard> gives you a columned board of draggable widgets:
<WidgetBoard bind:widgets {columns} on:change={(e) => save(e.detail.widgets)} />
- Mouse, touch (hold to lift) and keyboard dragging, announced to screen readers
- Cross-column moves, a drop indicator, and edge auto-scroll
- Reordering is a pure function (
reorder()), so orders can never collide
- A widget registry that ships empty — register yours without touching the board
The two actions behind it, use:draggable and use:dropzone, work on any
markup, so a sortable list or a nav reorder needs no board at all.
Reference: docs/WIDGET_BOARD.md
📱 Mobile Support
NebulaKit is mobile-first with:
- Responsive breakpoints (640px, 768px, 1024px, 1280px)
- Touch-optimized interactions
- Mobile navigation menu
- Optimized bundle sizes
🛠️ Tech Stack
📝 License
MIT License - feel free to use this template for any project!
🤝 Contributing
We welcome contributions! Please read our Contributing Guide first.
Key requirements:
- ✅ Test-Driven Development (TDD) - write tests first
- ✅ 90%+ code coverage on all changes
- ✅ Cloudflare-first architecture
- ✅ Minimal external dependencies
- ✅ All tests passing before PR
See .github/copilot-instructions.md for detailed development guidelines.
⭐ Show Your Support
If you find NebulaKit useful, please consider giving it a star on GitHub!
