Installation

Get a new Svelar project up and running in minutes.

System Requirements

• Node.js: 20.0.0 or higher
• npm: 10.0.0 or higher (or pnpm, yarn)
• Docker: Recommended for production (optional for development)

Creating a New Project

npx @beeblock/svelar new my-app
cd my-app
npm run dev

That's it. The CLI scaffolds a complete SvelteKit + Svelar project, installs dependencies, and you're ready to go. Use npx @beeblock/svelar new when npm needs to fetch the package for a new app. Inside a generated app, @beeblock/svelar installs the svelar binary, so project-local commands can use npx svelar ....

What's Scaffolded

• SvelteKit 2 with Vite and TypeScript
• Tailwind CSS 4 with theme variables (--color-brand, etc.)
• Svelar Framework — ORM, Auth, Sessions, Middleware, Queue, Scheduler, and 35+ modules
• SQLite Database — Pre-configured, zero setup
• Icon Libraries — @lucide/svelte and @tabler/icons-svelte included
• Environment Config — .env.example with sensible defaults
• Vite Config — All @beeblock/svelar/* aliases, SSR config, and fs.allow pre-wired
• EventServiceProvider — Pre-wired for event listeners, subscribers, and model observers
• Application Bootstrap — app.ts bootstraps the service provider lifecycle
• Agent Guidance — AGENTS.md, CLAUDE.md, and local Codex/Claude Svelar skills are generated so AI agents follow the same framework conventions

Project Structure (DDD Modular Monolith)

my-app/
├── src/
│   ├── app.ts                    # Bootstrap (database, hashing, providers)
│   ├── app.css                   # Tailwind CSS + theme
│   ├── app.html                  # SvelteKit shell
│   ├── hooks.server.ts           # Middleware pipeline
│   ├── lib/
│   │   ├── modules/              # Domain modules (DDD)
│   │   │   ├── auth/
│   │   │   │   ├── contracts/schemas/
│   │   │   │   ├── domain/models/
│   │   │   │   ├── domain/events/
│   │   │   │   ├── domain/observers/
│   │   │   │   ├── domain/policies/
│   │   │   │   ├── application/actions/
│   │   │   │   ├── application/dto/
│   │   │   │   ├── application/listeners/
│   │   │   │   ├── application/services/
│   │   │   │   ├── infrastructure/repositories/
│   │   │   │   └── interface/http/
│   │   │   │       ├── controllers/
│   │   │   │       ├── requests/
│   │   │   │       └── resources/
│   │   │   ├── billing/
│   │   │   └── posts/
│   │   ├── shared/               # Cross-cutting concerns
│   │   │   ├── middleware/       #   Custom middleware
│   │   │   ├── components/       #   Shared Svelte components
│   │   │   ├── stores/           #   Svelte stores
│   │   │   ├── jobs/             #   Queue jobs
│   │   │   ├── plugins/          #   Custom plugins
│   │   │   ├── channels/         #   Broadcast channels
│   │   │   ├── commands/         #   Custom CLI commands
│   │   │   ├── providers/        #   Service providers (EventServiceProvider, etc.)
│   │   │   └── scheduler/        #   Scheduled tasks
│   │   └── database/
│   │       ├── migrations/
│   │       └── seeders/
│   └── routes/
│       ├── +layout.svelte
│       ├── +page.svelte
│       └── api/
├── storage/
│   ├── logs/                     # Application logs
│   ├── cache/                    # File-based cache
│   ├── uploads/                  # User uploads
│   └── sessions/                 # File-based sessions
├── static/
├── AGENTS.md
├── CLAUDE.md
├── .codex/skills/svelar-specialist/SKILL.md
├── .claude/skills/svelar-specialist/SKILL.md
├── vite.config.ts
├── svelte.config.js
├── svelar.database.json
├── .env.example
└── package.json

Each module is a self-contained domain. Domain concerns (models, events, observers, policies), application concerns (actions, dto, listeners, services), infrastructure concerns (repositories), interface concerns (controllers, requests, resources), and contracts (schemas) stay grouped inside that module. The shared/ folder holds cross-cutting infrastructure.

Step 1: Environment Variables

If you used npx @beeblock/svelar new, .env is already generated with secure random secrets. For manual setup:

cp .env.example .env
npx svelar key:generate

Edit .env:

# App Security — generated by key:generate or npx @beeblock/svelar new
APP_KEY=<auto-generated>

# Database (SQLite by default, no extra config needed)
DB_DRIVER=sqlite
DB_PATH=database.db
# Optional PostgreSQL/MySQL connection URL. When set, it takes precedence over DB_HOST/DB_PORT/etc.
# DATABASE_URL=postgres://postgres:secret@localhost:5432/svelar_db

# PostgreSQL (uncomment to switch)
# DB_DRIVER=postgres
# DB_HOST=localhost
# DB_PORT=5432
# DB_NAME=svelar_db
# DB_USER=postgres
# DB_PASSWORD=secret

# MySQL (uncomment to switch)
# DB_DRIVER=mysql
# DB_HOST=localhost
# DB_PORT=3306
# DB_NAME=svelar_db
# DB_USER=root
# DB_PASSWORD=secret

# JWT (if using JWT auth)
# JWT_SECRET=your-jwt-secret-key

# Mail (optional)
# MAIL_DRIVER=log
# MAIL_FROM=hello@example.com

# Redis (optional — needed for BullMQ queue and Redis cache/session)
# QUEUE_DRIVER=sync
# REDIS_URL=redis://localhost:6379

# Broadcasting (optional — Pusher/Soketi WebSocket)
# PUSHER_KEY=app-key
# PUSHER_SECRET=app-secret
# PUSHER_APP_ID=app-id
# PUSHER_HOST=localhost
# PUSHER_PORT=6001

Step 2: Create Your First Model & Migration

npx svelar make:model User
npx svelar make:migration CreateUsersTable

Edit the generated migration in src/lib/database/migrations/:

import { Migration } from '@beeblock/svelar/database';

export default class CreateUsersTable extends Migration {
  async up() {
    await this.schema.createTable('users', (table) => {
      table.id();
      table.string('name');
      table.string('email').unique();
      table.string('password');
      table.timestamps();
    });
  }

  async down() {
    await this.schema.dropTable('users');
  }
}

Step 3: Run Migrations

npx svelar migrate

Check migration status:

npx svelar migrate --status

Step 4: Start Building

npm run dev

Visit http://localhost:5173. Your app is running.

Docker Deployment

When you're ready for production, scaffold Docker files:

npx svelar make:docker

This generates:

Docker Flags

npx svelar make:docker --db=mysql       # MySQL instead of PostgreSQL
npx svelar make:docker --db=sqlite      # SQLite (no external DB)
npx svelar make:docker --no-redis       # Skip Redis
npx svelar make:docker --no-soketi      # Skip WebSocket server
npx svelar make:docker --no-gotenberg   # Skip PDF service
npx svelar make:docker --no-rustfs      # Skip object storage
npx svelar make:docker --no-meilisearch # Skip full-text search
npx svelar make:docker --force          # Overwrite existing files

Quick Start

# Generate Docker files
npx svelar make:docker

# Build and start everything
docker compose up -d --build

# Run migrations inside the container
docker compose exec app npx svelar migrate

# Seed data
docker compose exec app npx svelar seed:run

# View logs
docker compose logs -f app

# Stop
docker compose down

Runtime Processes

For local development, keep infrastructure in Docker and run the daemons from source:

npm run dev:worker
npm run dev:scheduler

Manual Setup

If you prefer adding Svelar to an existing SvelteKit project:

npm install @beeblock/svelar

Then create src/app.ts:

import { Connection } from '@beeblock/svelar/database';
import { Hash } from '@beeblock/svelar/hashing';

Connection.configure({
  default: process.env.DB_DRIVER ?? 'sqlite',
  connections: {
    sqlite: {
      driver: 'sqlite',
      filename: process.env.DB_PATH ?? 'database.db',
    },
    postgres: {
      driver: 'postgres',
      url: process.env.DATABASE_URL,
      host: process.env.DB_HOST ?? 'localhost',
      port: Number(process.env.DB_PORT ?? 5432),
      database: process.env.DB_NAME ?? 'svelar_db',
      user: process.env.DB_USER ?? 'postgres',
      password: process.env.DB_PASSWORD ?? '',
    },
    mysql: {
      driver: 'mysql',
      url: process.env.DATABASE_URL,
      host: process.env.DB_HOST ?? 'localhost',
      port: Number(process.env.DB_PORT ?? 3306),
      database: process.env.DB_NAME ?? 'svelar_db',
      user: process.env.DB_USER ?? 'root',
      password: process.env.DB_PASSWORD ?? '',
    },
  },
});

Hash.configure({ driver: 'scrypt' });

And src/hooks.server.ts:

import { createSvelarApp } from '@beeblock/svelar/hooks';
import { DatabaseSessionStore } from '@beeblock/svelar/session';
import './app.js';

export const { handle, handleError } = createSvelarApp({
  secret: process.env.APP_KEY!,
  sessionStore: new DatabaseSessionStore(),  // requires the sessions migration
});

Note: Manual setup requires configuring Vite aliases for @beeblock/svelar/* submodules. Use npx @beeblock/svelar new to see the full vite.config.ts as reference.

CLI Commands

All commands available after installation:

# Project
npx @beeblock/svelar new <name>              # Scaffold new project (DDD modular structure)
npx @beeblock/svelar new <name> --flat       # Scaffold with flat folder structure
npm run ui:install                 # Install shadcn-svelte components after --no-install
npx svelar key:generate            # Generate a new APP_KEY
npx svelar key:generate --show     # Display key without writing
npx svelar key:generate --force    # Overwrite existing key

# Migrations
npx svelar migrate                 # Run pending migrations
npx svelar migrate --rollback      # Rollback last batch
npx svelar migrate --reset         # Rollback ALL
npx svelar migrate --refresh       # Reset + re-run all
npx svelar migrate --fresh         # Drop all tables + re-run
npx svelar migrate --status        # Show migration status
npx svelar migrate --seed          # Run seeders after migrating

# Seeding
npx svelar seed:run                # Run database seeders

# Code Generation — Full resource scaffold
npx svelar make:entity Invoice --module=billing --fields "title:string,total:number,status:enum(draft,paid)" --crud

# Code Generation — Domain modules (goes into layered src/lib/modules/<module>/ folders)
npx svelar make:model User --module=auth        # domain/models
npx svelar make:controller User --module=auth   # interface/http/controllers
npx svelar make:service Billing --module=billing --crud # CRUD Service
npx svelar make:repository User --module=auth   # infrastructure/repositories
npx svelar make:action CreateUser --module=auth --dto --request --schema  # action + boundaries
npx svelar make:request StoreUser --module=auth  # interface/http/requests
npx svelar make:resource User --module=auth     # interface/http/resources
npx svelar make:schema User --module=auth       # contracts/schemas
npx svelar make:observer UserObserver --model=User --module=auth  # domain/observers

# Code Generation — Routes
npx svelar make:route posts --api --resource -c PostController    # CRUD routes
npx svelar make:route admin/settings --api -m GET,PUT             # Custom methods
npx svelar routes:list                           # Show all routes
npx svelar routes:list --api                     # API routes only
npx svelar routes:list --method POST             # Filter by method

# Code Generation — Events
npx svelar make:event UserRegistered --module=auth               # domain/events
npx svelar make:listener SendWelcomeEmail --event=UserRegistered --module=auth  # application/listeners

# Code Generation — Shared (goes into src/lib/shared/<type>/)
npx svelar make:middleware RateLimit  # Middleware
npx svelar make:job SendWelcomeEmail  # Queue job
npx svelar make:task CleanupExpired   # Scheduled task
npx svelar make:command SyncUsers     # Custom CLI command
npx svelar make:plugin Stripe         # Plugin class
npx svelar make:provider App          # Service provider
npx svelar make:channel Order         # Broadcast channel (-p for presence)

# Code Generation — Database (goes into src/lib/database/)
npx svelar make:migration <Name>   # Migration file
npx svelar make:seeder <Name>      # Seeder class
npx svelar make:config <Name>      # Config file

# Scaffolding
npx svelar make:docker             # Docker deployment files
npx svelar make:broadcasting       # Broadcasting routes + client
npx svelar make:dashboard          # Admin dashboard routes

# Plugins
npx svelar plugin:list             # List plugins
npx svelar plugin:publish <name>   # Publish plugin config/migrations
npx svelar plugin:install <pkg>    # Install plugin from npm

# Runtime
npx svelar schedule:run            # Run scheduler
npx svelar queue:work              # Process queued jobs
npx svelar queue:failed            # List failed jobs
npx svelar queue:retry <id>        # Retry a failed job
npx svelar queue:retry --all       # Retry all failed jobs
npx svelar queue:flush             # Delete all failed job records
npx svelar tinker                  # Interactive REPL

Production safety: Destructive migration commands (--reset, --refresh, --fresh) are blocked in production unless you pass --force.

Runtime commands such as migrate, seed:run, queue:work, schedule:run, and tinker boot src/app.ts before running. Put framework configuration, queue registration, scheduler registration, and service setup in src/app.ts so CLI processes use the same application state as the web server.

Troubleshooting

"Cannot find module '@beeblock/svelar'"

npm install @beeblock/svelar

Database file not found

Check DB_PATH in your .env. Default is database.db in project root.

Migrations not running

Make sure src/app.ts is imported in src/hooks.server.ts:

import './app.js'; // Triggers database configuration

TypeScript errors with models

Add skipLibCheck: true to tsconfig.json:

{
  "compilerOptions": {
    "skipLibCheck": true
  }
}

Next Steps

• Database — Migrations, seeders, multiple drivers
• Models & ORM — Eloquent-style queries, relationships
• Controllers & Routing — Request handling
• Authentication — Sessions, JWT, API tokens
• Middleware — CORS, CSRF, rate limiting, custom middleware