kemal - GitLite

KO | EN

gitlite — search

#react #ai #golang #android #machine-learning #deep-learning #linux #java #windows #cli #security #ios #openai #open-source

kemal

(★ 3,905)

Fast, Effective, Simple Web Framework

File Explorer

Download Latest Version (.zip)

- - ameba.yml
  - ci.yml
- FUNDING.yml
- ISSUE_TEMPLATE.md
- PULL_REQUEST_TEMPLATE.md
- - app.cr
- - app.cr
- - app.cr
- - app.cr
- - app.cr
- - app.cr
  - custom-handler.cr
- - app.cr
- - app.cr
- - app.cr
- - app.cr
- - app.cr
- - app.cr
- - app.cr
- - app.cr
- - app.cr
- - hello.ecr
  - hello_with_content_for.ecr
  - layout.ecr
  - layout_with_yield.ecr
  - layout_with_yield_and_vars.ecr
- - filters_spec.cr
- all_spec.cr
- cli_spec.cr
- config_spec.cr
- context_spec.cr
- event_stream_spec.cr
- exception_handler_spec.cr
- filters_spec.cr
- handler_spec.cr
- head_request_handler_spec.cr
- helpers_spec.cr
- init_handler_spec.cr
- log_handler_spec.cr
- override_method_handler_spec.cr
- param_parser_spec.cr
- path_handler_spec.cr
- request_log_handler_spec.cr
- response_helpers_spec.cr
- route_handler_spec.cr
- route_spec.cr
- router_spec.cr
- run_spec.cr
- spec_helper.cr
- static_file_handler_spec.cr
- upload_cleanup_spec.cr
- view_spec.cr
- websocket_handler_spec.cr
- - base_log_handler.cr
  - cli.cr
  - config.cr
  - dsl.cr
  - event_stream.cr
  - exception_handler.cr
  - file_upload.cr
  - filter_handler.cr
  - handler.cr
  - head_request_handler.cr
  - init_handler.cr
  - log_handler.cr
  - null_log_handler.cr
  - override_method_handler.cr
  - param_parser.cr
  - path_handler.cr
  - request_log_handler.cr
  - route.cr
  - route_handler.cr
  - router.cr
  - ssl.cr
  - static_file_handler.cr
  - websocket.cr
  - websocket_handler.cr
- kemal.cr
.gitattributes
.gitignore
CHANGELOG.md
CONTRIBUTING.md
LICENSE
README.md
SECURITY.md
shard.yml

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

