Summon

⚠️ Alpha Status: Summon is currently in alpha development and actively seeking testers and feedback. While core functionality is stable, APIs may change between releases. We welcome early adopters and contributors! Please report issues and share your experience.

Summon is a powerful, type-safe frontend framework for Kotlin Multiplatform that brings the elegance of Jetpack Compose to both browser and JVM environments. Build beautiful, responsive applications with a declarative syntax that feels natural to Kotlin developers.

Project Structure

This monorepo contains:

• summon-core/ - The main Summon library
• summon-cli/ - Command-line tool for project generation
• docs/ - Documentation and guides

📝 Examples: Example projects showing various integrations have been moved to a separate repository for cleaner core library maintenance.

🎨 Type-safe styling with an intuitive modifier API inspired by Compose.

🧩 Component-based architecture for maximum reusability and maintainability.

🔄 Reactive state management that automatically updates your UI when data changes.

Summon combines the best ideas from modern frontend frameworks like React, Vue, and Next.js with the declarative UI patterns of Jetpack Compose and SwiftUI, while leveraging Kotlin's powerful type system to catch errors at compile time rather than runtime. Whether you're building a simple website or a complex web application, Summon provides the tools you need to create polished, professional user interfaces with less code and fewer bugs.

Features

• Cross-Platform: Build once, run on JavaScript, WebAssembly (WASM), and JVM platforms
• Component-Based: Create reusable UI components with a declarative syntax
• Type-Safe: Leverage Kotlin's type system for safer UI development with compile-time checks
• Enhanced Styling System:
  • Flexible and powerful styling using a comprehensive modifier API
  • Type-safe CSS properties with enum support for values like BorderStyle, Alignment, etc.
  • Numeric extensions for CSS units (px, rem, em, etc.) for cleaner code
  • Comprehensive gradient support with both linear and radial options
  • Extensive color system with Material Design and Catppuccin palettes
• Flexible Layout System:
  • Powerful flexbox layout with alignment controls
  • Row and Column components with intuitive alignment modifiers
  • Grid layout support with comprehensive controls
• State Management: Simple yet powerful reactive state management solutions
• Next.js-Style Routing: File-based routing with automatic page discovery and code generation
• Lifecycle Aware: Built-in lifecycle management with side effects and cleanup
• Framework Interoperability: Integrate with existing frameworks like Quarkus, Ktor, and Spring Boot
• Security: Comprehensive JWT authentication and role-based access control (RBAC)
• Accessibility: Built-in accessibility features with ARIA support for inclusive applications
• Animation and Transitions:
  • Smooth animations with keyframes support
  • CSS transitions with type-safe timing functions and properties
  • Transform operations for scaling, rotation, and translation
• Server-Side Rendering (SSR):
  • Complete SSR implementation with composition context management
  • State management during server rendering (remember, mutableStateOf)
  • SEO optimization with meta tags, OpenGraph, and Twitter Cards
  • Client-side hydration for interactive components
  • Production-ready performance handling 100+ components efficiently
• Enhanced Theme System:
  • Flexible theming with dark mode support
  • Type-safe theme properties for typography, spacing, colors, and more
  • Easy theme switching at runtime
• Internationalization: Full i18n support with RTL layouts for languages like Arabic and Hebrew
• WebAssembly (WASM) Support:
  • Native-like performance with near-zero startup time
  • Server-side rendering with seamless client-side hydration
  • Progressive enhancement with automatic JS fallback
  • Cross-browser compatibility and progressive loading
  • Production-ready WASM with optimized bundle sizes

What's New in 0.4.0.0

🚀 Major Release: Complete WebAssembly Integration

This release introduces comprehensive WebAssembly support, bringing near-native performance to web applications while maintaining full SSR compatibility:

✨ WebAssembly Features

• Complete WASM Target Support: Full Kotlin/WASM compilation with all platform features
• Server-Side Rendering: WASM applications with SSR for optimal SEO and performance
• Progressive Enhancement: Automatic fallback to JavaScript when WASM is not supported
• Browser Compatibility: Intelligent browser detection with graceful degradation
• Optimized Performance: Near-native execution speed with minimal bundle overhead
• Seamless Hydration: Client-side hydration maintains state and interactivity

🔧 Technical Improvements

