README.md

This is the official repository for the WebX web server project. A framework for building minimal but powerful web app backends, REST APIs, and hypermedia systems using a HTML first approach.
▸ Get started or read more about the project below.

⚠️ WebX is still in early development and not ready for production use.

Features & Roadmap

Below is a high-level overview of the existing (implemented) and planned features of the WebX technology (in no particular order).

• Blazingly fast¹ 🔥
• Lightweight and minimalistic 🪶
• Versatile, flexible, and powerful 🤸
• Easy to use and learn 🧠

Batteries included 🔋

• Hot reloading 🔥
• Protected and secure by default 🔒
  • DDOS 🛡️
  • CORS 🛡️
  • CSRF 🛡️
  • XSS 🛡️
  • SQL injection 🛡️
  • Rate limiting ⏱️
  • TLS/SSL/HTTPS 🔒
• Built-in modules and services 📦
  • Static file serving 📁
  • Database driver integration 🗃️
    • PostgreSQL
    • MySQL
    • SQLite
    • MariaDB
    • MongoDB
    • Redis
  • Authentication 🔑
  • Authorization 🔑
  • Caching 🗄️
  • Sessions 🍪
  • WebSockets 🌐
• VSC extension (Syntax Highlighting, Snippets, and more)
• WebX Playground 🛝
• WebX Docs 📖
• Package manager 📦 (NPM-like, for WebX handlers, modules, and drivers)

WebX DSL (Domain Specific Language)

• Parser
  • AST for WebX modules
• Comments
• Model definitions (ORM, Prism-like)
  • Fields
  • Types
  • Value Constraints
  • Serde Validation
  • Relations
  • Migrations
  • Queries (CRUD operations)
• Native SSR (templating)
  • JSX support
  • HyperScript support
• TypeScript support
  • Deno runtime
  • WebAssembly AoT compilation
  • Unified type definitions (shared between client and server)
• Validation (Serialize/Deserialize for req/res data)
  • Input sanitization (safe defaults)
  • Output sanitization (safe defaults)
  • Type checking
  • Constraints
  • Relations
  • Formats
    • JSON
    • JSON5
    • XML
    • HTML
    • CSV
    • YAML
    • TOML
    • Custom (plugins)
• Route definitions
  • HTTP methods
  • Path parameters (URL/segments/)
  • Query parameters (?key=value)
  • Request headers
  • Request Body parameters (POST/PUT/PATCH)
  • Body serialization (JSON, XML, etc.)
  • Body deserialization and validation
  • Dependency injection (between handlers)
  • Middleware (before/after handlers)
  • Endpoint body code block types
    • TypeScript (TS)
    • Typescript-React (TSX)

get /todos/(id: number) -> initServices:s, auth(s.userService, id):user, isAdmin(user) { ... }

• Handlers (middleware)
  • Design choices
    • Async vs sync
    • Return types (explicit)
    • Error handling (opinionated!)
    • Dependency injection
    • Return result destructuring
• Built-in handlers 📦 (stdlib)
  • Data manipulation
  • Business logic
  • Authentication
    • OAuth
    • OpenID
    • JWT
    • SAML
    • LDAP
    • Kerberos
    • Basic
    • Digest
    • Bearer
    • API keys
    • HMAC
    • Mutual TLS
  • Authorization
    • RBAC
    • ABAC
    • PBAC
    • LBAC
    • DAC
  • Logging
    • Request logging
    • Error logging
    • Audit logging
    • Security logging
    • Performance logging
    • Debug logging
    • Custom logging (plugins)
  • Caching
    • In-memory
    • Redis
    • Memcached
  • Sessions
  • Database drivers
  • Static file serving
  • Templating 📄
• Error handling 🚨
  • Server errors
  • Client errors
  • Network errors
  • Database errors
  • External service errors
  • Logging

WebX CLI tool

• Project
  • Scaffolding (init new project)
  • Configuration
• Build (AoT compilation)
  • Static files
  • TypeScript to WebAssembly
• Run (JIT compilation)
  • Development mode
    • Hot reloading
    • Logging
    • Error handling
    • Debugging
  • Production mode
    • Optimizations
    • Caching
    • Compression
    • Security
    • Logging
    • Error handling