[![Kemal](https://avatars3.githubusercontent.com/u/15321198?v=3&s=200)](http://kemalcr.com)

# Kemal - Fast, Effective, Simple Web Framework for Crystal

Build web applications and APIs with minimal code. 3.8k+ ⭐, 5M+ downloads since 2015.

[![Stars](https://img.shields.io/github/stars/kemalcr/kemal?style=flat-square&label=%20&color=gold)](https://github.com/kemalcr/kemal)
[![CI](https://github.com/kemalcr/kemal/actions/workflows/ci.yml/badge.svg?style=flat-square)](https://github.com/kemalcr/kemal/actions/workflows/ci.yml)
[![Release](https://img.shields.io/github/v/release/kemalcr/kemal?style=flat-square)](https://github.com/kemalcr/kemal/releases)
![Downloads](https://img.shields.io/badge/Downloads-5M%2B-gold?style=flat-square)
![Crystal](https://img.shields.io/badge/Crystal-1.19+-%23000?style=flat-square&logo=crystal)
[![License](https://img.shields.io/github/license/kemalcr/kemal?style=flat-square)](https://raw.githubusercontent.com/kemalcr/kemal/master/LICENSE)
![Built with Crystal](https://img.shields.io/badge/Built%20with-Crystal-776791?style=flat-square&logo=crystal)

---

## Quick Start

1. **Create a new project**
   ```bash
   crystal init app my-app
   cd my-app
   ```

2. **Add Kemal to `shard.yml`**
   ```yaml
   dependencies:
     kemal:
       github: kemalcr/kemal
   ```

3. **Write your app** - replace `src/my-app.cr` with:
   ```crystal
   require "kemal"

get "/" do
     "Hello World!"
   end

get "/api" do |env|
     env.response.content_type = "application/json"
     {status: "ok"}.to_json
   end

Kemal.run
   ```

4. **Install dependencies and run**
   ```bash
   shards install
   crystal run src/my-app.cr
   ```

Visit http://localhost:3000 - done in under a minute. 🚀

---

## Why Kemal?

| Problem | Solution |
|---------|----------|
| "I want C-level performance with Ruby-like syntax" | Crystal + Kemal - fast by default |
| "I need WebSocket support out of the box" | Built-in, no extra gems |
| "Building a JSON API" | Native JSON handling, minimal boilerplate |
| "I want a framework that stays out of my way" | No forced ORM, no magic, just Crystal |

---

## Key Features

- 🚀 **High-performance by default** - Built on Crystal with a thin abstraction layer
- 🌐 **Full REST & HTTP support** - All HTTP verbs with a straightforward routing DSL
- 🔌 **WebSocket & real-time** - First-class WebSocket support
- 📦 **JSON-first APIs** - Native JSON handling
- 🗄️ **Static assets** - Serve files efficiently from the same application
- 📝 **Template engine** - Built-in ECR template engine
- 🔒 **Composable middleware** - Logging, auth, rate limiting, metrics
- 🎯 **Ergonomic request/response** - Simple params, headers, cookies via context
- 🍪 **Session management** - Production-ready via kemal-session

---

## Performance

Kemal is built on Crystal. It compiles to native code and starts instantly.

| Test | Results |
|------|---------|
| **JSON serialization** (100 conn) | ~50,000 req/sec |
| **Hello World** (100 conn) | ~85,000 req/sec |
| **Static file serving** | ~40,000 req/sec |
| **Memory per request** | ~0.5 KB |
| **Binary size** | ~2 MB (with dependencies) |

No JVM, no Node, no Ruby VM. Just a native binary.

---

## How Kemal compares

| Feature | Kemal | Sinatra | Flask | Express |
|---------|:-----:|:-------:|:-----:|:-------:|
| **Performance** (req/sec) | ~85K | ~5K | ~3K | ~15K |
| **WebSocket** built-in | ✅ | - | - | - |
| **Single binary deploy** | ✅ | - | - | - |
| **JSON handling** | Native | Gem | Extension | Native |
| **Type safety** | ✅ | - | - | - |
| **Concurrency** | Fibers | Threads | Threads | Async |

---

## Philosophy

Kemal aims to be a simple, fast and reliable foundation for building production-grade web applications and APIs in Crystal.

- **Simple core, powerful building blocks** - The core is intentionally simple. Most power comes from Crystal and middleware, not hidden magic.
- **Performance as a baseline** - Crystal's native speed means high performance is the default. Kemal keeps abstractions thin.
- **Minimal assumptions, maximum flexibility** - No forced ORM, template engine, or project layout. Choose your own tools.
- **Batteries within reason** - Ships with essentials (routing, middleware, templates, static files) while keeping advanced concerns in separate shards.

---

## Learning Resources

- 📚 [Official Documentation](http://kemalcr.com)
- 💻 [Example Applications](https://github.com/kemalcr/kemal/tree/master/examples)
- 🚀 [Kemal Guide](http://kemalcr.com/guide/)
- 💻 [Kemal By Example](https://github.com/sdogruyol/kemal-by-example)
- 💬 [Community Chat](https://discord.gg/prSVAZJEpz)

---

## FAQ

**Is Kemal production ready?**

Yes. Kemal has been used in production since 2015 with 5M+ downloads.

**Does Kemal support WebSocket?**

Yes, built-in. No extra dependencies needed.

**Can I build a REST API with Kemal?**

Yes. JSON handling is built-in. Return hashes or JSON directly from routes.

**Does Kemal support the HTTP QUERY method?**

Yes. QUERY ([RFC 10008](https://www.rfc-editor.org/rfc/rfc10008)) is a safe, idempotent method that carries the query in the request body instead of the URL:

```crystal
query "/search" do |env|
  q = env.params.json["q"]? # or env.params.body for form-encoded queries
  search_products(q).to_json
end
```

`before_query` / `after_query` filters and `Kemal::Router#query` work like every other verb. A QUERY request that has a body but no `Content-Type` header is rejected with `400` per the RFC.

**Does Kemal work with any ORM?**

Yes. You can use any Crystal ORM or database library. No forced dependencies.

**How is Kemal different from Sinatra / Flask / Express?**

Kemal compiles to a native binary with Crystal. You get C-like performance, type safety, and single-binary deployment. Sinatra and Flask are interpreted. Express runs on Node's event loop.

---

## Sponsors

If Kemal helps you or your company, consider [sponsoring](https://github.com/sponsors/sdogruyol). Your support helps me maintain Kemal and build the Crystal ecosystem full time.

[![Sponsor](https://img.shields.io/badge/Sponsor-30363D?style=flat-square&logo=githubsponsors&logoColor=white)](https://github.com/sponsors/sdogruyol)

---

## Contributing

We love contributions! Please read our [Contributing Guide](CONTRIBUTING.md).

## Security

To report a security vulnerability, please see our [Security Policy](SECURITY.md).

---

## Acknowledgments

Special thanks to Manas for their work on [Frank](https://github.com/manastech/frank).

---

## License

MIT