Chapter 1: Getting Started with Kungfu.js in Go

Welcome! This tutorial will take you from complete beginner to professional level with Kungfu.js. By the end of these 50 chapters, you will know how to build, secure, test, and deploy production-grade web applications.

What is Kungfu.js?

Kungfu.js is a polyglot web framework built with a Rust core. The word "polyglot" means it can speak many languages. You can write your backend logic in Go, Rust, Python, Go, PHP, Ruby, or any of the 16 supported languages, while the heavy lifting (HTTP parsing, routing, security) runs in Rust for maximum speed.

Think of it like a restaurant kitchen. The head chef (Rust) handles the dangerous, high-precision work: managing the stove, cutting ingredients, timing everything perfectly. You (the Go developer) write the recipes and decide what dishes to serve. The chef executes your recipes at top speed.

Why choose Kungfu.js over other frameworks?

Here is a comparison to help you understand where Kungfu.js fits:

  • vs Express.js: Express is JavaScript only. Kungfu.js lets you write in Go. Express needs middleware for security. Kungfu.js has it built in. Express does ~80k req/s. Kungfu.js does ~86k+ req/s on the same hardware.
  • vs Next.js: Next.js is full-stack but requires JavaScript everywhere. Kungfu.js lets your backend be in Go while keeping the frontend in JS/TS. Kungfu.js also has a built-in CSS engine, so no Tailwind config needed.
  • vs FastAPI: FastAPI is Python only. Kungfu.js lets you use Go but runs the server in Rust, making it 10 to 50 times faster than FastAPI on the same hardware.
  • vs Actix: Actix is Rust only. Kungfu.js gives you the same Rust performance but with a simpler API and support for Go.

What you will learn in this tutorial

Over the next 50 chapters, you will learn:

  1. How to install and set up Kungfu.js (chapters 1 to 4)
  2. Routing: static paths, parameters, wildcards, query strings (chapters 5 to 10)
  3. Middleware: built-in security, custom logic, execution order (chapters 11 to 14)
  4. Request and Response handling: JSON, forms, file uploads, cookies (chapters 15 to 20)
  5. Database and ORM: models, CRUD, transactions, migrations, JOINs (chapters 21 to 30)
  6. Authentication: passwords, JWT, sessions, RBAC, OAuth2 (chapters 31 to 35)
  7. Real-time: WebSocket chat app (chapters 36 to 37)
  8. Frontend: CSS engine, SSR, hydration, file routing, live reload (chapters 38 to 44)
  9. Production: OpenAPI docs, error handling, testing, performance, deployment (chapters 45 to 50)

Prerequisites

Before we start, make sure you have the following:

You need Go 1.21+.

Install Kungfu.js

Install the Go package for Kungfu.js:

go get github.com/Resolutefemi/kungfu/bindings/go

Your First Application

Let us build a simple server that responds to HTTP requests. Create a new file and paste this code:

package main
import "github.com/Resolutefemi/kungfu/bindings/go/kungfu"

func main() {
    app := kungfu.New()
    app.Get("/hello", func(w kungfu.ResponseWriter, r *kungfu.Request) {
        w.Text(200, "world")
    })
    app.Run(":3000")
}

Run the Server

Now run your application:

go run main.go

Open your browser and visit http://localhost:3000/hello. You should see the text "world".

What Just Happened? Let Us Break It Down

Here is what happened when you ran that code, step by step:

  1. You created a Kungfu application. This initialized the Rust HTTP server engine, which will handle all network communication.
  2. You registered a route. You told the router: "When someone sends a GET request to /hello, run this function." The router stored this in a trie data structure for fast lookup.
  3. You started the server. The Rust core bound to port 3000 on your machine and started listening for TCP connections.
  4. A request came in. When you visited the URL, your browser sent an HTTP GET request to /hello. The Rust core parsed the raw bytes of the request, extracted the method (GET) and path (/hello), and looked them up in the trie router.
  5. Your handler ran. The router found your function and called it. Your function returned a response saying "world".
  6. The response was sent. The Rust core formatted your response into valid HTTP bytes and sent them back to the browser. It also added security headers (HSTS, CSP, X-Frame-Options), CORS headers, and a rate limit check, all automatically.

Try This: Check the Headers

Run this command in your terminal to see the full HTTP response with headers:

curl -i http://localhost:3000/hello

You will see something like this:

HTTP/1.1 200 OK
strict-transport-security: max-age=63072000; includeSubDomains; preload
content-security-policy: default-src 'self'; ...
x-frame-options: DENY
x-content-type-options: nosniff
server: kungfu/1.0.0
content-length: 5

world

Notice all those security headers? You did not configure any of them. Kungfu.js adds them automatically because security should be the default, not an option.

Auto-Generated API Documentation

Visit http://localhost:3000/docs in your browser. You will see a Swagger UI page listing your /hello endpoint. This is auto-generated from your route registrations. No annotations or configuration needed.

Common Mistakes Beginners Make

  • Forgetting to call listen(): If you do not call listen(3000), the server never starts. Always end your setup with listen().
  • Using the wrong port: Port 3000 is the default, but if another app is using it, you will get an error. Try 3001, 8080, or 9000.
  • Not handling errors: In production, always handle errors gracefully. We will cover this in chapter 46.

Package Information

Package name: github.com/Resolutefemi/kungfu/bindings/go
Registry: pkg.go.dev
File extension: .go

What is Next?

In chapter 2, we will do a deep dive into installation and configuration for your specific operating system and language. We will cover troubleshooting common install issues, setting up your development environment, and configuring your project for maximum productivity.

Next: Installation Deep Dive