• Enhanced Build System: Complete WASM compilation pipeline with webpack integration
• Cross-Platform APIs: Unified APIs working seamlessly across JS, WASM, and JVM
• Error Handling: Comprehensive error boundaries and fallback mechanisms
• Bundle Optimization: Code splitting and lazy loading for optimal performance
• Development Tools: Enhanced CLI with WASM project templates and build tools

📦 Platform Targets

• WASM-JS: Primary WebAssembly target for modern browsers
• JavaScript: Fallback target for compatibility and development
• JVM: Server-side rendering and backend integration

Previous enhancements included in this release:

• Enhanced Theme System with typed theme classes for more type-safe access
• Improved Modifier API with type-safe CSS properties and enum support
• Comprehensive Border API with support for individual sides and properties
• Enhanced Flexbox Layout with alignment controls for Row and Column components
• Extensive Color System with Material Design and Catppuccin palettes
• Gradient Support for both linear and radial gradients with flexible options
• Animation Enhancements with keyframes and transition support
• Comprehensive Documentation with WASM integration guides and examples

Component Categories

Summon provides a comprehensive set of UI components organized into logical categories:

Input Components

• TextField - Single-line text input
• TextArea - Multi-line text input
• Button - Clickable button with various styles
• Checkbox - Checkbox input with label
• RadioButton - Radio button for single selection
• Switch - Toggle switch component
• Select - Dropdown selection component
• Slider - Single value slider
• RangeSlider - Dual-handle range slider
• DatePicker - Date selection component
• TimePicker - Time selection component
• FileUpload - File upload with drag & drop support
• Form & FormField - Form management components

Layout Components

• Row - Horizontal layout with alignment controls
• Column - Vertical layout with alignment controls
• Box - Container with positioning capabilities
• Grid - CSS Grid layout component
• Spacer - Flexible spacing component
• Divider - Visual separator
• Card - Elevated container with shadow
• AspectRatio - Maintains aspect ratio for content
• ExpansionPanel - Collapsible/expandable panel
• LazyColumn & LazyRow - Virtualized lists for performance
• ResponsiveLayout - Responsive layout utilities

Display Components

• Text - Text display with styling
• Image - Image display component
• Icon - Icon component with various sources
• Badge - Small status indicator

Feedback Components

• Alert - Dismissible alert messages
• Modal - Dialog system with variants (DEFAULT, ALERT, CONFIRMATION, FULLSCREEN) and sizes
• Loading & LoadingOverlay - Loading indicators with multiple animation types (SPINNER, DOTS, LINEAR, CIRCULAR)
• Toast & ToastManager - Notification system with positioning and action support
• Snackbar & SnackbarHost - Temporary notifications
• Progress & ProgressBar - Progress indicators
• Tooltip - Hover tooltips

Navigation Components

• Link - Navigation links
• TabLayout - Tab-based navigation

Utility Components

• Div - Basic container element
• AccessibleElement - Accessibility wrapper

Network and Communication

• WebSocket - Cross-platform WebSocket with auto-reconnection and lifecycle management
• HttpClient - Comprehensive HTTP client with JSON and form data support
• Storage - Local, session, and memory storage abstraction with TypedStorage wrapper

Inspiration

Summon is proudly inspired by Kobweb, a modern framework for full stack web apps in Kotlin built upon Compose HTML. Kobweb's elegant API design and approach to creating web applications using Kotlin has been instrumental in shaping Summon's philosophy. We highly recommend checking out Kobweb if you're looking for a mature, feature-rich solution for Kotlin web development.

Documentation

For detailed documentation, please check the docs directory:

• Components - Learn about Summon's built-in UI components
• Routing - Set up navigation in your application with Next.js-style file-based routing
• File-Based Routing - Next.js-style file-based routing system
• State Management - Manage application state effectively
• Styling - Apply styles to your components
• Integration Guides - Integrate with existing frameworks
• Security - Authentication and authorization features
• Accessibility and SEO - Build accessible and SEO-friendly applications
• Internationalization - Add multi-language support with RTL layouts

API Reference

Comprehensive API reference documentation is available in the docs/api-reference directory:

