⚡ Zyra Framework

The Ultimate Fullstack Web Framework Unifying Native Go Performance & Dual-Frontend Architecture

📑 Table of Contents

1. Overview & PRD
2. System Architecture & Data Flow
3. Core Features
4. Premium UI Components
5. Framework Comparison
6. Quick Start
7. Go Action RPC Bridge
8. Database Integrations
9. Single-Binary Production Deployment
10. CLI Commands Reference

1. Overview & PRD

Zyra is a next-generation fullstack web framework engineered to bridge Go 1.22+ backend execution with your choice of React 18 & TypeScript client DX or HTMX & Pure Go templates into a unified, single-binary application.

• For React Users: Write native Go functions annotated with // +zyraaction. Zyra automatically parses the Go AST and generates type-safe TypeScript client bindings.
• For HTMX Users: Zyra provides a blazing fast native Go template rendering engine coupled with Alpine.js for lightweight client interactivity, bypassing Node.js/Bun entirely.

2. System Architecture & Data Flow

graph TD
    Client([Browser Client])
    
    subgraph Zyra Engine [Zyra Unified Engine]
        direction TB
        GoRouter[Go HTTP Router<br/>Security Headers & Rate Limiting]
        Cache[In-Memory SSR Cache]
        
        subgraph Renderers [Frontend Renderers]
            HTMX[HTMX Engine<br/>Go Template Parser]
            React[React Engine<br/>Bun Worker Pool via JSON IPC]
        end
        
        GoActions[Go Actions RPC Bridge<br/>AST-Scanned Endpoints]
        Stream[Realtime Streams<br/>SSE Engine // +zyrastream]
    end
    
    DB[(Database<br/>Postgres, MySQL, Firebase, etc.)]
    
    Client -- HTTP Request --> GoRouter
    GoRouter --> Cache
    Cache -- Cache Miss --> HTMX
    Cache -- Cache Miss --> React
    HTMX -. HTML Output .-> Client
    React -. SSR HTML Output .-> Client
    
    Client -- Type-Safe JSON-RPC --> GoActions
    Client -- Server-Sent Events --> Stream
    GoActions --> DB
    Stream --> DB

3. Core Features

• ⚡ Dual Frontend Architecture — Choose between React 18 (with Bun SSR) or HTMX (Pure Go templates) during zyra create.
• ⚡ Go Action RPC Bridge (React Mode) — Annotate Go functions with // +zyraaction for instant, type-safe TypeScript client RPC calls.
• 📡 Realtime Streams — Annotate with // +zyrastream to instantly generate Server-Sent Event (SSE) streaming endpoints.
• 🚀 Sub-Millisecond SSR Engine — Bun worker thread pool handles React renderToString via JSON IPC, or use native Go templates for HTMX.
• 🎣 Zyra React Hooks — Auto-generated useZyraAction, useZyraMutation (Optimistic Updates), and useZyraQuery (Polling).
• 🛠️ Built-in DevTools Panel — Monitor Action latency, cache hits, and SSR render times directly in your browser.
• 🛡️ Bank-Grade Security Hardening — Pre-configured security headers (X-Frame-Options, X-Content-Type-Options) & token bucket IP rate limiting.
• 🗄️ 6 Database Integrations — PostgreSQL, MySQL, SQLite, MongoDB, Firebase/Firestore, and Supabase.
• 📦 Single-Binary Deployment — Packaged into one standalone executable via //go:embed. Zero Node.js runtime required in production.

4. Premium UI Components

Zyra ships with 26 beautifully designed, zero-dependency premium UI components inspired by shadcn/ui.

Using the CLI, you can inject these directly into your project. Zyra is smart enough to detect your project's architecture (react or htmx) via zyra.config.json and will output either a .tsx file or a .tmpl file (powered by Alpine.js).

# Add a command palette
zyra add ui command-palette

# Add a modal
zyra add ui modal

# Add a data table
zyra add ui data-table

Available Components: button, input, textarea, select, switch, checkbox, radio-group, slider, badge, alert, toast, skeleton, tooltip, progress, spinner, avatar, data-table, tabs, accordion, breadcrumbs, card, modal, drawer, popover, dropdown-menu, command-palette.

5. Framework Comparison

6. Quick Start

Installation

# Linux & macOS
curl -fsSL https://raw.githubusercontent.com/LythianOlyx/Zyra/main/install.sh | bash

# Windows (PowerShell)
irm https://raw.githubusercontent.com/LythianOlyx/Zyra/main/install.ps1 | iex

Create Project

zyra create my-app

Start Dev Server

cd my-app
zyra dev

Your app will be live at http://localhost:3000 with hot reload enabled.

7. Go Action RPC Bridge

Go Server Action (actions/user.go)

package actions

import "context"

type UserProfile struct {
	ID       string `json:"id"`
	Username string `json:"username"`
	IsAdmin  bool   `json:"isAdmin"`
}

// +zyraaction
func GetUserProfile(ctx context.Context, userID string) (*UserProfile, error) {
	return &UserProfile{
		ID:       userID,
		Username: "alex_dev",
		IsAdmin:  true,
	}, nil
}

React Client Component (pages/profile.tsx)

import React, { useState, useEffect } from "react";
import { hydrate, useZyraQuery } from "../runtime/client";
import { GetUserProfile } from "../.generated/actions/actions";

export default function ProfilePage() {
  // Zyra's built-in query hook handles loading states and SSR fetching automatically!
  const { data: user, loading } = useZyraQuery(GetUserProfile, ["usr_100"]);

  if (loading) return <div>Loading...</div>;

  return (
    <main className="min-h-screen bg-slate-950 text-white p-8">
      <h1 className="text-2xl font-bold">Welcome, {user?.username}</h1>
    </main>
  );
}

if (typeof window !== "undefined") {
  hydrate(ProfilePage);
}

8. Database Integrations

Zyra provides instant database configurations during zyra create:

• PostgreSQL — GORM / sqlx / lib/pq
• MySQL / MariaDB — GORM / sqlx / go-sql-driver
• SQLite — GORM / sqlx / go-sqlite3
• 🍃 MongoDB — go.mongodb.org/mongo-driver
• 🔥 Firebase / Cloud Firestore — firebase.google.com/go/v4
• ⚡ Supabase — PostgreSQL Cloud

9. Single-Binary Production Deployment

Compile frontend assets, SSR bundles, and Go server into one binary:

zyra build

The output standalone binary is created at dist/zyra-server. Run it directly without Node.js:

PORT=8080 ./dist/zyra-server

10. CLI Commands Reference

Built with ⚡ by LythianOlyx & Zyra Contributors