DEV Community: Ravi Kishan

RustDNS: Writing a Recursive DNS Resolver in Rust, Byte by Byte

Ravi Kishan — Tue, 06 Oct 2026 15:31:56 +0000

TL;DR: RustDNS is a recursive DNS resolver written in plain Rust with zero dependencies, just std::net::UdpSocket and a 512-byte array. It parses DNS packets by hand, follows compression pointers, starts every lookup at a root server and walks the tree down to the answer, then serves that answer to dig on port 2053. This post goes through the code byte by byte, and then through what broke when I ran it against the real internet.
git clone https://github.com/ravikisha/rustdns && cd rustdns
cargo run --release
🔗 GitHub · 🐛 Issues

Why I built this
DNS in two minutes
Hello, resolver
The map of the code
A 512-byte cursor
Twelve bytes of header
Names, labels and compression pointers
One enum per record type
Walking the tree: recursive resolution
Serving dig on port 2053
Breaking it on purpose
How fast is it?
What I learned
What's next
Try it

Why I built this

Every network request you have ever made started with a question: what is the IP address of this name? You type github.com, and before a single byte of HTML moves, something somewhere has to turn those ten characters into 20.207.73.82.

For years that "something" was a black box to me. I knew the words (resolver, root server, TTL, A record) the way you know the names of planets. I'd never touched one.

The usual analogy is that DNS is the internet's phone book. It's a good analogy, but it hides the interesting part. A phone book is one big printed list. DNS is a distributed phone book: no single machine knows every name, so a resolver has to ask a chain of servers, each of which only knows who to ask next.

I wanted to see that chain with my own eyes, and I wanted to do it in Rust, because DNS is a binary protocol full of bit fields, offsets and length prefixes. That's exactly the kind of code where Rust's Result and bounds checks earn their keep. Malformed packets are not hypothetical on the open internet.

I built RustDNS by working through Emil Hernvall's excellent dnsguide, and if you want a step-by-step tutorial, that guide is the place to go. This post is the other half: a tour of the finished code, plus what happened when I ran it against the real internet two years later.

DNS in two minutes

DNS names are a tree, read right to left. The invisible dot at the end of google.com. is the root. Below it sit the top-level domains (.com, .org, .in), below those the domains people register, and below those whatever names the owner creates.

Diagram from the original.

Each level is delegated. The root servers don't know Google's IP. They only know which servers are in charge of .com. The .com servers don't know it either; they know which servers are in charge of google.com. Only those last servers, the authoritative ones, have the actual answer.

A recursive resolver is the operator in this picture. You ask it one question, and it makes all the calls on your behalf: root, then TLD, then authoritative, then it hands you the answer. Your laptop normally uses one run by your ISP, Google (8.8.8.8) or Cloudflare (1.1.1.1). RustDNS is a tiny one you can run yourself.

Hello, resolver

Build and run it. There are no dependencies to download, so it compiles in seconds:

cargo run --release
# listening on 0.0.0.0:2053 (UDP)

Port 2053 instead of 53 is deliberate: ports below 1024 need root on Linux, and this way you don't have to sudo a learning project. In a second terminal:

dig @127.0.0.1 -p 2053 google.com

No dig on Windows? Neither did I while writing this post, so here is a 12-line client in Python that builds a query packet by hand. It's also a nice preview of the wire format we're about to dissect:

import socket, struct, sys

name, qtype = sys.argv[1], int(sys.argv[2]) if len(sys.argv) > 2 else 1
q = struct.pack(">HHHHHH", 0x1234, 0x0100, 1, 0, 0, 0)   # header: id, flags (RD=1), 1 question
for label in name.split("."):
    q += bytes([len(label)]) + label.encode()             # [6]google[3]com
q += b"\0" + struct.pack(">HH", qtype, 1)                 # end of name, QTYPE, QCLASS=IN

s = socket.socket(socket.AF_INET, socket.SOCK_DGRAM)
s.settimeout(20)
s.sendto(q, ("127.0.0.1", 2053))
print(s.recvfrom(4096)[0].hex())

The server prints every step of its search. This is a real run from my machine, unedited:

Received query: DnsQuestion { name: "google.com", qtype: A }
attempting lookup of A google.com with ns 198.41.0.4
attempting lookup of A google.com with ns 192.41.162.30
attempting lookup of A google.com with ns 216.239.34.10
Answer: A { domain: "google.com", addr: 142.250.29.100, ttl: 300 }
Answer: A { domain: "google.com", addr: 142.250.29.101, ttl: 300 }
Answer: A { domain: "google.com", addr: 142.250.29.138, ttl: 300 }
Answer: A { domain: "google.com", addr: 142.250.29.113, ttl: 300 }
Answer: A { domain: "google.com", addr: 142.250.29.139, ttl: 300 }
Answer: A { domain: "google.com", addr: 142.250.29.102, ttl: 300 }

Three lines, three servers: 198.41.0.4 is a.root-servers.net, 192.41.162.30 is l.gtld-servers.net (one of the .com servers), and 216.239.34.10 is ns2.google.com. That's the whole tree from the diagram above, walked in about half a second.

A CNAME chain works too. Asking for www.github.com comes back with an alias and the address it points to:

Answer: CNAME { domain: "www.github.com", host: "github.com", ttl: 3600 }
Answer: A { domain: "github.com", addr: 20.207.73.82, ttl: 60 }
Authority: NS { domain: "github.com", host: "dns1.p08.nsone.net", ttl: 900 }
Authority: NS { domain: "github.com", host: "ns-421.awsdns-52.com", ttl: 900 }
...

So how does it do that?

The map of the code

The whole server lives in one file, src/main.rs, and Cargo.toml has an empty [dependencies] table. It layers neatly from raw bytes up to a running server:

Diagram from the original.

Everything that touches the wire goes through BytePacketBuffer. Everything above it works with plain Rust structs and enums. Let's go bottom-up.

A 512-byte cursor

The original DNS spec (RFC 1035) caps a UDP message at 512 bytes. So the buffer is just a fixed array and a position:

pub struct BytePacketBuffer {
    /// Buffer for holding the packet contents
    pub buf: [u8; 512],
    /// Field for keeping track of where we are
    pub pos: usize,
}

No heap allocation, no Vec, no growing. Reading is a cursor that walks forward and refuses to fall off the end:

fn read(&mut self) -> Result<u8> {
    if self.pos >= 512 {
        return Err("End of the buffer".into());
    }
    let res = self.buf[self.pos];
    self.pos += 1;
    Ok(res)
}

DNS is big-endian ("network byte order"), so multi-byte integers are assembled most-significant byte first:

fn read_u16(&mut self) -> Result<u16> {
    let res = ((self.read()? as u16) << 8) | (self.read()? as u16);
    Ok(res)
}

The ? after every read() is the quiet hero here. A truncated or malicious packet can end at any byte, and every single read propagates that as an error instead of reading garbage. Writing mirrors reading: write_u8, write_u16, write_u32, each splitting the integer back into bytes with shifts.

There are two more primitives that matter later: get(pos) peeks at a byte without moving the cursor, and set_u16(pos, val) overwrites two bytes we already wrote. Hold on to both.

Twelve bytes of header

Every DNS message, query or response, starts with the same 12-byte header:

                                1  1  1  1  1  1
  0  1  2  3  4  5  6  7  8  9  0  1  2  3  4  5
+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
|                      ID                       |
+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
|QR|   OPCODE  |AA|TC|RD|RA| Z|AD|CD|   RCODE   |
+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
|                    QDCOUNT                    |
+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
|                    ANCOUNT                    |
+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
|                    NSCOUNT                    |
+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
|                    ARCOUNT                    |
+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+

Field	Bits	Meaning
`ID`	16	Chosen by the client, copied into the reply so answers can be matched to questions
`QR`	1	0 = query, 1 = response
`OPCODE`	4	0 = standard query
`AA`	1	Authoritative answer: the server owns this name
`TC`	1	Truncated: the answer didn't fit, retry over TCP
`RD` / `RA`	1 + 1	Recursion desired (client asks) / available (server offers)
`AD` / `CD`	1 + 1	DNSSEC: authenticated data / checking disabled
`RCODE`	4	0 NOERROR, 2 SERVFAIL, 3 NXDOMAIN, …
`QDCOUNT` … `ARCOUNT`	16 each	How many entries follow in each of the four sections

The flags live in the middle 16 bits. DnsHeader::read splits them into a high byte a and low byte b and picks them apart with masks:

let flags = buffer.read_u16()?;
let a = (flags >> 8) as u8;
let b = (flags & 0xFF) as u8;
self.recursion_desired    = (a & (1 << 0)) > 0;
self.truncated_message    = (a & (1 << 1)) > 0;
self.authoritative_answer = (a & (1 << 2)) > 0;
self.opcode               = (a >> 3) & 0x0F;
self.response             = (a & (1 << 7)) > 0;

self.rescode              = ResultCode::from_num(b & 0x0F);
self.checking_disabled    = (b & (1 << 4)) > 0;
self.authed_data          = (b & (1 << 5)) > 0;
self.z                    = (b & (1 << 6)) > 0;
self.recursion_available  = (b & (1 << 7)) > 0;

Bit-twiddling is much easier to feel than to read. Click any bit below to flip it and watch the decoded header change. It starts at 0x8180, the flags of a normal successful response: QR, RD and RA set, RCODE 0. Try setting the low bits to 0011 to make an NXDOMAIN.

A frame from the interactive sketch in the original — watch it run.

Writing the header is the same thing in reverse: shift each boolean back into position and OR the pieces together into two bytes.

A real packet, byte by byte

The repo keeps two captured packets, query_packet.txt and response_packet.txt. The query is 28 bytes:

79 88 01 20 00 01 00 00 00 00 00 00   header: id 0x7988, RD=1, 1 question
06 67 6f 6f 67 6c 65 03 63 6f 6d 00   [6]google[3]com[0]
00 01 00 01                           QTYPE A, QCLASS IN

The response is 44. The sketch below steps through every field. Watch byte 28: it's where things get clever.

A frame from the interactive sketch in the original — watch it run.

Names, labels and compression pointers

Domain names on the wire aren't dotted strings. They're a sequence of labels, each prefixed by its length, ending with a zero-length label:

www.google.com  →  [3] w w w [6] g o o g l e [3] c o m [0]

A length byte can only use 6 of its 8 bits, which is where the famous label limit comes from: $2^{6} - 1 = 63$ characters.

The top two bits are reserved for something much better. If both are set (0b11xxxxxx), the byte isn't a length at all. It's the start of a compression pointer: the remaining 14 bits are an offset elsewhere in the packet where the rest of the name can be found.

$$
\text{offset} = \big((b_0 \mathbin{&} \texttt{0x3F}) \ll 8\big) \mathbin{|} b_1
$$

That's exactly what c0 0c at byte 28 of the response means: offset 0x000C, byte 12, where google.com was already written in the question. Two bytes instead of twelve. In a response with ten records about the same domain, that saving is the difference between fitting in 512 bytes and not.

Here's the flow of read_qname:

Diagram from the original.

And the heart of the code:

fn read_qname(&mut self, outstr: &mut String) -> Result<()> {
    let mut pos = self.pos();   // local cursor, independent of the buffer's
    let mut jumped = false;
    let max_jumps = 5;
    let mut jumps_performed = 0;
    let mut delim = "";

    loop {
        // A crafted packet can contain a pointer loop. Never trust the wire.
        if jumps_performed > max_jumps {
            return Err(format!("Limit of {} jumps exceeded", max_jumps).into());
        }

        let len = self.get(pos)?;

        if (len & 0xC0) == 0xC0 {
            // Move the *shared* cursor past the pointer, but only once
            if !jumped {
                self.seek(pos + 2)?;
            }
            let b2 = self.get(pos + 1)? as u16;
            let offset = (((len as u16) ^ 0xC0) << 8) | b2;
            pos = offset as usize;

            jumped = true;
            jumps_performed += 1;
            continue;
        } else {
            pos += 1;
            if len == 0 {
                break;
            }
            outstr.push_str(delim);
            let str_buffer = self.get_range(pos, len as usize)?;
            outstr.push_str(&String::from_utf8_lossy(str_buffer).to_lowercase());
            delim = ".";
            pos += len as usize;
        }
    }

    if !jumped {
        self.seek(pos)?;
    }
    Ok(())
}

Two details I really like here:

Two cursors. The function walks the name with a local pos, but the buffer's shared cursor has to end up right after the name as it appears in this record. After a jump, those are different places. So the shared cursor is moved exactly once, at the first pointer, and never touched again.
The jump limit. A malicious server can send a pointer that points to itself. Without max_jumps, read_qname would spin forever and one UDP packet would take down the resolver. Five jumps is plenty for any honest packet.

One enum per record type

Answers, authorities and additionals are all resource records with the same envelope: name, type, class, TTL, data length, then type-specific data. Rust's enums model that perfectly:

pub enum DnsRecord {
    UNKNOWN { domain: String, qtype: u16, data_len: u16, ttl: u32 }, // anything else
    A       { domain: String, addr: Ipv4Addr, ttl: u32 },              // 1
    NS      { domain: String, host: String, ttl: u32 },                // 2
    CNAME   { domain: String, host: String, ttl: u32 },                // 5
    MX      { domain: String, priority: u16, host: String, ttl: u32 }, // 15
    AAAA    { domain: String, addr: Ipv6Addr, ttl: u32 },              // 28
}

QueryType has an UNKNOWN(u16) variant too, so a record type the server has never heard of doesn't crash the parser. It reads data_len and skips over the data:

QueryType::UNKNOWN(_) => {
    buffer.step(data_len as usize)?;
    Ok(DnsRecord::UNKNOWN { domain, qtype: qtype_num, data_len, ttl })
}

Reading an A record is four bytes turned into an Ipv4Addr. AAAA is sixteen bytes turned into eight u16 segments. NS, CNAME and MX contain names, so they reuse read_qname, compression pointers and all.

Writing: backpatching the length

Writing has one fun problem. Every record carries an RDLENGTH field before its data, but for a name-valued record you don't know the length until you've written the name. So RustDNS writes a placeholder, writes the data, measures, and goes back to patch it in:

DnsRecord::CNAME { ref domain, ref host, ttl } => {
    buffer.write_qname(domain)?;
    buffer.write_u16(QueryType::CNAME.to_num())?;
    buffer.write_u16(1)?;       // class IN
    buffer.write_u32(ttl)?;

    let pos = buffer.pos();
    buffer.write_u16(0)?;       // placeholder RDLENGTH

    buffer.write_qname(host)?;

    let size = buffer.pos() - (pos + 2);
    buffer.set_u16(pos, size as u16)?;   // backpatch
}

That's what set_u16 was for. It's the same trick assemblers use for forward jumps, and it shows up any time a format puts a length before the thing being measured.

Walking the tree: recursive resolution

Everything so far is a parser. This is the part that makes it a resolver.

lookup() does one round trip: build a packet with one question, send it to one server over UDP, parse whatever comes back:

fn lookup(qname: &str, qtype: QueryType, server: (Ipv4Addr, u16)) -> Result<DnsPacket> {
    let socket = UdpSocket::bind(("0.0.0.0", 43210))?;

    let mut packet = DnsPacket::new();
    packet.header.id = 6666;
    packet.header.questions = 1;
    packet.header.recursion_desired = true;
    packet.questions.push(DnsQuestion::new(qname.to_string(), qtype));

    let mut req_buffer = BytePacketBuffer::new();
    packet.write(&mut req_buffer)?;
    socket.send_to(&req_buffer.buf[0..req_buffer.pos], server)?;

    let mut res_buffer = BytePacketBuffer::new();
    socket.recv_from(&mut res_buffer.buf)?;

    DnsPacket::from_buffer(&mut res_buffer)
}

(Keep an eye on that fixed port 43210 and fixed ID 6666. We'll come back to them.)

recursive_lookup() calls it in a loop, starting at a root server and following referrals downward:

Diagram from the original.

A referral is a response with no answer, but with NS records in the authority section ("ask these servers instead") and, usually, matching A records in the additional section. Those A records are called glue, and they save a round trip: the root doesn't just say "ask l.gtld-servers.net", it also tells you its IP.

Finding the next server with glue is a neat little iterator chain:

pub fn get_resolved_ns(&self, qname: &str) -> Option<Ipv4Addr> {
    self.get_ns(qname)                      // (domain, host) pairs from NS records
        .flat_map(|(_, host)| {
            self.resources.iter().filter_map(move |record| match record {
                DnsRecord::A { domain, addr, .. } if domain == host => Some(addr),
                _ => None,
            })
        })
        .map(|addr| *addr)
        .next()                             // first NS that has glue wins
}

When there's no glue (the nameserver lives in a different zone, like GitHub's ns-421.awsdns-52.com), the resolver has to stop, resolve the nameserver's name from scratch, then continue. That's literally recursion: recursive_lookup calls itself.

