File: README.md Copy Chapter

News

🚀 Iris v14 is on the way. The next major version is the largest release in the project's history: the framework rebuilt on Go generics, an application builder the compiler checks, request helpers that validate for you, one central error map, thirty built-in middleware and a book that ships inside the repository. See what is coming in Iris v14 below.

The version you are reading about here, v12, keeps working and keeps getting fixes. v14 arrives on a new import path, so nothing on your side breaks the day it lands.

[](https://iris-go.com) Iris Web Framework [](README_GR.md) [](README_JA.md) [](README_FR.md) [](README_ZH_HANT.md) [](README_ZH_HANS.md) [](README_ES.md) [](README_FA.md) [](README_RU.md) [](README_KO.md) [](README_PT_BR.md) [](README_VN.md) [العربية](README_AR.md)

⚡ Iris is a fast, simple yet fully featured and very efficient web framework for Go.

✨ It provides a beautifully expressive and easy to use foundation for your next website or API.

🌟 Learn what others say about Iris and star this open-source project

package main

import "github.com/kataras/iris/v12"

func main() {
  app := iris.New()
  app.Use(iris.Compression)

  app.Get("/", func(ctx iris.Context) {
    ctx.HTML("Hello **%s**!", "World")
  })

  app.Listen(":8080")
}

As one Go developer once said, Iris got you covered all-round and standing strong over the years ⭐

Some of the features Iris offers:

• HTTP/2 (Push, even Embedded data)
• Middleware (Accesslog, Basicauth, CORS, gRPC, Anti-Bot hCaptcha, JWT, MethodOverride, ModRevision, Monitor, PPROF, Ratelimit, Anti-Bot reCaptcha, Recovery, RequestID, Rewrite)
• API Versioning
• Model-View-Controller
• Websockets
• gRPC
• Auto-HTTPS
• Builtin support for ngrok to put your app on the internet, the fastest way
• Unique Router with dynamic path as parameter with standard types like :uuid, :string, :int... and the ability to create your own
• Compression
• View Engines (HTML, Django, Handlebars, Pug/Jade and more)
• Create your own File Server and host your own WebDAV server
• Cache
• Localization (i18n, sitemap)
• Sessions
• Rich Responses (HTML, Text, Markdown, XML, YAML, Binary, JSON, JSONP, Protocol Buffers, MessagePack, Content Negotiation, Streaming, Server-Sent Events and more)
• Response Compression (gzip, deflate, brotli, snappy, s2)
• Rich Requests (Bind URL Query, Headers, Form, Text, XML, YAML, Binary, JSON, Validation, Protocol Buffers, MessagePack and more)
• Dependency Injection (MVC, Handlers, API Routers)
• Testing Suite
• And the most important... you get fast answers and support, from the first day until now

🚀 What is coming in Iris v14 Copy Chapter

Iris v14 is the largest release in the project's history. It rebuilds the framework on Go generics and changes how an application is put together: less wiring in main, shorter handlers, and one place for the decisions that used to be scattered across every route.

None of it needs your attention today. v12 keeps working, keeps getting fixes, and v14 arrives with a migration guide that covers every renamed and removed API.

The whole application in one compile-checked chain Copy Section

iris.NewBuilder wires CORS, compression, access logging, the health endpoint, the error map, your services and your API groups in a single expression. The compiler enforces the step order, so an application either builds correctly or does not build at all.

iris.NewBuilder().
    Prefix("/api").
    AllowOrigin("*").
    Compression(true).
    LogRequests(true).
    Health(true, "production", "kataras").
    Errors(errors.NewOptions().
        MapErrors(errors.NotFound, catalog.ErrNotFound)).
    Services(catalog.NewRepository, catalog.NewService).
    API("/products", api.NewProductsAPI).
    Build().
    Listen(":8080")

Handlers stop repeating themselves Copy Section

Decoding, validation and error rendering move out of the handler body. rest.ReadJSON[T] decodes the request, runs the type's Validate() error when it has one, and writes the 400 itself. The response helpers write the success status, or whatever your central map says that error should return.

func (api *ProductsAPI) create(ctx iris.Context) {
    input, ok := rest.ReadJSON[catalog.ProductInput](ctx)
    if !ok {
        return // 400 already written: malformed JSON or failed Validate.
    }

    id, err := api.svc.Create(ctx, input)
    rest.Created(ctx, id, err) // 201, or the centrally mapped error.
}

rest.OK, rest.NoContent, rest.Count and rest.Paginated cover the rest of the shapes an API returns.

Errors are declared once Copy Section

The new rest/errors package holds the mapping from your domain errors to HTTP responses. Clients get canonical, machine-readable payloads. Internal messages stay internal. Register a collector and every failure reaches your logger or your database from a single place. An error can render as JSON or as a view, depending on what the client asked for.

Dependency injection everywhere, not only in MVC Copy Section

Constructors declare what they need and the container provides it: for handlers, for API groups, for controllers. A service that implements Init(ctx context.Context) error runs once inside Build(). Anything closeable is closed at shutdown. The hero package is gone, replaced by dep and rest, which do more in fewer lines. MVC controllers are built on generics.

The packages are where you would expect them Copy Section

sessions, cache, websocket, i18n, view and versioning became middleware. mvc moved under controller, next to the new fileserver, sitemap and apigraph controllers. apigraph renders your route tree as an interactive D3 graph.

Thirty middleware ship in the box, including new ones: httpcost (time, memory and CPU per request, for performance work or billing), bodylimit, compress, counter, referrer, geolocation, ipaccess and servertiming. View engine implementations moved to iris-contrib/views.

Configuration is a partial literal Copy Section

iris.Configuration and the With* configurators are replaced by iris.Options. Set the fields you care about and the rest come from the defaults. Bind loads YAML from the SERVER_CONFIG environment variable, then from a file.

app := iris.New(iris.Options{Name: "myapp", LogLevel: "debug"})

Names that say what they do Copy Section

Reading a request header and setting a response header no longer share a prefix that quietly flips meaning: ctx.Header reads the request, ctx.SetHeader and ctx.ResponseHeader work on the response. Party is now Router. ctx.URLParam is now ctx.Query().Get. Every rename is listed in the migration guide with its replacement, and most are one search and replace.

Secure by default Copy Section

Session cookies ship with Secure and SameSite=Lax. The request body limit is enforced on every read path. Long-standing bugs went down with the rebuild, among them a rate limiter that recorded limits without ever enforcing them and a Logout call that could take the process with it.

Documentation you can read start to finish Copy Section

v14 comes with a book of 23 chapters inside the repository, a getting started tutorial that builds a tested REST API in one document, a migration guide for v12 applications, and a live AI wiki generated from the source that answers questions about the codebase.

What it means for your v12 code Copy Section

The import path becomes github.com/kataras/iris/v14, so v12 and v14 can sit side by side and nothing breaks on release day. Upgrade when it suits you. The migration guide covers the import path, the package moves, every removed API and its replacement, and the behavior changes, with ready commands for the mechanical parts.

There is no public release date yet. Watch releases or follow @iris_framework to hear about it first.

👑 [Supporters](https://iris-go.com/donate) Copy Chapter

With your help, we can improve Open Source web development for everyone!

📖 Learning Iris Copy Chapter

Installation Copy Section

The only requirement is the Go Programming Language.

Create a new project

$ mkdir myapp
$ cd myapp
$ go mod init myapp
$ go get github.com/kataras/iris/v12@latest # or @v12.2.11

Install on existing project

$ cd myapp
$ go get github.com/kataras/iris/v12@latest

Run

$ go mod tidy -compat=1.23 # -compat="1.23" for windows.
$ go run .

Iris contains extensive and thorough documentation making it easy to get started with the framework.

For a more detailed technical documentation you can head over to our godocs. And for executable code you can always visit the ./_examples repository's subdirectory.

Develop with Plexon AI Copy Section

Plexon AI is a cross-platform AI coding assistant from Hellenic Development, and it ships with a dedicated Iris skill: a v14 development guide written by the framework's author, with nineteen reference documents covering routing and macros, the context API, the rest helpers, error handling, all thirty middleware, the built-in controllers, the authentication SDK, security hardening, persistence, caching, i18n, observability, performance, testing, deployment, and the v12 to v14 migration.

Install the Software Developer persona and the Iris skill comes with it, alongside the engineering agents it activates. Your assistant then writes Iris code the way the framework is meant to be used, instead of guessing from whatever it picked up in training.

Do you like to read while traveling? Copy Section

You can request a PDF and online access of the Iris E-Book (New Edition) today and take part in the development of Iris.

🙌 Contributing Copy Chapter

We'd love to see your contribution to the Iris Web Framework! For more information about contributing to the Iris project please check the CONTRIBUTING.md file.

List of all Contributors

🛡 Security Vulnerabilities Copy Chapter

If you discover a security vulnerability within Iris, please send an e-mail to [email protected]. All security vulnerabilities will be promptly addressed.

📝 License Copy Chapter

This project is licensed under the BSD 3-clause license, just like the Go project itself.

The project name "Iris" was inspired by the Greek mythology.

File: _benchmarks/view/README.md Copy Chapter

View Engine Benchmarks

Benchmark between all 7 supported template parsers.

Ace and Pug parsers minifies the template before render. So, to have a fair benchmark, we must make sure that the byte amount of the total response body is exactly the same across all. Therefore, all other template files are minified too.

Last updated: Mar 17, 2023 at 10:31am (UTC)

System Copy Chapter

Terminology Copy Chapter

Name is the name of the framework(or router) used under a particular test.

Reqs/sec is the avg number of total requests could be processed per second (the higher the better).

Latency is the amount of time it takes from when a request is made by the client to the time it takes for the response to get back to that client (the smaller the better).

Throughput is the rate of production or the rate at which data are transferred (the higher the better, it depends from response length (body + headers).

Time To Complete is the total time (in seconds) the test completed (the smaller the better).

Results Copy Chapter

Test:Template Layout, Partial and Data Copy Section

📖 Fires 1000000 requests with 125 concurrent clients. It receives HTML response. The server handler sets some template data and renders a template file which consists of a layout and a partial footer.

How to Run Copy Chapter

$ go install github.com/kataras/server-benchmarks@master
$ go install github.com/codesenberg/bombardier@master
$ server-benchmarks --wait-run=3s -o ./results

File: _benchmarks/README.md Copy Chapter

Benchmarks

• HTTP/2 Benchmarks
• View Engine Benchmarks

File: _examples/mvc/repository/models/README.md Copy Chapter

Domain Models

There should be the domain/business-level models.

Example:

import "github.com/kataras/iris/v12/_examples/mvc/repository/datamodels"

type Movie struct {
    datamodels.Movie
}

func (m Movie) Validate() (Movie, error) {
    /* do some checks and return an error if that Movie is not valid */
}

However, we will use the "datamodels" as the only one models package because
Movie structure we don't need any extra functionality or validation inside it.

File: _examples/mvc/repository/repositories/README.md Copy Chapter

Repositories

The package which has direct access to the "datasource" and can manipulate data directly.

File: _examples/mvc/repository/services/README.md Copy Chapter

Service Layer

The package which has access to call functions from the "repositories" and "models" ("datamodels" only in that simple example). It should contain the domain logic.