• Core API - Core interfaces and classes
• Components API - Built-in UI components
• Modifier API - Styling and layout modifiers
• State API - State management utilities
• Routing API - Navigation and routing
• Effects API - Side effects and lifecycle management
• Events API - Event handling and listeners
• Animation API - Animations, transitions, and keyframes
• Theme API - Theming and styling system
• Color API - Color system with Material Design and Catppuccin palettes
• Focus Management API - Focus management and keyboard navigation
• Validation API - Form validation and input validation
• Security API - Security features and access control
• Authentication API - Authentication providers and JWT integration
• Accessibility API - Accessibility features and ARIA support
• SEO API - SEO features and meta tags
• Internationalization API - Multi-language and RTL layout support

Installation

Add Summon to your project dependencies from Maven Central:

repositories {
    mavenCentral()
}

dependencies {
    // For JVM projects (Ktor, Spring Boot, Quarkus)
    implementation("io.github.codeyousef:summon-jvm:0.4.0.0")

    // For JavaScript/Browser projects
    implementation("io.github.codeyousef:summon-js:0.4.0.0")

    // For WebAssembly projects
    implementation("io.github.codeyousef:summon-wasm-js:0.4.0.0")

    // For Kotlin Multiplatform projects (includes all targets)
    implementation("io.github.codeyousef:summon:0.4.0.0")
}

Note: No authentication required - Summon is available directly from Maven Central!

Version Management

Summon uses a centralized version management approach to ensure consistency across the main project and example projects. The version information is defined in a single place and referenced from all other places.

For more information, see VERSIONING.md.

Security Best Practices

Protecting Sensitive Credentials

To prevent accidentally committing sensitive credentials to the repository, Summon includes a Git pre-commit hook that checks for actual credentials in gradle.properties.

Installing the Git Hook

1. Windows:

   .git-hooks\install-hooks.bat
   

2. Unix/Linux/macOS:

   chmod +x .git-hooks/install-hooks.sh
   .git-hooks/install-hooks.sh
   

The pre-commit hook will prevent commits that contain actual credentials (not placeholders) in gradle.properties.

Recommended Approach for Credentials

For local development:

1. Keep placeholder values in gradle.properties (which is version controlled):

   # No authentication needed - using Maven Central

2. Store your actual credentials in local.properties (which is ignored by Git):

   # No authentication needed - using Maven Central

3. In your build script, prioritize values from local.properties over gradle.properties:

   val localProperties = java.util.Properties().apply {
       val localFile = rootProject.file("local.properties")
       if (localFile.exists()) {
           load(localFile.inputStream())
       }
   }
   
   // No authentication needed when using Maven Central
   // repositories { mavenCentral() }

This approach ensures that sensitive credentials are never committed to version control while maintaining a clear example of what credentials are needed in the version-controlled gradle.properties file.

WebAssembly (WASM) Support

Summon 0.4.0.0 introduces comprehensive WebAssembly support, bringing near-native performance to web applications while maintaining full compatibility with server-side rendering and JavaScript fallbacks.

Getting Started with WASM

Create a new WASM project using the Summon CLI:

# Install Summon CLI
npm install -g @summon/cli

# Create a new WASM project
summon init my-wasm-app --template=wasm

# Or add WASM to an existing project
summon generate wasm-config

Basic WASM Application

// src/wasmJsMain/kotlin/Main.kt
import code.yousef.summon.annotation.Composable
import code.yousef.summon.components.display.Text
import code.yousef.summon.components.input.Button
import code.yousef.summon.components.layout.Column
import code.yousef.summon.modifier.Modifier
import code.yousef.summon.runtime.wasmMain
import code.yousef.summon.state.mutableStateOf
import code.yousef.summon.runtime.remember

@Composable
fun App() {
    val counter = remember { mutableStateOf(0) }

    Column(modifier = Modifier()) {
        Text("WASM Counter: ${counter.value}", modifier = Modifier())
        Button(
            onClick = { counter.value++ },
            label = "Increment",
            modifier = Modifier()
        )
    }
}

fun main() {
    wasmMain {
        App()
    }
}

WASM Features

🚀 Performance Benefits

• Near-Native Speed: Execute at 95%+ of native performance
• Minimal Startup Time: Sub-100ms initialization
• Memory Efficiency: Precise garbage collection and memory management
• Bundle Optimization: Tree-shaking and dead code elimination

🌐 Browser Compatibility

• Progressive Enhancement: Automatic fallback to JavaScript
• Browser Detection: Smart feature detection and capability assessment
• Polyfill Support: Seamless compatibility across browser versions
• Mobile Optimization: Optimized for mobile browsers and PWA