let new_ns_name = match response.get_unresolved_ns(qname) {
    Some(x) => x,
    None => return Ok(response),
};

// Down the rabbit hole: a whole new lookup in the middle of this one.
let recursive_response = recursive_lookup(&new_ns_name, QueryType::A)?;

if let Some(new_ns) = recursive_response.get_random_a() {
    ns = new_ns;
} else {
    return Ok(response);
}

Here's the google.com run from earlier as a sequence, with the real servers from the log:

Diagram from the original.

And here it is moving. The upstream legs are slowed down so you can follow them. Click the canvas to switch to what a cache would do (more on that later; RustDNS doesn't have one yet):

A frame from the interactive sketch in the original — it does not render here.

Serving dig on port 2053

The last layer turns the resolver into a server. main() is a single loop:

fn main() -> Result<()> {
    let socket = UdpSocket::bind(("0.0.0.0", 2053))?;
    loop {
        match handle_query(&socket) {
            Ok(_) => {}
            Err(e) => eprintln!("An error occurred: {}", e),
        }
    }
}

An error in one query is logged and the loop moves on, so one bad packet never kills the server. handle_query receives a packet, resolves it, and builds a response:

Diagram from the original.

let mut packet = DnsPacket::new();
packet.header.id = request.header.id;        // echo the client's ID
packet.header.recursion_desired = true;
packet.header.recursion_available = true;
packet.header.response = true;

if let Some(question) = request.questions.pop() {
    if let Ok(result) = recursive_lookup(&question.name, question.qtype) {
        packet.questions.push(question.clone());
        packet.header.rescode = result.header.rescode;
        packet.answers.extend(result.answers);       // (the repo uses for-loops with logging)
        packet.authorities.extend(result.authorities);
        packet.resources.extend(result.resources);
    } else {
        packet.header.rescode = ResultCode::SERVFAIL;
    }
} else {
    packet.header.rescode = ResultCode::FORMERR;
}

The response codes are the polite part of the protocol. A failed upstream lookup becomes SERVFAIL ("I tried, it broke"), and a packet with no question becomes FORMERR ("that's not a valid query"). The client always gets something back.

At least, that was the theory.

Breaking it on purpose

I wrote RustDNS in September 2024. To write this post, I built it again and threw real queries at it. Most worked. Two did not, and both are great lessons in why protocols look the way they do.

Bug 1: the MX query that never came back

Received query: DnsQuestion { name: "gmail.com", qtype: MX }
attempting lookup of MX gmail.com with ns 198.41.0.4
attempting lookup of MX gmail.com with ns 192.41.162.30
attempting lookup of MX gmail.com with ns 216.239.34.10
Answer: MX { domain: "gmail.com", priority: 5, host: "gmail-smtp-in.l.google.com", ttl: 3600 }
...   (5 MX answers, then 5 A and 5 AAAA additional records)
An error occurred: End of the buffer

The resolution succeeded. Google's server sent five MX records plus glue for every mail host, and that response fit comfortably in 512 bytes because Google compresses names with pointers.

RustDNS doesn't compress when it writes. write_qname spells every name out in full, so the same response grows:

Part	Bytes, uncompressed
Header + question	27
5 MX answers	275
5 A additionals	230
5 AAAA additionals	290
Total	822

The writer runs out of room partway through the A records, write() returns Err("End of the buffer"), handle_query bails out with ?, and the error is logged. Nothing is sent. The client just waits until it times out. My Python client gave up after 20 seconds.

The fix is a ladder of increasingly blunt tools, and real resolvers use all of them:

Compress names on write. Keep a map of name → offset while writing and emit a pointer the second time a name appears. That alone would shrink this response well under 512 bytes.
Drop the additional section. Glue records are optional hints. Header, question and answers here are only 302 bytes.
Set the TC bit. If even that doesn't fit, send what you can with truncated_message = true, which tells the client to retry over TCP. (RustDNS would then also need a TCP listener.)
EDNS(0), from RFC 6891, lets client and server agree on UDP payloads larger than 512 bytes.

A sketch of step 2, which is a few lines:

// Sketch, not in the repo yet
let mut res_buffer = BytePacketBuffer::new();
if packet.write(&mut res_buffer).is_err() {
    packet.resources.clear();                  // additionals are optional
    res_buffer = BytePacketBuffer::new();
    if packet.write(&mut res_buffer).is_err() {
        packet.answers.clear();
        packet.authorities.clear();
        packet.header.truncated_message = true; // "retry over TCP"
        res_buffer = BytePacketBuffer::new();
        packet.write(&mut res_buffer)?;
    }
}

Bug 2: an NXDOMAIN that lies about itself

Asking for a name that doesn't exist looked fine in the logs:

Received query: DnsQuestion { name: "doesnotexist-xyz123.com", qtype: A }
attempting lookup of A doesnotexist-xyz123.com with ns 198.41.0.4
attempting lookup of A doesnotexist-xyz123.com with ns 192.41.162.30
Authority: UNKNOWN { domain: "com", qtype: 6, data_len: 61, ttl: 900 }
Skipping record: UNKNOWN { domain: "com", qtype: 6, data_len: 61, ttl: 900 }

Type 6 is SOA, the record a server attaches to an NXDOMAIN so resolvers know how long to cache the "no". RustDNS doesn't model SOA, so it parses it as UNKNOWN, and when writing, UNKNOWN writes nothing at all. But DnsPacket::write sets the header counts from the vectors before writing:

self.header.authoritative_entries = self.authorities.len() as u16; // 1

So the response says "one authority record follows", and then the packet ends:

12 34 81 83 00 01 00 00 00 01 00 00  13 64 6f 65 73 ...
         ^ RCODE=3         ^ NSCOUNT = 1, but zero bytes of records follow

A lenient client shrugs and reads the NXDOMAIN rcode. A strict one rejects the whole packet as malformed. The quick fix is one line: packet.authorities.retain(|r| !matches!(r, DnsRecord::UNKNOWN { .. })) before writing. The proper fix is adding an SOA variant to DnsRecord. Either way, a header count is a promise, and a writer must never count something it doesn't write.

Smaller things I found reading the code again

Label length check. write_qname rejects labels longer than 0x34, which is 52, but the error message (and the spec) say 63. It should be 0x3F.
Off-by-one in get_range. It errors when start + len >= 512, so a range ending exactly at byte 512 is rejected. That should be >.
get_random_a isn't random. It returns the first A record. Harmless, but the name over-promises.
Zone matching with ends_with. get_ns keeps NS records where qname.ends_with(domain), so notgoogle.com "ends with" google.com. Comparing on a label boundary (qname == domain or qname.ends_with(&format!(".{}", domain))) is the correct check.

The serious one: spoofing

Remember lookup()? Every upstream query goes out from port 43210 with ID 6666, and the reply's ID is never checked. An attacker who can send UDP packets to the resolver only has to guess... nothing. They can race a forged answer for any name and it will be believed.

This is the class of attack Dan Kaminsky made famous in 2008, and the industry's response was to make forgeries expensive to guess: a random 16-bit ID and a random source port, roughly $2^{16} \times 2^{16} \approx 4.3 \times 1 0^{9}$ combinations instead of one. It's a small change:

// Sketch, not in the repo yet
use std::collections::hash_map::RandomState;
use std::hash::{BuildHasher, Hasher};
use std::time::Duration;

fn random_u16() -> u16 {
    RandomState::new().build_hasher().finish() as u16 // fine for a toy; use getrandom for real
}

let socket = UdpSocket::bind(("0.0.0.0", 0))?;           // OS picks a random ephemeral port
socket.set_read_timeout(Some(Duration::from_secs(2)))?;  // a dead server can't hang us forever
let id = random_u16();
// ... send, receive ...
if response.header.id != id {
    return Err("response ID mismatch".into());
}

The read timeout fixes a quieter problem too: today, if an upstream server never answers, recv_from blocks forever and the whole server freezes with it.

How fast is it?

Every query I sent was a cold lookup, because RustDNS doesn't cache anything. Each one walked root → TLD → authoritative, and took between 533 and 568 ms end to end on my connection.

That's almost entirely network time. Cold latency is roughly the sum of the round trips:

$$
T_{\text{cold}} \approx \sum_{i=1}^{h} \mathrm{RTT}_i \qquad (h = 3 \text{ for google.com})
$$

Parsing a 44-byte packet takes microseconds; waiting on three servers in a row takes hundreds of milliseconds. Which is why every real resolver caches. With a hit rate $p$ :

$$
\mathbb{E}[T] = p \cdot T_{\text{hit}} + (1 - p) \cdot T_{\text{miss}}
$$

At a modest 90% hit rate, with a hit costing about 1 ms and a miss 550 ms, the average drops from 550 ms to about 56 ms. The TTL on each record (300 seconds for Google's A records, 3600 for the gmail MX records) is the server telling you exactly how long you're allowed to keep it.

There's a second, sneakier cost. The server handles one query at a time. While it spends half a second walking the tree for one client, every other client waits in the socket's queue. And because lookup() binds a fixed port, you couldn't simply spawn a thread per request: the second thread would fail with "address in use". The spoofing fix above (port 0) happens to unblock concurrency too.

What I learned

Binary protocols are honest. There is no "kind of parsed". Either the 12 bytes are a header or they aren't, and Rust's Result plus ? on every read made each failure path explicit rather than a crash waiting to happen.
Every limit has a story. 512 bytes, 63-character labels, 14-bit pointers, 16-bit IDs. Each one is a design decision from 1987 that the internet has spent decades working around with compression, TCP fallback and EDNS.
Parsing and writing are not symmetric. RustDNS reads compression pointers perfectly and never writes one. That asymmetry is invisible on small answers and fatal on large ones.
Header counts are promises. Counting a record you then skip produces a packet that's wrong in a way only a strict parser notices.
Never trust the wire. The jump limit in read_qname is the line I'm proudest of, and the fixed query ID is the one I'd fix first. Same lesson, both directions.
DNS is a cache with a protocol attached. Resolution itself is a handful of round trips. Everything that makes it fast in practice is caching and TTLs.

What's next

TTL cache. A HashMap<(String, QueryType), (Vec<DnsRecord>, Instant)> behind a Mutex, respecting each record's TTL, including negative caching from the SOA.
Concurrency. A thread per request with socket.try_clone(), or a move to tokio, once upstream sockets use ephemeral ports.
Spoofing defences. Random IDs and source ports, ID verification and read timeouts, as sketched above.
Name compression on write, plus graceful truncation with the TC bit.
More record types: SOA, TXT, SRV and PTR.
TCP and EDNS(0) for responses bigger than 512 bytes.
A config.toml for the listen address, root hints and an optional upstream forwarder.
Tests built on the captured packets in the repo, so every fix above comes with a regression test.

Try it

git clone https://github.com/ravikisha/rustdns && cd rustdns
cargo run --release

# in another terminal
dig @127.0.0.1 -p 2053 google.com
dig @127.0.0.1 -p 2053 www.github.com
dig @127.0.0.1 -p 2053 gmail.com MX   # spoiler: see "Breaking it on purpose"

It's a single file with no dependencies, so it's a nice codebase to read in one sitting. If you've never looked inside DNS, I'd recommend opening main.rs next to RFC 1035 and a packet capture; it all clicks surprisingly fast.

If you liked this kind of build-it-to-understand-it post, I've done the same for link checkers in Rust and for calling Rust from Node.js.

⭐ Star it on GitHub, and if you'd like to pick up anything from the "What's next" list, open an issue or a PR. The NXDOMAIN fix is a great first contribution.

Happy resolving! 🦀

Photo credits: cover and rack photos by Derrick Coetzee, CC0, via Wikimedia Commons. Bell System switchboard, public domain, U.S. National Archives. 1928 Rikstelefonkatalogen, public domain, Televerket Sverige.

Relaxnative: Import C, C++, Rust, Zig and Go Straight into Node.js

Ravi Kishan — Mon, 05 Oct 2026 08:01:26 +0000

TL;DR: Relaxnative is a Node.js library that lets you write a function in C, C++, Rust, Zig or Go, point loadNative() at the file, and call it from JavaScript like any other function. No node-gyp, no binding.gyp, no hand-written N-API glue. It compiles on first import, caches by content hash, can ship prebuilt so production needs no compiler, and lets you choose how much a native crash is allowed to hurt.
npm i relaxnative
🔗 GitHub · 📦 npm · 🐛 Issues

Why I built this
Hello, native
Five languages, one call
What loadNative() actually does
Reading signatures: tree-sitter and friends
The types contract
A cache keyed by everything
Ahead-of-time builds: no compiler in production
Three isolation modes
Annotations: @sync, @async, @cost
Benchmarks: where native wins (and where it loses)
RelaxRegistry and supply-chain trust
Developer experience
What I learned
What's next

Why I built this

JavaScript is fast, often surprisingly fast. But every Node developer eventually hits a wall where it isn't fast enough:

64-bit integer math. JS numbers are doubles, so real u64 work means BigInt, and BigInt is slow.
Raw byte crunching, like image pixels, checksums and histograms, where you want tight loops over memory with no bounds checks.
Code that already exists in C or Rust that you'd rather reuse than rewrite.

The traditional answer is a native addon: node-gyp, a binding.gyp, N-API boilerplate, a C++ wrapper per function, and a build that breaks on every other Windows machine. It works, but it's a lot of ceremony for "I want to call add(a, b) written in C".

I wanted something closer to Python's ctypes or Bun's bun:ffi, but for plain Node, for several languages, and with real answers for safety. What happens when native code segfaults? What happens when you install someone else's native code? That's Relaxnative.

Hello, native

Create native/add.c:

// @sync
int add(int a, int b) {
  return a + b;
}

Call it from JavaScript:

import { loadNative } from 'relaxnative';

const mod = await loadNative('native/add.c', { isolation: 'worker' });
console.log(mod.add(1, 2)); // 3

That's the whole integration. The first loadNative() finds a compiler, builds a shared library, reads the function signatures out of your source and binds them. Every later run hits the cache.

Not sure which toolchains you have? Ask:

npx relaxnative doctor

✓ C compiler detected (clang 22.1.8)
✓ C++ compiler detected (clang 22.1.8)
✓ Rust compiler detected (rustc 1.97.1)
✗ Zig compiler missing (install zig)
✓ Go toolchain detected (go-wsl: go1.22.2 linux/amd64)
✓ Worker threads supported
✓ Cache directory OK
✓ ESM loader supported (Node >= 18)

Five languages, one call

Each language compiles to a C-ABI shared library (.dll / .so / .dylib), so from JavaScript they all look the same:

Language	Extension	How you export	Compiler
C	`.c`	plain top-level functions	clang / gcc / MSVC `cl` / `zig cc`
C++	`.cpp` `.cc` `.cxx`	`extern "C"` functions	clang++ / g++ / `cl` / `zig c++`
Rust	`.rs`	`#[no_mangle] pub extern "C" fn`	`rustc --crate-type cdylib`
Zig	`.zig`	`export fn`	`zig build-lib -dynamic`
Go	`.go`	`//export Name` + `import "C"`	`go build -buildmode=c-shared`

// add.rs
#[no_mangle]
pub extern "C" fn add(a: i32, b: i32) -> i32 { a + b }

// add.zig
export fn add(a: i32, b: i32) i32 { return a + b; }

// add.go
package main
import "C"
//export add
func add(a, b C.int) C.int { return a + b }
func main() {}

const mod = await loadNative('native/add.zig', { isolation: 'in-process' });
console.log(mod.add(20, 22)); // 42

One Zig install is a cheat code here: zig cc and zig c++ are clang-based, so a single download covers C, C++ and Zig.

Go on Windows was the fun one. To build a real Windows DLL, Relaxnative cross-compiles inside WSL with GOOS=windows CGO_ENABLED=1 CC=x86_64-w64-mingw32-gcc go build -buildmode=c-shared, so you only need go and mingw-w64 inside your distro.

Multi-file builds work too. Extra C/C++ sources get linked into the same library, Rust files are mod-declared, Zig files are @imported, and Go files form one main package:

const mod = await loadNative('native/main.c', {
  isolation: 'in-process',
  build: {
    sources: ['native/helper.c'],
    includePaths: ['native/include'],
    libraries: ['m'],
    flags: ['-O3'],
  },
});

What `loadNative()` actually does

The whole library is built around one pipeline in src/loader.ts:

Prebuilt? If .relaxnative/prebuilt/ has an artifact for this platform and this exact source content, use it and skip compiling entirely.
Detect the toolchain for the file's language (clang, gcc, cl, zig, rustc, go).
Hash the compile inputs. On a cache hit, reuse the library.
Compile to a shared library on a miss. C/C++ get -O2 by default, because building at -O0 makes native code lose badly to V8's JIT and that's an embarrassing benchmark.
Parse the signatures from your source to learn names, parameter types and return types.
Bind them with koffi, a fast FFI library for Node.
Wrap each function according to the isolation mode you picked.

The result is a plain object of JavaScript functions.

Reading signatures: tree-sitter and friends

To bind a function, Relaxnative has to know its signature without you writing it twice. So it reads your source:

C, C++ and Rust are parsed with tree-sitter grammars, giving a real syntax tree instead of regex guesses.
Zig and Go use small lexical scanners that look for export fn and //export and map types like i32, [*]u8 or C.int to the shared type model.

Real C is messier than it looks, and the parser has the scars to prove it. My favourite: for a pointer-returning function like char *greet(int), tree-sitter nests the function declarator inside a pointer_declarator and hangs the * there, not on the return type. The first version read the name as greet(int), found no parameters, decided the return type was unknown, and silently dropped the function. The fix unwraps every pointer_declarator layer and folds the stars back into the return type.

Other details it handles:

foo(void) means "no parameters", so the lone void is dropped.
Variadic functions (printf-style) are detected and rejected instead of being called with a garbage stack.
Pointer stars can live in the declarator (uint8_t *buf), so type and declarator text are combined with a space. Otherwise unsigned long long x becomes unsigned long longx.

And there's a rule: if a type isn't recognized, fail fast. A wrong FFI signature doesn't throw a nice error. It corrupts memory.

The types contract

Concept	C / C++	Rust	Zig	Go (cgo)
32-bit int	`int` / `int32_t`	`i32`	`i32`	`C.int`
64-bit int	`int64_t`	`i64`	`i64`	`int64`
float / double	`float` / `double`	`f32` / `f64`	`f32` / `f64`	`float32` / `float64`
bool	`bool`	`bool`	`bool`	`bool`
byte buffer	`uint8_t*`	`*mut u8`	`[*]u8`	`*byte`
C string	`const char*`	`*const i8`	`[*c]const u8`	`*C.char`

On the JavaScript side:

Scalars become number. 64-bit integers can come back as bigint and accept either.
Pointers accept TypedArrays: pass a Uint8Array for uint8_t* or a Uint32Array for uint32_t*. Native code writes straight into your array.
const char* parameters and returns are plain JS strings.
For manual memory there's native.alloc(size), which returns a NativeBuffer with an .address.

// @async
void histogram_u8(const uint8_t* data, int n, uint32_t* out256) {
  for (int i = 0; i < 256; i++) out256[i] = 0;
  for (int i = 0; i < n; i++) out256[data[i]]++;
}

const { histogram_u8 } = await loadNative('native/histogram.c', { isolation: 'worker' });
const data = new Uint8Array(1024 * 1024);
const out = new Uint32Array(256);
await histogram_u8(data, data.length, out); // out is filled in place

Tip: prefer fixed-width types (uint32_t* over unsigned*). They make the parser's job unambiguous, and they're better C anyway.

A cache keyed by everything

Compiling on every import would be unbearable, so builds are cached under ~/.relaxnative/cache. The key is a SHA-256 over everything that changes the output binary:

// src/cache/hash.ts (simplified)
for (const p of [sourcePath, ...sources]) hash.update(readFileSync(p)); // CONTENTS, not paths
hash.update(compiler.path + compiler.version);
hash.update(flags.join(' '));
hash.update(includePaths.join(' '));
hash.update(libraryPaths.join(' '));
hash.update(libraries.join(' '));
hash.update(platform); // e.g. win32-x64

Two bugs taught me this list. Originally only the entry file was hashed, so editing a helper file in a multi-file build gave a false cache hit: you changed code and nothing happened. Now every source's contents are hashed. And a failed compile used to leave a half-populated cache directory behind. Now a cache entry only counts once its meta.json exists, and failed builds clean up after themselves.

npx relaxnative cache status
npx relaxnative cache clean

Ahead-of-time builds: no compiler in production

Compile-on-import is lovely in development and a liability in a slim Docker image. So there's an AOT mode:

npx relaxnative build native/add.c native/kernel.zig native/svc.go

Or declare targets once in relaxnative.build.json:

{
  "targets": [
    { "source": "native/add.c" },
    {
      "source": "native/mathkernel/main.c",
      "sources": ["native/mathkernel/helper.c"],
      "libraries": ["m"],
      "flags": ["-O3"]
    }
  ]
}

This writes the compiled libraries plus the parsed bindings to .relaxnative/prebuilt/. Ship that folder, and at runtime loadNative() uses a prebuilt artifact when it matches the current platform and the source's current content hash. No compiler, no parser work.

If you edit the source after building, the hash no longer matches and it quietly falls back to compiling, which is exactly what you want in development. RELAXNATIVE_NO_PREBUILT=1 turns the fast path off.

Three isolation modes

Here's the uncomfortable truth about native code: a segfault doesn't throw, it kills the process. No try/catch saves you. So Relaxnative makes the blast radius a per-call choice:

await loadNative('native/kernel.c', { isolation: 'in-process' }); // fastest
await loadNative('native/kernel.c', { isolation: 'worker' });     // default
await loadNative('native/kernel.c', { isolation: 'process' });    // safest

in-process calls the function directly on the JS thread. It has the lowest overhead and no safety net. Use it for trusted, hot code.

worker (the default) sends async work to a worker-thread pool so heavy calls don't block the event loop. To keep tiny calls cheap, sync functions still run in-process. That means worker mode is not crash-safe for sync functions, and the code comments say so plainly.

process forks a helper process and talks to it over IPC. It's the heavyweight option, and it buys you a lot:

Crash containment. If the native code segfaults, the helper dies, your app gets a ProcessIsolationError with code ISOLATED_PROCESS_CRASH (and the JS callsite that made the call), and the helper restarts.
Per-call timeouts. An infinite loop gets the helper killed instead of hanging forever.
A best-effort memory cap. The helper watches its own RSS and exits if it goes over.
Permission guards. Inside the helper, imports of fs, net/http/dns/tls, and child_process are denied unless granted. worker_threads, vm, v8 and inspector are always blocked because each one is an isolation escape hatch. Blocking is by module family, so node:fs/promises can't slip past a check for fs.

All calls in process mode are async, since there's an IPC boundary in the way.

I'm careful about wording here, and so is the threat model: this is defense in depth, not a sandbox. Native code can make raw syscalls that no Node-level guard can see. Kernel-level sandboxing (seccomp, AppContainer, sandbox-exec) is explicitly a non-goal for now.

Annotations: `@sync`, `@async`, `@cost`

How does the wrapper know whether a function should return a value or a Promise? You tell it, in a comment up to 3 lines above the function:

// @async
// @cost high
int heavy(int n) {
  long x = 0;
  for (int i = 0; i < n * 10000000; i++) x += i;
  return (int)x;
}

Annotation	Effect
`@sync`	Returns a plain value. In `worker` mode it may run on the main thread for speed.
`@async`	Returns a `Promise` and always goes through the worker in `worker` mode.
`@cost high`	Treated like `@async`, so heavy work stays off the event loop.

You can also override per call: loadNative(path, { config: { functionMode: { add: 'sync' }, defaultMode: 'async' } }).

Benchmarks: where native wins (and where it loses)

I didn't want to write a "native is 1000× faster!!" post, because it isn't, at least not always. Every FFI call has a fixed cost of a few microseconds. Native only wins when each call does enough work to pay that back.

The numbers above come from the in-repo suites (benchmark.report.test.ts and benchmark.realworld.test.ts), using in-process isolation. They tell a clear story:

64-bit integers: 53×. JS has to use BigInt, while native uses raw u64. I re-ran a xorshift kernel in Rust on a different Windows machine while writing this post and got ~74× (2000 × 4000 iterations: 6.7 s in JS, 91 ms native), with results matching JS bit for bit.
Raw buffers: 14× for summing 1 MiB, and 6.7× for RGBA→grayscale on a 2.1 MP image.
Float-heavy loops: about 1.1–2×. V8's JIT is genuinely excellent at number math, so Mandelbrot and dot products barely move.
A trivial a + b: 0.01×, roughly 80× slower. The FFI crossing costs far more than the addition, which V8 would simply inline.

The same u64 kernel across languages is a nice sanity check that it's the workload, not the language, that matters:

Language	Calls/s	vs JS
JS (V8, BigInt)	1,945	1.0×
Rust	28,503	14.7×
Go	40,560	20.9×
C (`zig cc`)	42,242	21.7×
Zig	45,304	23.3×

The rule of thumb: cross the boundary rarely, and do a lot of work each time. Batch your data into TypedArrays and make one big call, not a million small ones.

You can benchmark your own kernels against a plain-JS baseline:

npx relaxnative bench examples/matmul.c matmul_f32 --traditional --iterations 5 --warmup 1

RelaxRegistry and supply-chain trust

Once loading native code is this easy, the next question is scary: what about native code from someone else? An npm package can at least be sandboxed by your judgement. A native package can do anything your user account can.

So Relaxnative ships a small package system, RelaxRegistry, built with trust in mind:

npx relaxnative add file:examples/registry/fast-matrix
npx relaxnative list
npx relaxnative remove fast-matrix

Each package has a relax.json declaring its exports, the permissions it wants, and a trust level:

local: your own code. No prompts.
community: third-party code. You get a warning and must consent. Elevated permissions (fs, network, spawn) are refused, and isolation is forced to process.
verified: elevated trust, but only if a real cryptographic signature checks out. Otherwise the package is demoted to community.

Before any of that, a static scan flags risky APIs such as system, popen, exec*, fork, CreateProcessW and raw sockets. It strips comments, splices backslash line-continuations and blanks out string literals first, so sys\<newline>tem or "sy" "stem" can't dodge it. It's still only a heuristic, and the code says so.

Signing, done properly

My first design had a digest field and treated a matching digest as "verified". That's wrong, because anyone can recompute a hash. Integrity isn't authenticity. The final design has two separate layers:

{
  "trust": "verified",
  "registrySignature": {
    "alg": "sha256",
    "digest": "<sha256 over canonical manifest + per-source hashes>",
    "sources": { "add.c": "<sha256>" },
    "keyId": "relaxnative-registry-2026",
    "signature": "<base64 Ed25519 over the digest>"
  }
}

Integrity: the digest covers the manifest and every source file's content. It's computed over canonical JSON (keys sorted recursively, no whitespace), so reformatting the file can't change it. Any tampering fails the install.
Authenticity: an Ed25519 signature over that digest, verified against a pinned public key. Only this grants verified. Keys are bundled or provided via RELAXNATIVE_TRUSTED_KEYS, and signPackage() produces signatures.

Consent is content-pinned too. Your "yes" is stored with the package's content digest in native/registry/.trust.json, so if someone republishes the same name@version with different bytes, you're asked again. And the low-level raw installer is deliberately not exported. Every install goes through the trust-enforcing path, so there's no shortcut that skips the gate.

Developer experience

A few things that make day-to-day use pleasant:

Tracing. When a crash happens behind a worker or process boundary, the real error is easy to lose. RELAXNATIVE_TRACE=1 prints lifecycle events (loadNative.begin, build.done, dispatch, isolation.process.call…), and RELAXNATIVE_TRACE_LEVEL=debug also prints every parsed signature.

Hot reload. With RELAXNATIVE_DEV=1, loadNative() returns a stable proxy that watches the source file, rebuilds on save and swaps the implementation in place. It fingerprints the ABI (names, argument types, return types), so it knows when a change is more than a body edit.

An ESM loader. Run Node with --loader relaxnative/loader and you can import native files directly:

// node --loader relaxnative/loader app.js
import math from './native/add.c';

It currently handles C, C++ and Rust sources, plus relaxnative/<package> registry specifiers, with package names validated so relaxnative/../../etc/passwd goes nowhere.

A native test harness. Write tests in C:

int test_add() { return add(2, 2) == 4 ? 0 : 1; }      // 0 = pass
const char* test_msg() { return NULL; }                // NULL/"" = pass

npx relaxnative test native/examples --isolation process

Running tests in process isolation means a segfaulting test fails that test instead of taking down the runner.

Express in five lines:

import express from 'express';
import { loadNative } from 'relaxnative';

const app = express();
const native = await loadNative('native/loop.c', { isolation: 'worker' });
app.get('/sum', (req, res) => res.json({ v: native.loop_sum(Number(req.query.n ?? 1e6)) }));
app.listen(3000);

What I learned

FFI cost is the whole game. Native isn't faster per se. It's faster per unit of work, and only once that work dwarfs the few-microsecond crossing. The 0.01× add benchmark taught me more than the 53× one.
V8 is a formidable opponent. For plain float loops the JIT is within a whisker of -O2 C. Real wins come where JS is structurally weak: 64-bit ints and raw memory.
Parsing C is humbling. Pointer declarators, (void), variadics and multi-word types: every edge case is a silent-corruption bug waiting to happen. "Fail fast on unknown types" became a core principle.
Hashes aren't signatures. Separating integrity (the digest) from authenticity (Ed25519 with a pinned key) was the most important security fix in the project.
Be honest about safety. It's tempting to call process isolation a "sandbox". It isn't, and the docs and threat model say exactly what is and isn't protected.

What's next

Fix clang on Windows MSVC targets. It currently rejects -fPIC, which is why my demo above used Rust. zig cc or cl work today.
Cache toolchain detection so that warm loads skip probing compilers (and WSL) on every call.
Bring Zig and Go to the ESM loader.
Richer types: structs and callbacks.
An optional hardened runtime: seccomp-bpf on Linux, AppContainer on Windows, sandbox-exec on macOS.

Try it

mkdir my-native-app && cd my-native-app
npm init -y && npm pkg set type=module
npm i relaxnative
npx relaxnative doctor

⭐ Star it on GitHub, install it from npm, and if you find a signature it can't parse or a kernel where native loses, open an issue. Those are my favourite bug reports.

Happy hacking! ⚡

Relaxicons: Turn Any Iconify Icon into a Native Component for 8 Frameworks

Ravi Kishan — Mon, 05 Oct 2026 07:24:51 +0000

TL;DR — Relaxicons is a Node.js CLI that pulls any icon from the Iconify catalogue (200+ open-source icon sets) and writes it into your project as a real component for React, Next.js (RSC), Vue, Angular, Svelte, Solid, Laravel Blade or Web Components. One command, one file, no runtime icon library.
npm install -g relaxicons
relaxicons init
relaxicons add lucide:home
🔗 GitHub · 📦 npm · 📚 Docs · 🔍 Icon Explorer

The problem: icons are weirdly annoying
The idea: shadcn, but for icons
A 60-second tour
What happens when you run relaxicons add
The SVG transform pipeline (and the outline-icon trap)
One prop contract, eight frameworks
Caching that respects the network
The small details that make a CLI pleasant
Icons in CI
The docs site
Testing
What I learned
What's next

The problem: icons are weirdly annoying

Every frontend project hits the same wall sooner or later. You need one home icon. Your options are usually:

Install a whole icon package (react-icons, @mdi/js, lucide-react…). Great until you want an icon from a different set, and now you have two dependencies, two APIs and two styling conventions.
Use a runtime icon loader that fetches SVGs from a CDN in the browser. Flexible, but now your icons depend on a network request at render time.
Copy-paste the SVG from a website. Fast, but you end up with hard-coded width="24", a random fill="#000", kebab-case attributes that React complains about, and zero consistency between files.

None of these felt right to me. I wanted the icon in my repo, as code I own, written in the idiom of whatever framework I'm using — and I wanted it from any icon set without thinking about it.

That's why I built Relaxicons.

The idea: shadcn, but for icons

The mental model is close to how shadcn/ui treats components: don't install a library, generate the source into your project.

Iconify already did the heavy lifting of collecting icon sets — Lucide, Material Design Icons, Tabler, Phosphor, Font Awesome, Heroicons, and hundreds more — behind a single, consistent API. Every icon has an ID like collection:name:

lucide:home
mdi:github
tabler:brand-react
ph:rocket-launch

Relaxicons sits on top of that API. You give it an ID, and it gives you back a component file that:

has no width/height baked in (it scales with a size prop, default 1em),
uses currentColor so it inherits your text color,
exposes the same props in every framework (size, color, strokeWidth, className/class),
is formatted with Prettier, and
is automatically exported from an index.ts barrel file.

No runtime. No icon package. Just a file.

A 60-second tour

Install the CLI globally (Node 18+):

npm install -g relaxicons
relaxicons --version   # 1.1.2

Initialize inside your project. Relaxicons sniffs your project to figure out what you're using:

relaxicons init
# ✔ Detected: Next.js
# ? Confirm framework › Next.js
# ? Where do you want to save icons? › components/ui/icons
# ? Do you use TypeScript? › yes
# ✔ Created relaxicons.config.json

That writes a small config:

{
  "framework": "next",
  "iconPath": "components/ui/icons",
  "typescript": true,
  "schemaVersion": 2,
  "generatedAt": "2026-10-05T00:00:00.000Z"
}

Now add icons — one, several, or a whole file of them:

relaxicons add lucide:home
relaxicons add lucide:home,star,bell          # shared prefix shorthand
relaxicons add mdi:github,tabler:brand-react   # mix collections
relaxicons add --from icons.txt                # batch from a file

And use them like any other component:

import { HomeIcon, StarIcon } from '@/components/ui/icons';

export default function Nav() {
  return (
    <nav className="text-slate-600">
      <HomeIcon />                         {/* inherits text color, 1em */}
      <StarIcon size={24} color="gold" />  {/* explicit size + color */}
    </nav>
  );
}

Need to find an icon first? Explore from the terminal:

relaxicons collections --filter luc
relaxicons icons lucide --filter clock --limit 10
relaxicons search arrow --collection lucide
relaxicons stats -c lucide

…or use the visual Icon Explorer on the docs site and copy the command straight from there.

What happens when you run `relaxicons add`

Under the hood, add is a small, linear pipeline. Here's the whole journey of relaxicons add lucide:home:

  lucide:home
      │
      ▼
┌──────────────┐   relaxicons.config.json → framework, iconPath, typescript
│  getConfig   │   (--framework flag can override per call)
└──────┬───────┘
       ▼
┌──────────────┐   GET https://api.iconify.design/lucide/home.svg
│  fetchIcon   │   404 → fuzzy "Did you mean…?" suggestions
└──────┬───────┘
       ▼
┌──────────────┐   optional, only if svgo is installed
│  SVGO        │
└──────┬───────┘
       ▼
┌──────────────┐   strip width/height, currentColor, drop data-* attrs
│ transformSvg │   → { attrs, children }
└──────┬───────┘
       ▼
┌──────────────┐   custom template (.hbs/.ejs/.js) if present,
│  template    │   otherwise built-in react/vue/angular/svelte/…
└──────┬───────┘
       ▼
┌──────────────┐   parser picked from file extension
│  Prettier    │
└──────┬───────┘
       ▼
┌──────────────┐   HomeIcon.tsx + sorted `export * from './HomeIcon'`
│ write+barrel │
└──────────────┘

A few parts of that are worth zooming into.

Parsing the ID

fetchIcon accepts both lucide:home and lucide/home, and rejects anything that isn't exactly two non-empty parts with a helpful message. It then validates that the response actually is an SVG (optionally preceded by an XML prolog) before trusting it — if Iconify ever returns an HTML error page, you get Unexpected response: not an SVG instead of a broken component.

Safe names

Icon names on Iconify are wild. Some start with digits (500px), some are JavaScript reserved words (default, class, function), some are pure symbols. A generated component must be a valid identifier, so names go through two passes:

toPascalCase('arrow-right')  // ArrowRight
safePascal('Default')        // fine — PascalCase isn't reserved
safePascal('500px')          // Icon500px  (leading digit)
safePascal('')               // Icon       (nothing left after cleaning)
safeKebab('ÅÄÖ')             // icon

The same sanitized names are reused by relaxicons remove, so removing an icon always finds the file add created.

The SVG transform pipeline (and the outline-icon trap)

This is the most interesting file in the project: src/utils/transformSvg.js. It loads the SVG with cheerio in XML mode and does four things:

Removes width and height from the root, keeping viewBox, so the component can scale freely.
Applies currentColor so icons inherit the surrounding text color.
Strips noise like data-name / data-style attributes left behind by design tools.
Returns a neutral representation — { attrs, children } — that every framework template consumes.

Step 2 sounds trivial ("just set fill="currentColor" everywhere"), and that's exactly the trap I fell into first.

Icon sets come in two flavours:

Style	Examples	How it's drawn
Filled	MDI, Material Symbols, Font Awesome	Shapes painted with `fill`
Outline	Lucide, Feather, Tabler	`fill="none"` + `stroke`, lines only

If you blindly add fill="currentColor" to every <path> in an outline icon, the strokes get filled in and your crisp line icon turns into a solid blob. So the transform first asks: is this an outline icon?

const rootFillNone = $svg.attr("fill") === "none";
const rootHasStroke = !!$svg.attr("stroke");
const isOutline = rootFillNone || rootHasStroke;

…and only then decides, per element:

element has a stroke-width but no stroke → give it stroke="currentColor";
element already has its own fill (even fill="none") → never touch it;
outline icon, or the element itself is stroke-based → leave fill unset so it inherits none;
otherwise, for real shapes (path, circle, rect, polygon, polyline, ellipse) → fill="currentColor".

The trap had a second layer, and I only found it while writing this post. The Iconify API doesn't put Lucide's fill="none" on the root at all. It wraps every path in a group:

<svg viewBox="0 0 24 24">
  <g fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round">
    <path d="M15 21v-8a1 1 0 0 0-1-1h-4…"/>
    <path d="M3 10a2 2 0 0 1 .709-1.528l7-6…"/>
  </g>
</svg>

A root-only check sees no outline, so relaxicons add lucide:home produced a filled house. Worse, the group's stroke-width="2" shadowed the component's strokeWidth prop. The fix does two things:

Hoist the wrapper. If the root has exactly one <g> child that only carries presentation attributes (fill, stroke, stroke-width, line caps/joins), those move onto the root and the group is unwrapped. Now the root really says fill="none" stroke="currentColor", and strokeWidth defaults to the icon's own 2.
Check ancestors, not just the root. If a group can't be hoisted (say it also has a transform), any element inside a fill="none" or stroked group is left alone instead of being filled.

With both in place, filled icons recolor correctly and outline icons stay outlines, whichever way the SVG is structured.

One prop contract, eight frameworks

Every template lives in src/templates/ and shares helpers from _shared.js. The key design decision: every framework gets the same props.

Prop	Default	What it does
`size`	`1em`	Sets `width` and `height`
`color`	inherited	Applied as CSS `color` — which `currentColor` resolves to
`strokeWidth`	the icon's own value	Overrides stroke width when passed
`className` / `class`	—	Merged onto the root `<svg>`

Notice that color is applied through CSS color, not by forcing a fill. That one choice means color="red" recolors filled icons and outline icons without ever changing what kind of icon it is.

Here's what that contract looks like in each ecosystem:

React / Next.js — named + default export, optional TypeScript props type, and an RSC-safe variant (--framework next-rsc) with no hooks and no 'use client':

export function HomeIcon({ size = '1em', color, strokeWidth, className, style, ...props }: IconProps) {
  return (
    <svg viewBox="0 0 24 24" fill="none" stroke="currentColor"
         width={size} height={size} strokeWidth={strokeWidth}
         className={className} style={color ? { color, ...style } : style} {...props}>
      <path d="…" />
    </svg>
  );
}

Vue — a Single File Component with real typed props and inheritAttrs: false, forwarding everything else via v-bind="$attrs":

<template>
  <svg viewBox="0 0 24 24" :width="size" :height="size" :stroke-width="strokeWidth"
       :style="color ? { color } : undefined" v-bind="$attrs">
    <path d="…" />
  </svg>
</template>

Angular — a standalone component with @Input()s and a selector like icon-home:

@Component({ selector: 'icon-home', standalone: true, template: `<svg …>…</svg>` })
export class HomeIcon {
  @Input() size: string | number = '1em';
  @Input() color?: string;
}

Laravel Blade — @props([...]) with $attributes->merge(), used as <x-home-icon size="24" color="red" />.

Svelte — exported props plus $$restProps; class is aliased because it's a reserved word in JS.

Solid — JSX with splitProps so known props are separated from the rest.

Web Components — a framework-free custom element with Shadow DOM, observing size, color, stroke-width and class:

<script type="module" src="./icons/home.js"></script>
<icon-home size="32" color="tomato"></icon-home>

Getting the markup idiomatic per framework is where most of the subtle bugs hide. A few I had to handle in _shared.js and the templates:

React needs camelCase attributes (stroke-linecap → strokeLinecap, class → className, xlink:href → xlinkHref) — but only attribute names, never path data.
Angular embeds the SVG in a template literal, so backticks, backslashes and ${ inside the markup must be escaped.
Web Components embed the markup as a JS string, so it goes through JSON.stringify to survive quotes and newlines.
Custom element names must contain a hyphen — hence the icon- prefix.

And if none of the built-ins fit your codebase, drop a react.hbs, vue.ejs or svelte.js into a templatesDir and Relaxicons will use your template instead, passing it { iconId, pascal, kebab, svg, typescript }. Handlebars and EJS are lazy-required, so they're only needed if you actually use them.

Caching that respects the network

Listing collections and searching icons means hitting Iconify's metadata endpoints a lot. src/utils/cache.js makes that cheap and resilient:

Responses are cached as JSON in ~/.cache/relaxicons (override with RELAXICONS_CACHE_DIR).
Each entry stores the ETag; the next request sends If-None-Match, and a 304 Not Modified just refreshes the timestamp.
Entries without an ETag use a 24-hour TTL.
Requests retry with backoff (250 ms → 500 ms → 1 s) on network errors, 429 and 5xx, and honour the server's Retry-After header.
If the network fails entirely, it falls back to stale cache instead of crashing.
RELAXICONS_OFFLINE=1 makes the CLI run purely from a warm cache — handy on a plane, and essential for deterministic tests.

relaxicons update-cache   # warm everything
relaxicons cache-clear    # start fresh

The small details that make a CLI pleasant

Most of the work in a CLI isn't the happy path — it's everything around it.

"Did you mean…?" — typo an icon name and Relaxicons loads the collection and ranks names by similarity:

✖ Icon not found
Did you mean: alarm-clock, alarm-check, alarm-off?

If nothing in that collection is close, it searches across collections for the nearest match.

Framework auto-detection — init looks for next.config.*, vite.config.* + a react/vue/svelte dependency, angular.json, or composer.json + artisan. Each match carries a confidence score and the highest wins (Astro is detected at low confidence so a docs folder never overrides your real app).

Always-sorted barrels — every add appends an export and re-sorts the barrel alphabetically, preserving comment headers and the file's original line endings (CRLF stays CRLF on Windows).

Batch-friendly errors — in a batch, a missing icon or an existing file doesn't abort the run; it's reported and the rest continue.

Meaningful exit codes, so scripts can react:

Code	Meaning
`0`	OK
`1`	Generic error
`2`	Config missing / invalid
`3`	Fetch failed
`4`	File already exists

And the usual polish: --dry-run to preview writes, --quiet and --no-color for CI logs, --raw for plain SVG, --both for component + cleaned SVG side by side, doctor to check Node, config and Iconify reachability, and a JSON Schema (relaxicons.config.schema.json) so your editor autocompletes the config.

Icons in CI

For teams, I wanted icons to be reproducible. List the icons your app uses in a manifest:

# relaxicons.manifest
lucide:home
lucide:star
mdi:github

…and regenerate them anywhere:

relaxicons regenerate -m relaxicons.manifest --concurrency 4

One fun bug from building this: the first version ran several add commands concurrently inside the same process by re-parsing the shared Commander instance. Commander keeps per-invocation state on that object, so parallel runs corrupted each other. The fix was to run each add in an isolated child process with a small worker pool — boring, but bulletproof.

The repo ships a ready-made GitHub Action that runs on changes to the manifest or config, regenerates the icons and commits the result:

- run: npm i -g relaxicons
- name: Regenerate icons
  run: relaxicons regenerate -m relaxicons.manifest
- name: Commit changes
  run: |
    git add -A
    git diff --cached --quiet || git commit -m "chore(relaxicons): regenerate icons"
    git push

The docs site

The documentation at ravikisha.github.io/relaxicons is built with Astro 5, React islands, Tailwind CSS 4 and Radix UI primitives, and deployed to GitHub Pages by the CI workflow on every push to main.

Some highlights:

Icon Explorer — browse collections, search icons, keep Favorites and Recent tabs, navigate with arrow keys + Enter, and copy an icon as a CLI command, raw SVG or data URI. It also shows per-collection stats and a top-icons carousel.
Command palette (built with cmdk) for jumping anywhere in the docs.
Copy-ready code tabs for every framework, an animated framework marquee and a live mini demo on the home page.

Good starting points in the docs:

Testing

The project has 24 Jest suites covering each piece in isolation and the CLI end to end:

Unit tests for naming, sanitizing, path handling, framework detection, config validation, the SVG transform, and every framework template.
Golden tests that snapshot generated output, so a template change can't silently alter what users get.
Integration tests that spawn the real CLI in temp directories with RELAXICONS_OFFLINE=1 and fixture icons — no network, no flakiness — and assert on files written and exit codes.
Windows path tests, because a CLI that writes files had better work with backslashes too.

npm test
npm run coverage

What I learned

SVG is not one format, it's a family of conventions. Outline vs. filled, attributes on the root vs. on a <g>, fill="none" meaning "inherit nothing". Normalizing icons from 200+ sets is way subtler than "replace the color", and testing against the real API response (not a hand-written fixture) is what caught the <g> wrapper bug.
Generating code means respecting each framework's idioms. It's easy to produce something that renders; it's harder to produce something a React, Vue or Angular developer would actually want to commit.
Caching is a UX feature. ETags, TTLs, backoff and stale fallback are what make a network-backed CLI feel instant and never strand you offline.
Shared mutable state bites, even in a CLI. The Commander concurrency bug was a good reminder that "it's just a script" doesn't exempt you from isolation.
Exit codes and --dry-run are documentation. They tell scripts and humans exactly what happened.

What's next

Real shell completions for zsh/bash/fish (the completion command is still a stub).
Removing the deprecated list alias in v2.0 (use icons instead).
More framework targets and richer custom-template examples.

If you're tired of juggling icon packages, give it a spin:

npm install -g relaxicons
relaxicons init
relaxicons add lucide:sparkles

⭐ Star it on GitHub, grab it from npm, and if you find an icon that renders wrong, open an issue — I'd love to see it.

Happy building! 🎨

How RelaxCSS Works: Building a TailwindCSS-Like Utility Engine

Ravi Kishan — Tue, 24 Jun 2025 05:59:38 +0000

Overview and Introduction

RelaxCSS is a lightweight, Tailwind-inspired utility-first CSS engine implemented as a PostCSS plugin and CLI tool. Like Tailwind, it provides a rich set of pre-defined utility classes (e.g. p-4, bg-blue-500, hover:text-white) and a configuration-driven design system. RelaxCSS aims to be minimal and extensible: it supports custom theme values (colors, spacing, etc.), responsive and pseudo-class variants, JIT compilation of only used utilities, and a plugin API for adding new utilities. Under the hood, a “preflight” (CSS reset) is injected (similar to Tailwind’s) and directives like @apply and @relax in CSS enable class composition.

In practice, you install RelaxCSS, write your CSS/HTML with utility classes, and run the CLI (or PostCSS plugin) to watch your files. The tool scans source files for class names (using glob patterns and regex), generates the corresponding utility CSS on-the-fly (JIT), and writes out a final output.css. The default configuration (which you can customize via relaxcss.config.js) includes sensible defaults for colors, spacing, screens, etc., and even a built-in example plugin (adding a fancy-border utility). Overall, RelaxCSS provides a Tailwind-like workflow—class-heavy markup and zero custom CSS—while remaining small and easy to extend.

Architecture Overview

RelaxCSS consists of several major components that work together in a build pipeline:

CLI/Watcher: A command-line interface (cli.ts/cli-watch.ts) runs RelaxCSS. It uses glob and chokidar to watch source files (HTML, CSS, JS, etc.) and trigger rebuilds on changes.
File Scanner (JIT Engine): The CLI watches file patterns (e.g. src/**/*.{html,js,jsx,ts,tsx,css}), reads each file’s content, and extracts class names with regex.
PostCSS Parser: RelaxCSS is implemented as a PostCSS plugin. The plugin receives the CSS AST parsed from your combined stylesheet (including your @apply rules).
Theme/Config: User configuration (from relaxcss.config.js or plugin options) is merged with the default theme/variants. This config object (colors, spacing, screens, etc.) is provided to the plugin and to any utility-generating code.
Utility Generator (Plugin Logic): The core plugin takes each utility class name (or @apply directive) and generates the corresponding CSS declarations based on the theme config. It supports responsive prefixes (e.g. md:), pseudo-classes (e.g. hover:), and even arbitrary values (bg-[#222]).
Output Generator: After PostCSS transforms (including preflight injection and @apply resolution), the plugin emits the final CSS. The CLI then writes this CSS to the output file (e.g. dist/output.css).

In this flow, the CLI initiates file scanning (with glob and chokidar) and combines CSS and @apply rules. The PostCSS parser parses the CSS, and the RelaxCSS plugin transforms it: injecting base styles (preflight), resolving @apply by inlining utility declarations, and wrapping rules in media/pseudo selectors. The theme/config drives which CSS values get used. Finally, the Output Generator writes out the CSS file.

Theme and Configuration System

RelaxCSS is highly configurable via a relaxcss.config.js (or via plugin options). The user config can define custom theme values (colors, spacing, fonts, etc.), responsive breakpoints, variants (e.g. which pseudo-classes to enable), plugins, and more. Internally, RelaxCSS starts with a defaultConfig (built-in) and merges the user’s config into it using lodash.merge:

const mergedConfig = merge(defaultConfig, opts);

This merged config object, mergedConfig, contains all theme scales. For example, the default theme includes a screens section (for breakpoints) and a spacing section:

theme: {
  screens: { sm: "640px", md: "768px", lg: "1024px", xl: "1280px" },
  spacing: { px: "1px", 0: "0px", 1: "0.25rem", 2: "0.5rem", … },
  colors: { transparent:"transparent", white:"#fff", blue: {50:"#eff6ff", 100:"#dbeafe", …}, … },
  fontSize: { base:["1rem",{lineHeight:"1.5rem"}], xl:["1.25rem",{lineHeight:"1.75rem"}], … },
  // etc.
}

Within the plugin code, CSS generation functions access these theme values. For example, when handling max-w-<key> utilities, the code does:

if (className.startsWith("max-w-")) {
  const value = get(config.theme.maxWidth, suffix);
  if (value !== undefined)
    declarations.push(new Declaration({ prop: "max-width", value }));
}

Similarly, for font sizes (text-xl), it retrieves a tuple from config.theme.fontSize:

const fontSizeTuple = get(config.theme.fontSize, suffix);
if (Array.isArray(fontSizeTuple)) {
  declarations.push(new Declaration({ prop: "font-size", value: fontSizeTuple[0] }));
  if (fontSizeTuple[1]?.lineHeight) {
    declarations.push(new Declaration({ prop: "line-height", value: fontSizeTuple[1].lineHeight }));
  }
}

In summary, RelaxCSS loads user settings (via opts or a relaxcss.config.js), merges them with defaults, and then all parts of the system read from this mergedConfig.theme. The variants section (e.g. which media queries and which pseudo-classes to support) also comes from the config and drives how the plugin wraps utility rules for sm: or hover: prefixes.

Utility Parser and Generator

At the heart of RelaxCSS is the utility parser, which takes a class name like p-4, bg-[#222], or md:hover:bg-blue-500 and translates it into one or more CSS declarations. This logic lives in the function generateUtilityCss(className, config) in index.ts. The class name is split into a prefix (e.g. p, bg, text, etc.) and a suffix (the part after the dash). A series of if/else and switch statements handle each utility:

Spacing utilities (p-4, mt-2, mx-auto, etc.): use helper functions that look up the numeric key in config.theme.spacing and emit corresponding padding or margin declarations. For example, m-4 becomes margin: 1rem if spacing[4] = "1rem".
Size limits (max-w-lg, max-h-full): look up in config.theme.maxWidth or maxHeight (from the merged config) and emit max-width or max-height. See above in .
Colors and fonts: for text-<color>-<shade> or bg-<color>-<shade>, a helper (getColor) checks the nested config.theme.colors. For text-xl, it instead looks in config.theme.fontSize as shown in .

Importantly, RelaxCSS also supports arbitrary values via a special parser function. A class like bg-[#222] or p-[4px] matches the regex /^([a-z-]+)-\[(.+)\]$/. This extracts a prefix and a raw value. The code parseArbitraryValue(className, config) (see below) directly maps certain prefixes to CSS properties:

function parseArbitraryValue(className: string, config: RelaxConfig): Declaration[] {
  // e.g. bg-[#222], p-[4px], text-[red], w-[100px], m-[1rem], etc.
  const arbitraryMatch = className.match(/^([a-z-]+)-\[(.+)\]$/i);
  if (!arbitraryMatch) return [];
  const prefix = arbitraryMatch[1];
  const value = arbitraryMatch[2];
  // Map prefix to CSS property
  switch (prefix) {
    case "bg":
      return [new Declaration({ prop: "background-color", value })];
    case "text":
      return [new Declaration({ prop: "color", value })];
    case "border":
      return [new Declaration({ prop: "border-color", value })];
    case "w":
      return [new Declaration({ prop: "width", value })];
    case "h":
      return [new Declaration({ prop: "height", value })];
    // ... handle px, py, m, etc. in a similar way ...
    default:
      // fallback: treat prefix as the property name
      return [new Declaration({ prop: prefix, value })];
  }
}

When the PostCSS plugin encounters a utility class, it first tries parseArbitraryValue. If that returns declarations, it uses them directly (for example, bg-[#222] yields background-color: #222). Otherwise, it falls back to the standard generateUtilityCss logic for named utilities.

Responsive and pseudo variants: Class names can be prefixed with media queries or pseudo-classes, like sm:, md:, hover:, focus:, etc. In RelaxCSS this is handled in the plugin as well. The CLI/JIT will detect a class like md:hover:bg-blue-500 and enqueue it. The plugin code splits on ":" to see that md is a responsive variant and hover is a pseudo-variant, and then wraps the generated declarations accordingly. For example, md:hover:bg-blue-500 results in a rule inside a @media (min-width: 768px) block, with selector .md\:hover\:bg-blue-500:hover { background-color: ... }. (The plugin has helper code to do this, but the key point is that our design allows stacking variants in class names.)

For standard utilities (without variants), the code essentially turns a class into a CSS rule of the form .<class> { <declarations> }. For example, text-xl would lead to:

.text-xl {
  font-size: 1.25rem; /* from theme */
  line-height: 1.75rem; /* from theme */
}

Likewise, .bg-blue-500 { background-color: #3b82f6; }. Arbitrary values work similarly: .bg-\[\#222\] { background-color: #222; }.

Plugin System

RelaxCSS provides a plugin API so users can register additional utilities. A plugin is simply a function receiving an API object, e.g.:

interface RelaxPlugin {
  (api: {
    addUtilities: (utils: Record<string, (config: RelaxConfig) => Declaration[]>) => void;
    config: RelaxConfig;
  }): void;
}

Within this function, a plugin typically calls api.addUtilities(...) with new utility definitions. For example, the default config includes a built-in plugin that adds a fancy-border utility:

plugins: [
  function ({ addUtilities, config }) {
    addUtilities({
      "fancy-border": () => [
        // This utility generates: border:2px dashed magenta;
        new Declaration({ prop: "border", value: "2px dashed magenta" }),
      ],
    });
  },
],

After loading the config, RelaxCSS iterates through any plugins array (if provided) and calls each plugin function. The addUtilities calls aggregate into a userUtilities map. Later, during CSS generation, these custom utilities are treated just like built-in ones: if a class matches "fancy-border", RelaxCSS will output the declarations given by that plugin function.

This plugin mechanism allows anyone to extend RelaxCSS with their own custom shortcut classes (e.g. new color utilities, or even complex components) without modifying the core engine.

JIT Compilation and File Scanning

The CLI tool (cli-watch.ts) implements a Just-In-Time (JIT) engine. Instead of generating all possible utility classes, it scans your source files on-the-fly for exactly the classes you use. Key points:

File watching: The CLI takes a glob pattern like src/**/*.html and uses glob.sync to find matching files. It then sets up a watcher with chokidar.watch(srcGlob) to re-run the scan whenever any matching file changes. This makes it incremental and efficient.
Class extraction: For each source file, the code reads its contents and uses a regex to find class names. For HTML/JSX/etc, it matches class="...", className="...", or Vue :class="...", etc. The regex used is:
```
const classRegex = /(?:class|className|:class)\s*=\s*["'`\{[]([^"'`\}\]]+)["'`\}]/g;
```
Then it splits the captured class string on whitespace. For example, in <div class="text-xl p-4 hover:bg-red-500">, it will extract ["text-xl","p-4","hover:bg-red-500"].

CSS files are also scanned for @apply directives: another regex /@apply\s+([^;]+);/g pulls out any classes listed in an @apply statement.
Building CSS to apply: After scanning all files, the CLI builds a temporary CSS string where each found class is “applied” via @apply. For example, if it found text-lg and mt-4, it generates:
```
.text-lg { @apply text-lg; }
.mt-4 { @apply mt-4; }
```
(It also handles variants by calling a helper generateTailwindVariantRule, but ultimately it creates @apply rules for each used class.) This combined CSS (plus any raw CSS content) is then fed into PostCSS with the RelaxCSS plugin.
Automatic rebuilds: Thanks to chokidar, any file change triggers the scan-and-build process again. This ensures the output CSS is always up-to-date with the classes in your source.

Key code excerpts from cli-watch.ts:

// Scan files for classes and @apply
const files = glob.sync(srcGlob);
console.log(`[RelaxCSS] Processing files matching: ${files}`);
files.forEach((file) => {
  const ext = path.extname(file).slice(1);
  const content = fs.readFileSync(file, "utf8");
  if (ext === "css") {
    combinedCss += content + "\n";
    extractApplyClasses(content).forEach(cls => foundClasses.add(cls));
  } else if (fileExtensions.includes(ext)) {
    extractClassNames(content).forEach(cls => {
      foundClasses.add(cls);
      classNameFoundClasses.add(cls);
    });
  }
});

The extractClassNames and extractApplyClasses functions use regexes to find classes:

// In cli-watch.ts:
function extractClassNames(content: string): string[] {
  // Match class="...", className="...", etc.
  const classRegex =
    /(?:class|className|:class)\s*=\s*["'`\{[]([^"'`\}\]]+)["'`\}]/g;
  let match;
  while ((match = classRegex.exec(content))) {
    matches.push(...match[1].split(/\s+/).filter(Boolean));
  }
  return matches.filter(cls => !cls.startsWith("...")); // ignore Spread syntax
}

After extracting, the watcher rebuild logic looks like:

// Watch for changes and rebuild
const watcher = chokidar.watch(srcGlob, { ignoreInitial: true });
watcher.on("all", (event, filePath) => {
  console.log(`[RelaxCSS] Detected ${event} in ${filePath}. Rebuilding...`);
  processFiles();
});

This JIT pipeline – scan source → extract classes → generate @apply CSS → run RelaxCSS plugin – ensures that only used utilities end up in the final CSS. We can diagram it as:

Preflight and CSS Output

By default, RelaxCSS injects a small preflight (base reset) at the top of the CSS. This is similar to Tailwind’s Preflight and is meant to normalize browser defaults. In the plugin code, you can see it defines sections like “box-sizing”, “margin-padding”, “list-style”, etc.:

const preflightSections: Record<string, string> = {
  "box-sizing": `*,*::before,*::after{box-sizing:border-box;}`,
  "margin-padding": `body,h1,h2,h3,h4,h5,h6,p,ul,ol,li,figure,figcaption,blockquote,dl,dd{margin:0;padding:0;}`,
  "list-style": `ul:not([class]),ol:not([class]){list-style:none;}`,
  "font-family": `body{font-family:system-ui,-apple-system,BlinkMacSystemFont,"Segoe UI",Roboto,Oxygen,Ubuntu,Cantarell,"Open Sans","Helvetica Neue",sans-serif;line-height:1.5;-webkit-font-smoothing:antialiased;-moz-osx-font-smoothing:grayscale;}`,
  "media": `img,picture,video,canvas,svg{display:block;max-width:100%;}`,
  "form": `button,input,optgroup,select,textarea{font-family:inherit;font-size:100%;line-height:1.15;margin:0;}`,
  "table": `table{border-collapse:collapse;}th,td{padding:0;}`,
};

These CSS snippets (with comments like /* RelaxCSS Preflight: box-sizing */) are prepended to the output. The preflight section of the config allows enabling/disabling parts or adding overrides, but by default all sections are included. For example, the first injected rule is *,*::before,*::after{box-sizing:border-box;} (ensuring consistent box-sizing).

After the plugin runs (resolving all @apply rules into concrete declarations and wrapping variants), the final CSS is emitted. In cli-watch.ts, this is done with PostCSS:

postcss([ relaxcss() ])
  .process(finalCss, { from: undefined })
  .then((result) => {
    fs.mkdirSync(path.dirname(outFile), { recursive: true });
    fs.writeFileSync(outFile, result.css, "utf8");
    console.log(`[RelaxCSS] Rebuilt: ${outFile}`);
  })
  .catch((err) => console.error("[RelaxCSS] Build error:", err));

So the final output is a single CSS file that begins with the preflight rules, followed by your combined utilities. All @apply rules have been replaced by their actual CSS declarations. For instance, if you had:

@relax;
.container { @apply flex bg-[#222] md:hover:bg-[#333]; }

the output might look like:

/* RelaxCSS Preflight: box-sizing */
*,*::before,*::after{box-sizing:border-box;}
/* RelaxCSS Preflight: margin-padding */
body,h1,...,dd{margin:0;padding:0;}
/* ... other preflight rules ... */

/* Utility classes */
.container {
  display: flex;
  background-color: #222;
}
@media (min-width:768px) {
  .md\:hover\:bg-\[\#333\]:hover {
    background-color: #333;
  }
}

In the example above, .container got display:flex (from the flex utility) and background-color:#222 (from bg-[#222]). The md:hover:bg-[#333] utility generated a media query rule for screens >=768px with the selector .md:hover:bg-[#333]:hover.

Example Output and Live Usage

Suppose we have an input CSS file like src/input.css:

/* src/input.css */
@relax;

.container {
  @apply flex bg-[#222] md:hover:bg-[#333];
}

.my-box {
  @apply fancy-border;
}

.ravi {
  @apply text-2xl;
}

.kishan {
  @apply text-3xl;
}

Here we use @relax; to trigger the plugin, and we apply several utilities:

flex, bg-[#222], and md:hover:bg-[#333] on .container.
fancy-border on .my-box (this was a custom utility from the default plugin).
text-2xl and text-3xl on .ravi and .kishan.

Running RelaxCSS on this (npx ts-node src/cli-watch.ts "src/**/*.{css,html,js,jsx,ts,tsx}" --out dist/output.css) will produce a dist/output.css roughly like:

/* RelaxCSS Preflight: box-sizing */
*,*::before,*::after{box-sizing:border-box;}
/* RelaxCSS Preflight: margin-padding */
body,h1,h2,h3,h4,h5,h6,p,ul,ol,li,figure,figcaption,blockquote,dl,dd{margin:0;padding:0;}
/* ... other preflight rules ... */

.container {
  display: flex;
  background-color: #222;
}
@media (min-width:768px) {
  .md\:hover\:bg-\[\#333\]:hover {
    background-color: #333;
  }
}
.my-box {
  border: 2px dashed magenta;
}
.ravi {
  font-size: 1.5rem;
  line-height: 2rem;
}
.kishan {
  font-size: 1.875rem;
  line-height: 2.25rem;
}

For live usage, one might have an HTML file like:

<button class="m-4">
  <span class="hover:bg-blue-500 hover:text-white md:hover:bg-blue-700 bg-[#222]">
    Hover over me
  </span>
</button>

When RelaxCSS processes this (in JIT mode), it will generate the equivalent CSS so that the button responds to hover and changes background/text color as expected.

Conclusion

RelaxCSS is a compact, flexible framework for utility-first styling, suitable for frontend developers and framework authors who want Tailwind-like productivity with a smaller footprint. It leverages a PostCSS plugin to parse utility class names (p-4, text-blue-500, hover:bg-red-200, etc.) and emit the corresponding CSS using values from a theme configuration. The CLI/JIT engine watches your files and includes only the utilities you actually use, keeping the CSS minimal. The plugin system lets you define your own utilities or copy Tailwind’s plugin approach. By supporting arbitrary values (bg-[#222]), responsive prefixes (md:) and variants (hover:), plus a built-in preflight reset, RelaxCSS covers most needs of modern utility-based development.

For advanced use, you can extend RelaxCSS by adding more functions to generateUtilityCss, writing plugins with addUtilities, or customizing the configuration. Because it’s just a PostCSS plugin and Node script, you could even integrate it into larger build tools or frameworks. Overall, RelaxCSS aims to be a learning-friendly, extensible alternative to Tailwind for projects where you want control over the utility engine’s internals. Users can build on this foundation – for example, adding support for more CSS features or improving performance – thanks to its clear architecture.

Sources: The above explanations and code snippets are drawn directly from the RelaxCSS source files (e.g. index.ts, cli-watch.ts, base.css).

Ravikisha / RelaxCSS

A next-generation, Tailwind-like JIT CSS/PostCSS plugin with a powerful plugin system, support for arbitrary values, variants (including dark mode and RTL), efficient watch mode, and CSS variable theme support. RelaxCSS can be used as a PostCSS plugin (recommended for most build pipelines) or as a standalone CLI tool.

RelaxCSS

A next-generation, Tailwind-like JIT CSS/PostCSS plugin with a powerful plugin system, support for arbitrary values, variants (including dark mode and RTL), efficient watch mode, and CSS variable theme support.

RelaxCSS can be used as a PostCSS plugin (recommended for most build pipelines) or as a standalone CLI tool.

PostCSS Plugin Usage

RelaxCSS is a drop-in PostCSS plugin. It works with PostCSS v8+ and integrates with any PostCSS-based build system (Webpack, Vite, Parcel, etc).

// postcss.config.js
const relaxcss = require('relaxcss');

module.exports = {
  plugins: [
    require('postcss-import'), // must be first
    relaxcss({
      // custom config here
    }),
    require('autoprefixer'),
    // ...
  ]
};

Supports all RelaxCSS features: JIT utilities, plugins, variants, dark mode, RTL, CSS variables, and more.
Use your relaxcss.config.js for custom configuration.
Compatible with PostCSS v8+ and all major build…

View on GitHub

npmjs.com

Building a Container Runtime from Scratch with Go (MyDocker)

Ravi Kishan — Thu, 05 Jun 2025 13:25:34 +0000

Table of Contents

Introduction: What is a Container Runtime?
Namespaces: Isolating Processes on Linux
Control Groups (cgroups): Managing Resources
Project Architecture: The MyDocker Design
- Command-Line Interface and Main.go
- Container Lifecycle (startContainer, child)
- Networking Isolation (Bridge and veth)
- Image Handling and OCI Unpacking
- Volumes and Port Mappings
Diagrams: Visualizing the Runtime
Getting Started and Resources

Introduction

Containers are lightweight, isolated environments for running applications. Unlike virtual machines, containers share the host kernel but isolate processes using kernel features like namespaces and cgroups. In this tutorial we’ll explore MyDocker, a simple container runtime written in Go, and walk through the key pieces that make it work. We’ll explain how MyDocker uses Linux namespaces (UTS, PID, network, mount, etc.) to isolate the container’s view of the system, and how it uses cgroups to limit resources. Along the way we’ll show key code snippets (e.g. startContainer, child, execContainer) and outline MyDocker’s architecture for CLI commands, networking, and image handling. By the end, you’ll see how MyDocker’s internals fit together, and how OCI image unpacking with tools like umoci and simple mount/iptables tricks provide the functionality of docker pull, run, exec, and more. We encourage you to check out the [MyDocker GitHub repository][22] and its [README][26] for examples and to try extending the code yourself.

Namespaces

Linux namespaces provide isolation by giving a process its own “view” of system resources. For example, PID namespaces mean a process can see only processes in its own container; UTS namespaces let each container have its own hostname; mount namespaces give each container its own filesystem root; network namespaces provide separate network interfaces/iptables, and so on. In other words, namespaces prevent processes in one container from seeing or affecting those in another. This isolation is a cornerstone of container security: “namespaces are quite flexible…they can be applied individually or in groups to one or more processes”. MyDocker’s container “child” process is created with clone flags for multiple namespaces (UTS, PID, NET, mount, etc.), so it runs in isolation. The code roughly follows the pattern:

// In main or run command:
cmd := exec.Command("/proc/self/exe", append([]string{"child"}, os.Args[2:]...)...)
cmd.SysProcAttr = &syscall.SysProcAttr{
    Cloneflags: syscall.CLONE_NEWUTS |
                syscall.CLONE_NEWPID |
                syscall.CLONE_NEWNET |
                syscall.CLONE_NEWNS, // etc.
}
cmd.Stdin, cmd.Stdout, cmd.Stderr = os.Stdin, os.Stdout, os.Stderr
must(cmd.Run())

// The child() function runs inside the new namespaces:
func child() {
    // e.g., set hostname inside UTS namespace
    syscall.Sethostname([]byte("mydocker"))
    // Possibly mount proc, chroot, pivot_root, etc.
    // Finally exec the requested command:
    cmd := exec.Command(os.Args[2], os.Args[3:]...)
    cmd.Stdin, cmd.Stdout, cmd.Stderr = os.Stdin, os.Stdout, os.Stderr
    must(cmd.Run())
}

As in other “container-from-scratch” examples, this pattern uses exec.Command("/proc/self/exe", "child", …) to re-invoke the same program in a new process (in new namespaces). From outside, the run command spawns the namespaced child; inside the container, the child function does setup (hostname, filesystem mounts, etc.) and then executes the user’s command. This effectively gives the container its own isolated environment separate from the host.

Figure: Container runtime architecture. MyDocker creates a namespaced “child” process for each container, mounts a fresh root filesystem (unpacked from an OCI image), applies cgroup limits, and sets up networking (bridge mydocker0 and veth pair). The CLI (main.go) drives commands like run, exec, pull, etc.

In summary, namespaces ensure that processes in MyDocker containers see only their own CPU, memory, filesystems, networks, and process list. This is one of the fundamental layers of container isolation. (MyDocker’s README also highlights this as a core feature: “Container process isolation using Linux namespaces (UTS, PID, NET, MNT)”.)

Control Groups (cgroups)

While namespaces isolate what a process sees, cgroups control how much of a resource a process can use. A control group (cgroup) is a Linux kernel feature that limits, accounts for, and isolates resource usage (CPU, memory, I/O, etc.) of a group of processes. MyDocker uses cgroups so that each container process has its own CPU and memory limits (as defined by CLI flags). For example, it might create a new cgroup under /sys/fs/cgroup/cpu/mydocker/<id> and write the PID of the container process into it, along with any limits (like cpu.shares or memory.limit_in_bytes). This means the container will only get a fraction of CPU or a fixed amount of memory, protecting the host and other containers.

“Cgroups are a kernel feature that allows you to partition and limit the system resources… that a group of processes can use. Think of them as virtual cages where you can corral your processes and set rules for their behavior”. (This quote describes cgroups in general; MyDocker uses them specifically for CPU and memory limits.)

For instance, MyDocker might contain code like:

// Simplified: create a cpu cgroup for the container
cgroupPath := filepath.Join("/sys/fs/cgroup/cpu/mydocker", containerID)
os.MkdirAll(cgroupPath, 0755)
// write the container's PID into the cgroup.procs file
os.WriteFile(filepath.Join(cgroupPath, "cgroup.procs"), []byte(pidStr), 0644)
// optionally set limits like cpu.shares or memory.limit_in_bytes

This ensures each container is “in its own cage”. The MyDocker README emphasizes resource control: “Resource control via cgroups (CPU & Memory)”. By combining cgroups with namespaces, the runtime isolates both the view and resources of each container process, similarly to how Docker does it behind the scenes.

Project Architecture

MyDocker’s source is structured simply (see [Architecture Overview][100]). At the top level we have:

main.go – The CLI entry point: parses commands like run, exec, pull, etc. It calls functions like startContainer() or execContainer() accordingly.
cgroups/ – Go package to set up cgroup directories and limits.
network/ – Go package to create a bridge (mydocker0) and virtual ethernet (veth) pairs for container networking.
helper.c – A small C program that is used to join existing namespaces (see below).
Other files: e.g. configuration templates, documentation.

The architecture overview in the README summarizes this:

“Architecture Overview: main.go — The CLI and container runtime entry point; cgroups/ — resource limits; network/ — bridge networks/veth; /var/lib/mydocker/ — stores metadata/images”.

So when you run something like sudo ./mydocker run -v /data:/data -p 8080:80 ubuntu:22.04 sh, what happens? A brief walkthrough:

CLI (main.go): The program parses the run command and container options (image name, mounts, ports, etc.). It likely calls a function startContainer(containerID, command, flags...).
startContainer: This function creates a unique container ID, sets up storage (image unpack, rootfs), sets up networking, then spawns a child process in new namespaces (using exec.Command("/proc/self/exe", ...) as above). It also records container metadata (like PID, rootfs path) under /var/lib/mydocker/.
Child process: In the new namespaces, it does further initialization: e.g., performs chroot/pivot_root into the unpacked image root filesystem; mounts the host directory if -v was given; configures networking (calls net.SetupVeth() to move one end of a veth into this namespace); then finally execs the user’s command (e.g. sh).
Networking: The network/ code ensures there is a Linux bridge (e.g. mydocker0) on the host. It creates a veth pair, moves one end into the child’s net namespace (as eth0), and attaches the other end to the mydocker0 bridge, giving the container network access (with its own IP).
Cgroups: Concurrently, before or after spawning the child, MyDocker creates new cgroup entries under CPU/memory controllers and adds the child’s PID, enforcing resource limits on that container.
Image Unpacking: For pulling images, MyDocker uses umoci. The pull command downloads an OCI image (like Ubuntu) and uses umoci unpack to extract it into a directory under /var/lib/mydocker. Umoci documentation explains: “umoci unpack - Unpacks an OCI image tag into a runtime bundle”. In other words, MyDocker relies on umoci to convert a container image into a rootfs directory with config, just like Docker does with layered filesystems.

Command-Line Interface and Main.go

The main.go file defines the CLI commands (run, exec, ps, etc.) using a library like urfave/cli. For example, when the user runs mydocker run ..., it ends up invoking something like:

func runCommandAction(ctx *cli.Context) error {
    imageName := ctx.Args().Get(0)
    cmd := ctx.Args().Get(1)
    flags := ctx.GlobalFlags()
    containerID := generateID()
    startContainer(containerID, imageName, cmd, flags)
    return nil
}

The core functions include startContainer (for run) and ExecContainer (for exec). In MyDocker, startContainer will unpack the image if needed, set up cgroups/networks, then clone a new process.

The execContainer function (called by mydocker exec) is also interesting. It finds the PID of an existing container process (by reading stored metadata) and then uses exec.Command("/proc/self/exe", "exec") to fork a helper process that enters that container’s namespaces (via a small C helper). Part of the code might look like:

func ExecContainer(containerID string, comArray []string) {
    pid, err := getPidByContainerId(containerID)
    // Set environment variables for the helper C program:
    cmd := exec.Command("/proc/self/exe", "exec")
    os.Setenv("mydocker_pid", pid)
    os.Setenv("mydocker_cmd", strings.Join(comArray, " "))
    cmd.Stdin, cmd.Stdout, cmd.Stderr = os.Stdin, os.Stdout, os.Stderr
    cmd.Run()
}

This tells the re-invoked process to run the "exec" branch of main(). The helper C code (in helper.c) sees mydocker_pid/mydocker_cmd and performs setns() calls to join the PID/UTS/NET namespaces of that container, then uses system(mydocker_cmd) to run the desired command inside the container. (In effect, mydocker exec adds your shell to the existing container’s namespaces, letting you run commands inside it.) The Chinese blog [89] illustrates this pattern clearly. The key idea is: we fork a new process that points itself into the container’s namespaces and execs the command as if we were inside the container.

Container Lifecycle (`startContainer`, `child`)

Putting it all together, MyDocker’s container lifecycle roughly is:

Start: User runs mydocker run .... The Go main.go calls startContainer(...).
Setup: In startContainer, MyDocker creates a directory for the container under /var/lib/mydocker/<id>. It unpacks the OCI image rootfs there (if not done already), creates cgroups, sets up network (bridge/veth), and prepares the command arguments.

Clone (run): The code then does something like:

cmd := exec.Command("/proc/self/exe", append([]string{"child"}, commandArgs...)...)
cmd.Stdin, cmd.Stdout, cmd.Stderr = os.Stdin, os.Stdout, os.Stderr
cmd.SysProcAttr = &syscall.SysProcAttr{
    Cloneflags: CLONE_NEWUTS | CLONE_NEWPID | CLONE_NEWNET | CLONE_NEWNS,
    UidMappings: ...,
    GidMappings: ...,
}
cmd.Run() // blocks until container process exits

This effectively forks into a child process that will run mydocker child ....

Child setup: In the child() function inside Go, the process is now in fresh namespaces. It performs actions similar to Docker’s container init:

- Calls `syscall.Chroot()` or `pivot_root()` to switch the root filesystem to the unpacked image.

- Applies mounts and volume binds (`syscall.Mount()`) for any `-v host:container` flags.

- Calls `net.SetupVeth()` to move one end of the veth into this namespace and bring up the network interface.

- Executes the container’s init process (e.g., `exec.Command("/bin/sh")`).

Run: The container process (PID 1 in its PID namespace) starts and runs user code. Meanwhile, the parent Go process (still the original CLI) waits (or returns immediately if detached).
Stop: When the container’s main process exits (e.g. you exit the shell), the child function returns. startContainer (the parent) will then do cleanup: remove cgroups, delete metadata, etc.

The code for startContainer and child in MyDocker is similar in spirit to many "from-scratch Docker" examples (e.g. [86]). For instance, the parent uses exec.Command("/proc/self/exe", "child", …) to create the child. Inside child, Go code uses syscalls (Mount, Chroot, Sethostname, etc.) to finish setting up the namespace, then exec.Command to run the actual command. Though we can’t cite the MyDocker source directly here, conceptually it follows the pattern above.

Networking

By default, containers should be able to talk to each other and the outside world (on certain ports). MyDocker’s network/ package likely does the following (in Go, via the vishvananda/netlink library or raw syscalls):

Ensure a Linux bridge exists (named mydocker0). If not, create it with ip link add name mydocker0 type bridge.
For each new container, create a veth pair (e.g. veth-host and veth-container). Move veth-container into the new namespace of the child (with netlink.LinkSetNsFd) and rename it to eth0.
Bring up eth0 inside the container and assign it an IP (e.g. via ip addr).
Attach veth-host to the mydocker0 bridge and bring it up on the host.

This way, containers get an IP on the mydocker0 network, and host-side NAT (iptables MASQUERADE) handles outbound traffic and port mapping. MyDocker’s README mentions a custom bridge network (mydocker0) and veth pairs for network isolation. (In our blog, we won’t go into all the iptables details, but that’s how host ports get forwarded: the CLI probably calls iptables -t nat rules so that -p host:container flags forward TCP from the host port to the container’s IP:port.)

Image Handling and OCI Unpacking

Container images (like ubuntu:22.04) come in the OCI/Docker image format. MyDocker supports pulling and unpacking these images using the umoci tool. The mydocker pull command likely shells out to umoci pull or similar, then umoci unpack. As the umoci manual states: “umoci unpack – Unpacks an OCI image tag into a runtime bundle”. In practice, MyDocker runs something like:

umoci unpack --image ubuntu:22.04 /var/lib/mydocker/images/ubuntu_22.04

This extracts the image layers and config into a directory that becomes the container’s root filesystem. MyDocker then stores this location (under /var/lib/mydocker/) so that future run commands can use the rootfs directly without repulling. The unpacked bundle includes /rootfs with all files and a JSON config. MyDocker’s Go code then chroot-es into that /rootfs when starting a container.

Using umoci (or a similar OCI utility) is important because it handles the layered filesystem format of images. Without overlay support, MyDocker unpacks into a single directory per image. The README cites “Simple OCI image unpacking using umoci” as a feature.

Volumes and Port Mappings

Volumes (-v): If the user specifies -v /host/dir:/container/dir, MyDocker will mount a bind mount inside the container namespace. The Go code in child() would do something like:

syscall.Mount("/host/dir", "/container/dir", "", syscall.MS_BIND, "")

after switching to the new root. This makes the host’s directory appear at the given path in the container. It relies on the mount namespace being isolated, so only the container sees the mount (the host’s filesystem is shared, but the namespace separates the mount list).

Port mappings (-p): For -p hostPort:containerPort, the runtime must forward network traffic. A simple approach: on the host, use iptables to NAT traffic from hostPort into the container’s IP and containerPort. For example:

iptables -t nat -A PREROUTING -p tcp --dport <hostPort> -j DNAT --to-destination <containerIP>:<containerPort>
iptables -t nat -A POSTROUTING -j MASQUERADE

This way, if a service inside the container listens on containerPort, requests to localhost:hostPort on the host will reach it. MyDocker’s implementation likely sets up such iptables rules automatically when starting the container, and removes them on stop. This achieves “port mapping” similar to Docker.

Diagrams

Below are some visual aids (using PlantUML) to illustrate the architecture and isolation concepts. These diagrams are simplified schematics.

These diagrams outline how the host CLI and services collaborate to create an isolated container process. In particular, the second diagram emphasizes that once the container process (C) is created, it has its own namespace instances and cannot see the host’s unrelated processes or network stacks.

Getting Started and Resources

MyDocker is intended as a learning tool to explore container internals. It “demonstrates how containerization works under the hood” and helps you understand namespaces, cgroups, and image formats. You can try it out by following the README instructions: for example, pull an image (mydocker pull ubuntu:22.04) and run it (mydocker run -it -v /data:/data -p 8080:80 ubuntu:22.04 bash) as shown in the usage examples. You’ll see your process isolated (check ps and hostname inside the container, and network connectivity to the bridge).

We encourage you to explore the Project Files (which includes source code and examples) and even extend it. Possible exercises include adding features like Dockerfile builds, overlayfs support, or enhanced networking. By tinkering with MyDocker’s code, you’ll gain a deep understanding of what happens in every docker run command. Happy hacking and containerizing!

Check out the github repo:

Ravikisha / MyDocker

MyDocker is a lightweight container runtime built from scratch in Go that demonstrates how containerization works under the hood — similar to Docker but in a simplified form.

🐳 MyDocker

MyDocker is a lightweight container runtime built from scratch in Go that demonstrates how containerization works under the hood — similar to Docker but in a simplified form.

👉 GitHub Repository

🚀 Features

Container process isolation using Linux namespaces (UTS, PID, NET, NS)
Resource control via cgroups (CPU & Memory)
Volume mounting (-v host:container)
Port mapping support (-p host:container)
Simple OCI image unpacking using umoci
Container image pulling, listing, and execution
Custom bridge network (mydocker0) and veth pairs for network isolation
Command-line interface similar to Docker (run, exec, ps, stop, pull, images, version)

🎯 Architecture

📦 Installation

Requirements

Go 1.19+

Root access (for namespace and networking)

umoci tool installed and in $PATH

Linux OS (recommended: Ubuntu)

git clone https://github.com/ravikisha/mydocker.git
cd mydocker
go build -o mydocker main.go
sudo ./mydocker version

…

View on GitHub

Introducing RelaxLang: A Beginner-Friendly Programming Language

Ravi Kishan — Thu, 16 Jan 2025 19:30:05 +0000

In the vast and ever-evolving world of programming languages, creating one from scratch is a feat that blends art, science, and a touch of magic. Today, I am excited to introduce RelaxLang, a simple yet powerful interpreted programming language. Inspired by Robert Nystrom's Crafting Interpreters and the Lox programming language, RelaxLang is designed to be accessible for beginners while being feature-rich for enthusiasts who want to dive deeper into language design and implementation.

Why RelaxLang?

RelaxLang stems from a vision to provide a lightweight, easy-to-understand programming language that serves as both a learning tool and a practical solution for basic scripting needs. Built with Java and C, it offers:

Dynamic Typing: Simplifies coding by inferring variable types at runtime.
First-Class Functions: Enables functional programming paradigms by treating functions as first-class citizens.
Classes and Inheritance: Introduces object-oriented programming with a straightforward syntax.
Built-In Standard Library: Provides out-of-the-box utilities for string manipulation, array operations, and more.

Whether you're an aspiring developer eager to learn how programming languages work or a seasoned programmer seeking an educational tool, RelaxLang caters to you.

Architecture

Key Features of RelaxLang

1. Dynamic Typing

In RelaxLang, you don’t need to worry about specifying types for variables. The interpreter takes care of it, allowing you to focus on logic and creativity.

var name = "RelaxLang";  // Automatically inferred as String
var version = 1.0;       // Automatically inferred as Float
var isActive = true;     // Automatically inferred as Boolean

print(name);            // Output: RelaxLang
print(version);         // Output: 1.0
print(isActive);        // Output: true

2. First-Class Functions

Functions are versatile in RelaxLang. They can be assigned to variables, passed as arguments, and even returned from other functions.

fun add(a, b) {
    return a + b;
}

var sum = add(5, 3);
print(sum);  // Output: 8

fun operate(func, x, y) {
    return func(x, y);
}

var result = operate(add, 10, 15);
print(result);  // Output: 25

3. Classes and Inheritance

RelaxLang supports object-oriented programming, making it a great tool to understand and implement OOP concepts.

class Animal {
    var name;

    init(name) {
        this.name = name;
    }

    fun speak() {
        print(this.name + " makes a sound.");
    }
}

class Dog < Animal {
    fun speak() {
        print(this.name + " barks.");
    }
}

var myDog = Dog("Buddy");
myDog.speak();  // Output: Buddy barks.

4. Control Flow

With intuitive if-else statements and loops, you can control the flow of your programs effortlessly.

var age = 18;

if (age < 18) {
    print("Minor");
} else {
    print("Adult");
}

for (var i = 0; i < 5; i = i + 1) {
    print(i);  // Output: 0 1 2 3 4
}

How to Get Started

1. Prerequisites

Ensure you have the following installed:

Java JDK 11 or later (Download here)
(Optional) Docker for a containerized setup

2. Installation

Clone the Repository:

git clone https://github.com/Ravikisha/RelaxLang.git
cd RelaxLang

Compile the Source Code:

javac src/*.java

3. Running RelaxLang

Using the JAR File:

java -jar lox.jar

Using Docker:

docker pull ravikishan63392/relaxlang:lastest
docker run -it ravikishan63392/relaxlang:lastest

Example Usage

RelaxLang scripts are simple to write and execute. For instance, here’s a script example.rl:

fun greet(name) {
    print("Hello, " + name + "!");
}

greet("World");

Run it with:

java -jar lox.jar example.rl

The Technical Journey

RelaxLang’s implementation involves:

Lexical Analysis: Breaking down source code into tokens.
Parsing: Constructing an Abstract Syntax Tree (AST) from tokens.
Interpreting: Executing the AST by traversing it node by node.

Developed in Java for platform independence and in C for low-level optimizations, RelaxLang’s design reflects a balance between simplicity and functionality.

Resources and Contributions

Docker Image:

RelaxLang Docker Image

GitHub Repository:

RelaxLang on GitHub

We welcome contributions! Whether it's bug fixes, feature requests, or documentation improvements, your input makes RelaxLang better. Please check out the contributing guidelines in the repository.

Final Thoughts

RelaxLang is not just a programming language; it’s a journey into the heart of language design. By exploring its features, experimenting with scripts, and diving into its implementation, you can gain insights into how modern programming languages work.

Give RelaxLang a try and embark on this exciting adventure. Let’s code, learn, and relax!

Building RelaxTube: A Scalable Video Transcoding and Streaming Application

Ravi Kishan — Tue, 14 Jan 2025 18:34:42 +0000

Introduction

RelaxTube is a feature-rich and scalable application designed to demonstrate the workflow of video transcoding and streaming. The project highlights the use of modern technologies like Node.js, React, Kafka, FFmpeg, MongoDB, and Docker. It efficiently processes videos by transcoding them into multiple quality levels, segmenting them for smoother streaming, and generating thumbnail previews.

This blog explores the architecture, key features, tech stack, installation, and potential enhancements for RelaxTube.

Key Features

Video Transcoding: Converts videos into multiple quality levels (360p, 480p, 720p, 1080p) using FFmpeg.
HLS Segmentation: Generates video segments for efficient HTTP Live Streaming (HLS) playback.
Thumbnail Generation: Automatically creates thumbnail previews for each uploaded video.
Batch Processing: Supports concurrent video processing using Kafka message queues.
Scalable Design: Built to handle increased loads and integrate with distributed systems.
Storage and Metadata: Manages video files in local storage and metadata in MongoDB.

Project Architecture

Components

Frontend (React): Provides a user-friendly interface for video uploads, management, and playback.
Backend (Node.js with Express): Handles API requests, video processing workflows, and communication with Kafka.
Kafka: Manages message queues for efficient batch processing.
Transcoding Service (FFmpeg): Handles video transcoding, segmentation, and thumbnail creation.
MongoDB: Stores metadata like video information, quality levels, and thumbnails.
File Storage: Stores processed video files and thumbnails locally.

Tech Stack

Node.js: Backend logic and API endpoints.
React: Frontend for user interaction.
Kafka: Manages distributed message queues for scalability.
FFmpeg: Performs video transcoding, segmentation, and thumbnail generation.
MongoDB: Stores metadata and provides quick access to processed data.
Docker: Ensures easy setup and consistent environments.
TailwindCSS: Enhances the frontend with modern styling.

Installation and Setup

Prerequisites

Install Docker.
Install Node.js (v16 or higher).
Clone the repository:

   git clone https://github.com/Ravikisha/RelaxTube.git
   cd RelaxTube

Steps

Run Docker Compose

   docker-compose up -d

Install Dependencies

   cd frontend && npm install
   cd ../backend && npm install
   cd ../transcoding-service && npm install

Start Services
- Backend:
```
 cd backend
 npm run dev
```

Frontend:
```
 cd frontend
 npm run dev
```
Transcoding Service:
```
 cd transcoding-service
 npm run dev
```

Access the Application Open your browser and navigate to http://localhost:3000.

Usage

Upload Videos: Users can upload videos through the frontend interface.
Processing: The backend processes the videos by:
- Transcoding them to multiple quality levels.
- Segmenting videos for HLS playback.
- Generating thumbnails.
Streaming: Processed videos are available for streaming via the frontend.
Batch Processing: Upload multiple videos for concurrent processing.

Screenshots

Homepage

Video Playback

Quality Selection

Upload Interface

Batch Upload

Scalability Features

Batch Processing: Process multiple videos simultaneously using Kafka.
Distributed Workers: Scale horizontally by adding workers for transcoding tasks.
Load Balancing: Distribute incoming requests across multiple backend servers.
Cloud Storage: Potential integration with AWS S3 or Google Cloud Storage for large-scale storage.
Monitoring: Use tools like Prometheus or Grafana for real-time monitoring and performance tracking.

Future Enhancements

Cloud deployment for global access and scalability.
Advanced analytics for tracking user interactions and video performance.
User authentication and access control.
Caching mechanisms for faster access to frequently requested content.

Contributing

We welcome contributions to RelaxTube! Feel free to submit pull requests, report issues, or suggest new features.

License

RelaxTube is licensed under the MIT License. See the LICENSE file for details.

Start exploring RelaxTube by visiting the GitHub Repository!

Building Scalable Web Applications with Microfrontends: A Detailed Walkthrough of Microfrontend Blog

Ravi Kishan — Sun, 29 Dec 2024 14:23:36 +0000

Introduction

In the rapidly evolving world of web development, creating scalable, maintainable, and modular applications is more important than ever. Enter microfrontend architecture—a game-changing approach that divides a monolithic frontend into smaller, independently deployable pieces.

This blog introduces Microfrontend Blog, a real-world implementation of microfrontends built using cutting-edge technologies like React, TailwindCSS, Clerk, Module Federation, and Firebase Firestore. Whether you're an experienced developer or just getting started with microfrontends, this project is a comprehensive guide to building modular web applications.

GitHub Repository: Microfrontend Blog

Project Overview

Microfrontend Blog is a blogging platform designed to demonstrate the power of microfrontend architecture. It splits the application into five key modules:

Auth Microfrontend: Handles user authentication using Clerk.
Dashboard Microfrontend: Allows users to create, edit, and manage blogs.
Viewer Microfrontend: Displays blogs with comment functionality.
Shared Components: A library of reusable components like headers, footers, and blog cards.
Container: Orchestrates the integration of all microfrontends.

By adopting Module Federation, each microfrontend is developed and deployed independently, enabling seamless collaboration across teams and simplifying the scaling process.

Features

Authentication: Secure login and signup with Clerk.
Blog Management: A rich dashboard for managing blogs.
Blog Viewing: Interactive blog display with a comments section.
Responsive UI: Styled with TailwindCSS for consistency across devices.
Scalability: Independent deployment of microfrontends.

Technologies Used

React: The foundation for building the UI.
TailwindCSS: A utility-first CSS framework for modern designs.
Clerk: A robust authentication library.
Firebase Firestore: Cloud-based database for blog storage.
Module Federation: Simplifies microfrontend integration.
Webpack: Efficient module bundler for development and production.

Architecture Diagram

The architecture demonstrates the interaction between microfrontends, the container, and backend services:

Getting Started

1. Prerequisites

Install Node.js (v16+).
Clone the repository:

  git clone https://github.com/Ravikisha/Microfrontend-Blog.git
  cd Microfrontend-Blog

2. Install Dependencies
For each microfrontend and shared components, run:

cd <microfrontend-folder>
npm install

3. Start the Development Server

npm start

4. Access the Application
Visit http://localhost:3005 to view the application.

Screenshots

Home Page:

Login Page:

Create Blog:

View Blog:

MicroFrontend Screenshots

Auth Microfrontend:

Dashboard Microfrontend:

Viewer Microfrontend:

Shared Components:

Container:

Key Benefits of Microfrontend Architecture

Independent Development: Teams can work on different microfrontends without stepping on each other's toes.
Scalability: Easily scale individual modules based on demand.
Reusability: Shared components streamline development and ensure design consistency.

Conclusion

The Microfrontend Blog project serves as a practical example of how microfrontend architecture can simplify development and improve scalability. With technologies like React, TailwindCSS, and Module Federation, developers can create robust and maintainable applications that meet modern web development demands.

Explore the code and start building your modular applications today!

GitHub Repository: Microfrontend Blog

Would you like me to add more details, such as common troubleshooting tips or deeper dives into individual microfrontends?

Introducing Stylesnap: Optimize Your CSS Like Never Before

Ravi Kishan — Sun, 29 Dec 2024 14:04:56 +0000

In the ever-evolving world of web development, efficiency and optimization are paramount. Meet Stylesnap, a cutting-edge solution for CSS optimization that simplifies your workflow and boosts performance. Designed for developers, this handy tool minimizes your CSS files by analyzing your project’s content and retaining only the styles you truly need.

What is Stylesnap?

Stylesnap is an NPX package tailored for modern web development. It scans your codebase—HTML, JSX, or any supported files—and generates a lightweight, optimized CSS file that eliminates unused styles. Whether you're using popular frameworks like Bootstrap, TailwindCSS, or custom CSS, Stylesnap has you covered.

Key Features

Selective CSS Extraction: Extracts only the required class names, tags, and selectors.
Framework Compatibility: Works seamlessly with CSS frameworks or custom styles.
Minification: Automatically minifies the generated CSS for improved performance.
Custom Configurations: Offers a customizable workflow using stylesnap.config.json.
Command-Line Simplicity: Easy-to-use CLI for quick integration.

Why Choose Stylesnap?

Enhanced Performance: Smaller CSS files mean faster page loads and better user experience.
Maintainability: Eliminates unused CSS, making your stylesheets cleaner and easier to manage.
Flexibility: Compatible with various frameworks and custom setups.
Developer-Friendly: Simple installation, intuitive CLI options, and detailed documentation.

Getting Started

Installation

Use npm to install Stylesnap as a development dependency:

npm install stylesnap --save-dev

Or run it directly with NPX:

npx stylesnap

Usage

Stylesnap’s CLI makes it easy to optimize your CSS. Here’s a quick example:

Initialize Configuration:

   npx stylesnap --init

This creates a stylesnap.config.json file in your project.

Update Configuration: Edit the file to suit your project’s needs:

   {
     "content": ["./src/**/*.html", "./src/**/*.jsx"],
     "css": "./src/styles.css",
     "output": "./dist/optimized.css",
     "minify": true
   }

Run Stylesnap:

   npx stylesnap

Your optimized CSS will be saved at the specified output location.

Real-World Benefits

By using Stylesnap, you’ll see immediate improvements in your development and deployment process:

Faster Load Times: Reduced CSS file size enhances website speed.
Smaller Builds: Ideal for production environments.
Streamlined Debugging: With unused CSS eliminated, debugging becomes simpler.

Contribute

Stylesnap is open-source, and contributions are welcome! If you encounter any issues or have ideas for improvement, feel free to open an issue or submit a pull request.

Start optimizing your CSS today with Stylesnap! 🚀 Streamline your workflow, boost performance, and take your web development projects to the next level.

A Comprehensive Guide to Building a Single Sign-On (SSO) Gateway with Node.js

Ravi Kishan — Sun, 22 Dec 2024 17:13:18 +0000

Single Sign-On (SSO) systems have become critical in today's interconnected application ecosystems. By allowing users to log in once and access multiple applications seamlessly, SSO simplifies authentication, enhances user experience, and bolsters security. This blog dives into the implementation of an SSO Gateway using Node.js, Express, and MongoDB, guiding you through its features, architecture, setup, and best practices.

What is a Single Sign-On Gateway?

An SSO Gateway is a centralized authentication system where users authenticate once and gain access to multiple interconnected applications without needing to reauthenticate. The Node-SSO-Gateway project demonstrates a robust yet simple implementation of such a system.

Key Features of the Node-SSO-Gateway

Centralized Authentication
- Users log in via a single SSO server, eliminating the need for multiple logins.
Token-Based Authorization
- Secure, stateless communication between the SSO server and consumer applications via JSON Web Tokens (JWT).
Cross-Domain Session Management
- Maintain seamless user sessions across multiple applications and domains.
MongoDB Integration
- Secure storage of user credentials with robust password hashing (e.g., bcrypt).
Dynamic Consumer App Registration
- Consumer applications can dynamically register themselves with the SSO server for authentication.
Logout Functionality
- Supports global and local session termination for enhanced security.

System Architecture

The system is divided into three primary components:

SSO Server

The central hub that authenticates users, manages sessions, and issues JWT tokens.
Consumer Applications (Clients)

Applications relying on the SSO server for authentication. Each client establishes a local session after verifying the token.
MongoDB

A database backend to securely store user data, including email and hashed passwords.

Architecture Diagram

How Does It Work?

User Login
- Users log in through the SSO server. Upon successful authentication, the server issues a JWT token and redirects the user to the desired consumer app.
Token Validation
- Consumer apps verify the JWT token with the SSO server before granting access to protected resources.
Session Management
- Both global (SSO server) and local (consumer app) sessions are managed, ensuring secure and consistent access.
Logout
- Users can log out from the SSO server, terminating the global session, or from a consumer app, terminating the local session.

Setting Up the Node-SSO-Gateway

1. Prerequisites

Node.js and npm installed.
MongoDB instance running (local or cloud-based).
Basic knowledge of JWT, Express, and MongoDB.

2. Clone the Repository

git clone https://github.com/Ravikisha/Node-SSO-Gateway.git
cd Node-SSO-Gateway

3. Install Dependencies

Navigate to the root directory of each component and install the required packages.

For the SSO Server

cd server
npm install

For Consumer Applications

cd client1
npm install

# In another terminal
cd client2
npm install

4. Configure MongoDB

Create a .env file in both the SSO Server and consumer apps with the following content:

MONGODB_URI=mongodb://localhost:27017/sso-db

5. Start the Applications

Start the SSO Server:

cd server
npm run dev

Start the consumer apps:

cd client1
npm run dev

# In another terminal
cd client2
npm run dev

6. Test the System

Visit http://localhost:3000 to access the SSO server login page.
Successfully log in to be redirected to consumer apps (http://localhost:3001 and http://localhost:3002).

Adding New Consumer Applications

Create a new app following the structure of client1.
Register the app’s domain in the SSO Server’s allowedOrigin configuration.

   const allowedOrigin = {
       "http://localhost:3001": true,
       "http://localhost:3002": true,
       "http://localhost:3003": true,
   };

Redirect authentication requests to the SSO Server.

Security Best Practices

HTTPS Everywhere
- Use HTTPS in production to ensure encrypted communication.
Secure JWT Storage
- Store JWT securely, preferably in HTTP-only cookies, to prevent XSS attacks.
Validate Origins
- Validate consumer app origins to prevent unauthorized requests.
Password Hashing
- Use strong hashing algorithms like bcrypt for storing user passwords.

Logout Functionality

Local Logout
- Removes the session from the consumer app only.
Global Logout
- Terminates the session on the SSO Server, logging the user out from all consumer apps.

Screenshots

Login Page

SSO Server Page

Consumer Application (Client1)

Consumer Application (Client2)

Conclusion

The Node-SSO-Gateway project offers a secure and scalable solution for centralized authentication across multiple applications. By leveraging modern web technologies like Node.js, Express, and JWT, the system ensures a seamless user experience and robust security. Whether you're building a microservices-based architecture or integrating multiple platforms, this SSO solution is a solid foundation for managing authentication effectively.

Explore the repository here and get started with centralized authentication today!

Building a Feature-Rich Load Balancer in TypeScript: A Detailed Overview

Ravi Kishan — Sun, 22 Dec 2024 16:45:02 +0000

Load balancers are essential components of modern distributed systems, ensuring scalability, fault tolerance, and optimal resource utilization. In this blog, we’ll explore the development and capabilities of a custom Load Balancer Implementation in TypeScript—a project that combines advanced load-balancing algorithms, health checks, self-healing mechanisms, and webhook notifications. This implementation mirrors the functionality of industry-standard tools like NGINX and HAProxy.

GitHub Repository

You can explore the complete project on GitHub: Load Balancer Implementation.

Key Features

Easy Configuration:

Configure all aspects of the load balancer through a config.json file. This includes backend server details, health check intervals, and load-balancing algorithms.
Load Balancing Algorithms:
- Random: Requests are sent to a randomly selected backend server.
- Round-Robin: Requests are distributed sequentially among backend servers.
- Weighted Round-Robin: Backend servers are prioritized based on assigned weights.
Health Checks:

Periodic pings to backend servers ensure only healthy servers receive traffic.
Self-Healing:

Automatically attempts to recover downed servers, with a configurable success rate.
Retries and Redirects:

Failed requests are retried on alternative healthy servers.
Webhook Alerts:

Notify administrators of server failures via custom webhook triggers. Alerts include:
- Individual server failures.
- Total backend server failure.
Scalability:

The modular design allows for easy addition or removal of backend servers.

Project Structure

The repository contains the following components:

Backend Server Simulation: Simulates multiple backend servers for load balancing.
Load Balancer Core: Manages traffic, health checks, retries, and notifications.
Configuration File: Allows users to define the behavior of the load balancer.

Getting Started

Prerequisites

Install Node.js and npm.
Clone the repository:

   git clone https://github.com/Ravikisha/Load-Balancer-Implementation.git
   cd Load-Balancer-Implementation
   npm install

Running the Application

Start Backend Servers: Run multiple backend servers on different ports using the command:

   npm run dev:be 8081
   npm run dev:be 8082
   npm run dev:be 8083

Launch the Load Balancer: Start the load balancer on the specified port:

   npm run dev:lb 8000

Send Requests: Use a tool like Postman or Curl to send HTTP requests to the load balancer at http://localhost:8000.

Testing and Monitoring

Simulate Backend Server Failures:
- Kill a backend server process.
- Observe automatic request redirection to other healthy servers.
Webhook Alerts:
- Configure a webhook URL in config.json for real-time alerts.
- Use services like Typed Webhook to test notifications.
Self-Healing:
- Check the logs for attempts to restart failed servers.

Configuration Options

The config.json file governs the behavior of the load balancer. Key parameters include:

{
  "lbPORT": 8000,
  "_lbAlgo": "rr",
  "be_servers": [
    { "domain": "http://localhost:8081", "weight": 1 },
    { "domain": "http://localhost:8082", "weight": 1 },
    { "domain": "http://localhost:8083", "weight": 1 }
  ],
  "be_retries": 3,
  "health_check_interval": 30000,
  "send_alert_webhook": "https://webhook.site/your-webhook",
  "enableSelfHealing": true
}

_lbAlgo: Choose between rand, rr, or wrr.
be_servers: Define backend servers and their weights.
send_alert_webhook: Specify a webhook URL for notifications.
enableSelfHealing: Enable or disable server recovery attempts.

Insights and Learning Outcomes

Developing this load balancer provided insights into:

Traffic Distribution Techniques: Understanding how different algorithms impact performance and fairness.
Fault Tolerance: Designing systems that gracefully handle failures and recover automatically.
Alerting Mechanisms: Using webhooks to keep administrators informed in real-time.
Configuration Management: Simplifying user experience through JSON-based settings.

Challenges and Future Scope

Challenges:

Ensuring low latency during health checks and retries.
Managing detached processes spawned during self-healing.

Future Enhancements:

Enhanced Health Checks: Add support for more complex health-check mechanisms.
SSL/TLS Support: Enable secure communication between clients and backend servers.
Dynamic Scaling: Integrate with cloud APIs to dynamically scale backend server pools.

Conclusion

This project demonstrates how a TypeScript-based load balancer can achieve features similar to enterprise-grade solutions like NGINX or AWS ELB. With robust fault tolerance, advanced load-balancing algorithms, and real-time alerting, this implementation serves as a practical example for developers looking to understand the inner workings of load balancers.

Explore the project on GitHub, try it out, and contribute to its future enhancements!

Introducing GitaVerse: Access Bhagavad Gita Verses Programmatically 🚀

Ravi Kishan — Tue, 17 Dec 2024 15:55:10 +0000

In the world of modern development, spiritual and literary texts can be made more accessible to developers through clean APIs and libraries. GitaVerse is a modern TypeScript library that enables you to access, explore, and retrieve shlokas (verses) from the Bhagavad Gita with ease.

🌟 What is GitaVerse?

GitaVerse is a TypeScript-based NPM library that allows developers to programmatically fetch the Bhagavad Gita's verses (shlokas), including translations, synonyms, and original Devanagari text.

The Bhagavad Gita is a profound Hindu scripture consisting of 700 verses across 18 chapters. With GitaVerse, you can:

Retrieve individual verses based on Chapter and Verse number.
Fetch all shlokas in a specific chapter.
Access translations, synonyms, and meanings in a structured format.
Build spiritual apps, educational tools, or study tools effortlessly.

🚀 Features of GitaVerse

✅ Fetch Any Shloka: Get verses from any chapter with full details.
✅ Detailed Information: Includes Devanagari text, verse translations, synonyms, and multiple meanings.
✅ Organized Data: All data is structured and typed with TypeScript interfaces for ease of use.
✅ Easy-to-Use API: Clean class-based methods for developers.
✅ Lightweight: Minimal dependencies for faster integration.
✅ TypeScript Support: Full type safety for robust development.

📥 Installation

You can install GitaVerse using npm or yarn:

npm install gitaverse

yarn add gitaverse

🔧 How to Use GitaVerse

Here’s a quick guide on how you can use the GitaVerse library.

1. Import GitaVerse and Initialize

Start by importing the GitaLibrary class and initializing it:

import { GitaLibrary } from "gitaverse";

const gita = new GitaLibrary();

2. Fetch Metadata About the Bhagavad Gita

Get an overview of the Bhagavad Gita, such as the total chapters and verses:

const metadata = gita.getDescription();
console.log(metadata);

/*
Output:
{
  title: "Bhagavad Gita",
  description: "The Bhagavad Gita, often referred to as the Gita, is a 700-verse Hindu scripture that is part of the Indian epic Mahabharata.",
  totalChapters: 18,
  totalVerses: 700
}
*/

3. Fetch All Shlokas in a Chapter

To retrieve all the verses from a specific chapter, use getChapter():

const chapter1Shlokas = gita.getChapter(1);

chapter1Shlokas.forEach((shloka) => {
  console.log(shloka.getSummary());
});

4. Fetch a Specific Shloka

Fetch a specific shloka using chapter number and verse number:

const shloka = gita.getShloka(1, 1);

console.log(shloka.getSummary());

/*
Output:
{
  chapter: "1",
  verse: "1",
  devanagari: "धृतराष्ट्र उवाच...",
  verseText: "Dhritarashtra said...",
  synonyms: "Dhritarashtra - King Dhritarashtra...",
  translation: "King Dhritarashtra inquired...",
  meaning: ["Literal meaning of the verse...", "Spiritual significance..."]
}
*/

5. Fetch All Shlokas Grouped by Chapters

If you want to get all verses organized by chapters, use getAllVerses():

const allVerses = gita.getAllVerses();

allVerses.forEach((chapter) => {
  console.log(
    `Chapter ${chapter.getShlokas().length} Shlokas available`
  );
});

📚 API Methods Overview

Here’s a quick overview of the available methods:

`GitaLibrary` Methods:

Method	Description
`getDescription()`	Get metadata about the Gita.
`getChapter(chapter)`	Fetch all shlokas in a specific chapter.
`getShloka(chapter, verse)`	Retrieve a specific shloka by chapter & verse.
`getAllVerses()`	Fetch all shlokas grouped by chapters.

`GitaShloka` Methods:

Method	Description
`getSummary()`	Retrieve a summary of the shloka details.
`getDevanagari()`	Get the Devanagari text of the verse.
`getTranslation()`	Get the verse translation.
`getMeaning()`	Get multiple meanings of the verse.

🛠 Use Cases

Here are a few ideas for integrating GitaVerse into your projects:

Spiritual Apps: Build apps to display Gita shlokas with translations and explanations.
Study Tools: Develop tools for students to explore and understand the Bhagavad Gita.
APIs: Serve Gita data through REST APIs for web or mobile apps.
Personal Projects: Use it for personal study and exploration of the Gita.

🌐 Links

NPM Package: gitaverse on npm
GitHub Repository: GitaVerse on GitHub

🤝 Contributing

We welcome contributions! If you'd like to add features or fix issues:

Fork the repository from GitHub.
Create a feature branch.
Submit a pull request.

For any suggestions or bugs, feel free to raise an issue.

📄 License

This project is licensed under the MIT License. See the LICENSE file for more details.

✨ Final Thoughts

With GitaVerse, exploring the timeless wisdom of the Bhagavad Gita becomes simple and developer-friendly. Whether you're building spiritual apps, study tools, or personal projects, GitaVerse provides everything you need to programmatically access and share the Gita's teachings.

"You have the right to work, but never to the fruit of work."

— Bhagavad Gita (Chapter 2, Verse 47)

Start Exploring the Gita Today with GitaVerse! 🌟

Install Now

DEV Community: Ravi Kishan

RustDNS: Writing a Recursive DNS Resolver in Rust, Byte by Byte

Table of Contents

Why I built this

DNS in two minutes

Hello, resolver

The map of the code

A 512-byte cursor

Twelve bytes of header

A real packet, byte by byte

Names, labels and compression pointers

One enum per record type

Writing: backpatching the length

Walking the tree: recursive resolution

Serving dig on port 2053

Breaking it on purpose

Bug 1: the MX query that never came back

Bug 2: an NXDOMAIN that lies about itself

Smaller things I found reading the code again

The serious one: spoofing

How fast is it?

What I learned

What's next

Try it

Relaxnative: Import C, C++, Rust, Zig and Go Straight into Node.js

Table of Contents

Why I built this

Hello, native

Five languages, one call

What loadNative() actually does

Reading signatures: tree-sitter and friends

The types contract

A cache keyed by everything

Ahead-of-time builds: no compiler in production

Three isolation modes

Annotations: @sync, @async, @cost

Benchmarks: where native wins (and where it loses)

RelaxRegistry and supply-chain trust

Signing, done properly

Developer experience

What I learned

What's next

Try it

Relaxicons: Turn Any Iconify Icon into a Native Component for 8 Frameworks

Table of Contents

The problem: icons are weirdly annoying

The idea: shadcn, but for icons

A 60-second tour

What happens when you run relaxicons add

Parsing the ID

Safe names

The SVG transform pipeline (and the outline-icon trap)

One prop contract, eight frameworks

Caching that respects the network

The small details that make a CLI pleasant

Icons in CI

The docs site

Testing

What I learned

What's next

How RelaxCSS Works: Building a TailwindCSS-Like Utility Engine

Overview and Introduction

Architecture Overview

Theme and Configuration System

Utility Parser and Generator

Plugin System

JIT Compilation and File Scanning

Preflight and CSS Output

Example Output and Live Usage

Conclusion

Ravikisha / RelaxCSS

RelaxCSS

PostCSS Plugin Usage

Building a Container Runtime from Scratch with Go (MyDocker)

Introduction

Namespaces

Control Groups (cgroups)

Project Architecture

Command-Line Interface and Main.go

Container Lifecycle (startContainer, child)

What `loadNative()` actually does

Annotations: `@sync`, `@async`, `@cost`

What happens when you run `relaxicons add`

Container Lifecycle (`startContainer`, `child`)