• Test 🧪
  • Unit tests
  • Integration tests
  • End-to-end tests
• Deploy ☁️
  • Docker
  • Kubernetes
  • Cloud
• Documentation (auto-generated)
• Publish (to package registry)
• Versioning
• Linting
• Formatting

WebX Runtime

• Web server
  • TCP/IP
  • HTTP Request parsing
  • HTTP Response serialization
  • HTTP Request routing
  • HTTP Request handling
  • Protocols
    • HTTP/0.9
    • HTTP/1.0
    • HTTP/1.1
    • HTTP/2
    • HTTP/3
    • HTTP/3 server push
    • TLS/SSL/HTTPS
  • Multiplexing
  • Compression
  • Status codes
  • Cookies
  • Caching
  • Sessions
  • Multi-threading
  • Middleware
  • Logging
  • Error handling
• Web framework
  • REST API
  • GraphQL API
  • Hypermedia API
  • WebSockets API

Getting started

→  Read the Documentation

→  Installation

Download the latest prebuilt binaries from the releases page and extract it to a folder of your choice.

→  Development

Run the web server in dev mode for the current project:

webx run

This enables hot reloading 🔥, extensive logging, safe real-time error reporting, and other useful features.

→  Production

To run the project in production mode:

webx run --prod

This performs compile-time optimizations 🚀 (for performance improvements), caching, and other valuable features. It also disables hot reloading and response-logging to reduce sensitive debug information.

Examples

The following is an example of a simple WebX to-do list application.

include "../common.webx"

global {
  const db = new Database("sqlite://db.sqlite");
}

model User {
  id: number;
  name: string[maxLength(50))]
  email: string?;
  isAdmin: boolean;
}

model Todo {
  id: number;
  task: string;
  userId: number;
}

handler initServices() {
  return {
    userService: new UserService(db),
    todoService: new TodoService(db)
  };
}

handler auth(userService: UserService, id: number) {
  const user = userService.getCurrentUser(id);
  if (!user) error("User not found.");
  return { user };
}

handler isAdmin(user: User) {
  if (!user.isAdmin()) error("User is not an admin.");
}

handler renderTodos(todos: Todo[], user: User): HTML {
  return (<div>
      <h1>Welcome, {user.name}!</h1>
      <ul>
        {todos.map(todo => <li>{todo.task}</li>)}
      </ul>
    </div>);
}

get /todos/(id: number) -> initServices:s, auth(s.userService, id):a, isAdmin(a.user) {
    const todos = s.todoService.getAllTodosForUser(a.user.id);
} -> renderTodos(todos, a.user)

Why Web X?

Our vision is to reduce the boilerplate and complexity of building backends and APIs.
▸ WebX is designed to be simple, minimal, easy to learn, and intuitive while still being versatile and flexible. It can build complex applications quickly while still being lightweight🪶 and blazingly fast🔥.

Backends shouldn't be bloated and complex, but focus on what's most important. Don't reinvent the wheel for every new project,
▸ Jump straight to the goodi-goodi parts and get started using WebX today!

❤️ Perfect match for </> htmx

WebX is designed to be a minimalistic web framework that is easy to learn and use. It is intended to be used with HTMX, a great alternative to frameworks like React, Vue, and Angular (or other stacks). HTMX allows you to build dynamic web applications without learning a new language or framework for the front end. WebX is designed to be versatile and flexible, and it is easy to quickly build backends for complex applications.
▸ Read more about HTMX

What about ///_hyperscript?

HyperScript is a front-end JavaScript DSL for creating and manipulating HTML DOM elements. It is lightweight, tightly coupled with your HTML code, and is easy to learn.
While JSX is the default JS+HTML DSL in Webx, HyperScript is supported natively by WebX and can also be configured to be used in the project settings.
▸ Read more about HyperScript

Contributing

Contributions are welcome! If you have any suggestions or find any bugs, please create an issue or a pull request.

Do you have any suggestions for additional features? Create an issue or a pull request! Read more about contributing below.

Footnotes

1. BLAZING FAST @ThePrimeagen ↩