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 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.

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

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/             #   User.ts, UserObserver.ts, AuthController.ts, AuthService.ts
│   │   │   ├── billing/          #   Invoice.ts, BillingService.ts, billing.schema.ts
│   │   │   └── posts/            #   Post.ts, PostController.ts, PostService.ts
│   │   ├── 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
│   │   ├── events/               # Event classes (npx svelar make:event)
│   │   ├── listeners/            # Listener classes (npx svelar make:listener)
│   │   └── 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/
├── vite.config.ts
├── svelte.config.js
├── svelar.database.json
├── .env.example
└── package.json

Each module is a self-contained domain — its model, controller, service, repository, observers, DTOs, and schema all live together. The shared/ folder holds cross-cutting infrastructure. The events/ and listeners/ folders hold application-wide event classes and their handlers.

Step 1: Environment Variables

If you used npx 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 svelar new
APP_KEY=<auto-generated>

# Database (SQLite by default, no extra config needed)
DB_DRIVER=sqlite
DB_PATH=database.db

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

# MySQL (uncomment to switch)
# DB_DRIVER=mysql2
# 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)
# 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.increments('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 --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

PM2 Processes

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: 'sqlite',
  connections: {
    sqlite: {
      driver: 'sqlite',
      filename: process.env.DB_PATH ?? 'database.db',
    },
  },
});

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(),  // auto-creates sessions table
});

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

CLI Commands

All commands available after installation:

# Project
npx svelar new <name>              # Scaffold new project (DDD modular structure)
npx svelar new <name> --flat       # Scaffold with flat folder structure
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 — Domain (goes into src/lib/modules/<module>/)
npx svelar make:model User --module=auth        # Model
npx svelar make:controller User --module=auth   # Controller
npx svelar make:service Billing --module=billing # Service (--crud)
npx svelar make:repository User --module=auth   # Repository (--model=X)
npx svelar make:action CreateUser --module=auth  # Action
npx svelar make:request StoreUser --module=auth  # FormRequest DTO
npx svelar make:resource User --module=auth     # API Resource (response)
npx svelar make:schema User --module=auth       # Contract schema (Zod + shared types)
npx svelar make:observer UserObserver --model=User --module=auth  # Model Observer

# 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 (goes into src/lib/modules/<module>/)
npx svelar make:event UserRegistered --module=auth               # Event class
npx svelar make:listener SendWelcomeEmail --event=UserRegistered --module=auth  # Listener class

# 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.

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