🔄 SSR Integration

• Seamless Hydration: Server-rendered content enhanced with WASM interactivity
• SEO Compatibility: Full search engine crawling with enhanced performance
• State Synchronization: Server state automatically synced to WASM client
• Progressive Loading: Initial content renders immediately, WASM loads in background

WASM Build Configuration

// build.gradle.kts
kotlin {
    wasmJs {
        moduleName = "my-wasm-app"
        browser {
            commonWebpackConfig {
                outputFileName = "my-wasm-app.js"
            }
        }
        binaries.executable()
    }
}

dependencies {
    implementation("io.github.codeyousef:summon-wasm-js:0.4.0.0")
}

Production Deployment

<!-- index.html -->
<!DOCTYPE html>
<html>
<head>
    <meta charset="UTF-8">
    <title>My WASM App</title>
</head>
<body>
<div id="root">
    <!-- Server-rendered content for SEO -->
    <div>Loading...</div>
</div>

<!-- Progressive WASM loading with JS fallback -->
<script src="wasm-loader.js"></script>
</body>
</html>

Performance Comparison

Platform	Bundle Size	Load Time	Runtime Performance
WASM	~450KB	~80ms	~95% native
JavaScript	~380KB	~120ms	~60% native
JVM	N/A	N/A	~100% native

WASM Development Tools

The Summon CLI provides comprehensive WASM development tools:

# Build WASM for development
summon build --target=wasm --mode=development

# Build optimized WASM for production
summon build --target=wasm --mode=production

# Run WASM development server with hot reload
summon dev --target=wasm

# Analyze WASM bundle size and performance
summon analyze --target=wasm

Server-Side Rendering (SSR)

Summon provides production-ready Server-Side Rendering capabilities for improved SEO, faster initial page loads, and better user experience. The SSR implementation includes full composition context management, state handling, and client-side hydration.

Basic SSR Usage

import code.yousef.summon.annotation.Composable
import code.yousef.summon.components.display.Text
import code.yousef.summon.components.layout.Column
import code.yousef.summon.modifier.Modifier
import code.yousef.summon.runtime.PlatformRenderer
import code.yousef.summon.runtime.remember
import code.yousef.summon.state.mutableStateOf

// Create a renderer instance
val renderer = PlatformRenderer()

@Composable
fun MyApp() {
    val counter = remember { mutableStateOf(0) }
    
    Column(modifier = Modifier()) {
        Text("Server-Rendered Counter: ${counter.value}", modifier = Modifier())
        Text("This content is generated on the server!", modifier = Modifier())
    }
}

// Render to HTML string
val html = renderer.renderComposableRoot {
    MyApp()
}

// The generated HTML includes proper document structure:
// <!DOCTYPE html>
// <html>
//   <head>...</head>
//   <body>
//     <div>Server-Rendered Counter: 0</div>
//     <div>This content is generated on the server!</div>
//   </body>
// </html>

Advanced SSR with SEO and Hydration

import code.yousef.summon.ssr.*

// High-level utility for complete page rendering
val html = ServerSideRenderUtils.renderPageToString(
    rootComposable = { MyApp() },
    initialData = mapOf("userId" to "123", "theme" to "dark"),
    includeHydrationScript = true
)

// With custom SEO metadata
val context = RenderContext(
    enableHydration = true,
    seoMetadata = SeoMetadata(
        title = "My Awesome App",
        description = "A server-rendered Kotlin app built with Summon",
        keywords = listOf("kotlin", "ssr", "web", "multiplatform"),
        openGraph = OpenGraphMetadata(
            title = "My Awesome App",
            description = "Server-side rendered with Summon",
            type = "website",
            url = "https://myapp.com",
            image = "https://myapp.com/og-image.jpg"
        )
    )
)

val seoOptimizedHtml = renderer.renderComposableRootWithHydration {
    MyApp()
}

Real-World SSR Examples

E-commerce Product Page

@Composable
fun ProductPage(productId: String) {
    val product = remember { mutableStateOf(loadProduct(productId)) }
    val cartItems = remember { mutableStateOf(0) }
    
    Column(modifier = Modifier()) {
        Text("${product.value.name}", modifier = Modifier())
        Text("$${product.value.price}", modifier = Modifier())
        
        Button(
            onClick = { cartItems.value += 1 },
            label = "Add to Cart (${cartItems.value})",
            modifier = Modifier()
        )
    }
}

Blog Post with Comments

@Composable
fun BlogPost(postId: String) {
    val post = remember { mutableStateOf(loadBlogPost(postId)) }
    val comments = remember { mutableStateOf(loadComments(postId)) }
    
    Column(modifier = Modifier()) {
        Text(post.value.title, modifier = Modifier())
        Text(post.value.content, modifier = Modifier())
        
        Text("Comments (${comments.value.size})", modifier = Modifier())
        comments.value.forEach { comment ->
            Text("${comment.author}: ${comment.text}", modifier = Modifier())
        }
    }
}

SSR Benefits

• SEO Optimization: Search engines can crawl your content immediately
• Faster Initial Load: Users see content before JavaScript loads
• Better Performance: Especially on slow devices and networks
• Improved Accessibility: Content is available even if JavaScript fails
• Social Media Sharing: Rich previews with OpenGraph metadata

Framework Integration

SSR works seamlessly with popular JVM frameworks:

• Ktor: Integrate with routing and HTML responses
• Spring Boot: Use with WebFlux and Thymeleaf templates
• Quarkus: Combine with Qute templates and reactive endpoints

See our integration guides for detailed framework-specific examples.

For maintainers: Publishing instructions are available at docs/private/publishing.md.

WASM Implementation Inspiration

Summon's WebAssembly implementation was inspired by and built upon the excellent work of several pioneering projects in the Kotlin/WASM ecosystem:

🌟 Spring Petclinic - sdeleuze/spring-petclinic

Trailblazing Kotlin/WASM with Server-Side Rendering

The Spring Petclinic project by Sébastien Deleuze was groundbreaking in demonstrating that Kotlin/WASM could work seamlessly with server-side rendering, maintaining SEO compatibility while delivering native-like performance. This project proved that WASM doesn't break SEO - a critical insight that shaped Summon's architecture.

Key inspirations:

• SSR + WASM hydration patterns
• Browser compatibility strategies
• Performance optimization techniques
• SEO preservation methods

🚀 Kilua Framework - rjaros/kilua

First Production-Ready Kotlin/WASM Framework with True SSR

Kilua by Robert Jaros stands as the first comprehensive Kotlin/WASM framework to achieve true server-side rendering capabilities. Its innovative approach to component architecture and state management provided crucial insights for Summon's design.

Key inspirations:

• Component lifecycle management
• State synchronization between server and client
• Type-safe DOM manipulation
• Progressive enhancement patterns

🔧 kotlinx-browser - Kotlin/kotlinx-browser

Foundation for Browser API Access

The official Kotlin browser API library provides the fundamental building blocks for WASM browser interaction. Summon builds upon this solid foundation to provide higher-level abstractions while maintaining full compatibility.

Key contributions:

• WASM-compatible DOM APIs
• Event handling abstractions
• Browser feature detection
• Cross-platform browser compatibility

🎯 kotlinx.html - Kotlin/kotlinx.html

Type-Safe HTML Generation

The kotlinx.html library's approach to type-safe HTML generation inspired Summon's component model and server-side rendering capabilities. Its elegant DSL design influenced Summon's declarative syntax.

Key inspirations:

• Type-safe HTML DSL patterns
• Component composition models
• Server-side HTML generation
• Build-time safety guarantees

🙏 Acknowledgments

Summon stands on the shoulders of these giants. Without their pioneering work, research, and open-source contributions, Summon's WASM implementation would not have been possible. We are deeply grateful to:

• Sébastien Deleuze for proving WASM + SSR viability
• Robert Jaros for creating the first production-ready framework
• The Kotlin Team for providing robust browser APIs and HTML DSL
• The broader Kotlin/WASM community for pushing the boundaries of what's possible

🔗 Related Resources

• Kotlin/WASM Documentation
• WebAssembly Specification
• Compose Multiplatform

🎉 Contributing to the Ecosystem

Summon aims to give back to the Kotlin/WASM community by:

• Sharing implementation techniques and patterns
• Contributing to upstream projects where appropriate
• Documenting lessons learned and best practices
• Supporting other developers building WASM applications

Together, we're building the future of web development with Kotlin! 🚀