A structural web framework for Node.js.

Baxxon leverages standard Node.js APIs and ES Modules to provide a transparent foundation for web applications. By eliminating hidden logic and complex abstractions, Baxxon ensures your code remains portable, predictable, and fast.

The Baxxon Philosophy: The Visual Contract

Baxxon eliminates routing ambiguity by splitting the web into two mutually exclusive categories based on the URL structure. This "Visual Contract" ensures that developers and browsers alike know exactly how a request will be handled:

• Physical Assets (Static): Any URL containing a file extension (a dot, e.g., /style.css) is strictly served from the public/ directory.
• Dynamic Logic (JS Modules): Any URL without a dot (e.g., /api/user) is treated as a logic request and routed to the modules/ directory. These are standard ES modules exporting a default handler function.

Core Features

Routing simplified

Baxxon implements a deterministic router that removes the need for centralized routing tables. By following the Visual Contract, your directory structure is your routing map.

URL as data structure

The integrated Slash-Param Engine treats the URL as a data structure. Any trailing segments following a module path are automatically parsed into the bx.params array and the standard bx.reqURL.searchParams object for instant use.

Markdown by default

Build content-rich sites with zero extra setup. Baxxon natively detects, parses, and renders Markdown files via the integrated marked engine.

Multiple sites, one install

Scale your infrastructure using Baxxon's built-in Virtual Hosting engine. Manage multiple independent domains and sites from a single installation by mapping hostnames to subdirectories in your sites/ folder.

Consistent API logic

Pages and APIs share a unified paradigm. In Baxxon, an API is simply a JS module that returns JSON. The framework handles the boilerplate, including automatic body parsing for JSON and URL-encoded form data.

Files as database

Baxxon uses TextDB, a filesystem-native database where folders act as tables and .txt files act as records. Data is stored in a human-readable Header:Value format, making your database searchable via standard system tools and perfectly suited for version control.

Example Library

Baxxon includes a collection of standalone example sites that serve as both tutorials and production-ready templates. You can load these into your sites/_default directory using the Baxxon CLI.

1. Static Content (example-1-static)

• Focus: Zero-config baseline and the Visual Contract for physical assets.
• Architecture: 100% Static. Served directly from the public/ folder.
• Demonstration: Shows how Baxxon uses the presence of a "dot" in the URL to bypass the logic engine and serve high-performance static assets with automatic MIME type handling and deterministic error responses (404/415).

2. Dynamic Content (example-2-dynamic)

• Focus: Server-side logic, URL parsing, and the native Template Engine.
• Architecture: JS Module driven (modules/index.js).
• Demonstration: Showcases the Slash-Param Engine (converting trailing URL segments into data), the variety of native Render Methods (HTML, Markdown, JSON, etc.), and the performance of the {placeholder} based template system.

3. Dynamic API (example-3-api)

• Focus: Client-server interaction and Network Resiliency.
• Architecture: Hybrid (JS Module Page + Dedicated API Responder).
• Demonstration: Demonstrates how pages and APIs share the same directory structure and logic. It highlights the refactored Resilient API utility, featuring built-in exponential backoff, robust error handling, and connectivity tracking.

4. SPA Architecture (example-4-spa)

• Focus: Advanced Single Page Application (SPA) architecture and TextDB transparency.
• Architecture: Complex JS Module system coordinating a client-side Controller (spa.js) with server-side API responders.
• Demonstration: Features deterministic Dual-Mode Operation (Local/Network) backed by persistent localStorage, the integrated TextDB Engine, and a unified background service monitor for automatic data synchronization and backups.

Shared Tools

• bx.log: A unified logger for note, warn, and error terminal feedback.
• bx.templates: A recursive engine for merging data into reusable HTML structures.
• bx.renderContent(file, vars): Injects fragments into layouts with optional variable replacement.

Installation

This is a Node.js module available through the npm registry.

Before installing, download and install Node.js.

mkdir {my-baxxon-project}
cd {my-baxxon-project}
npm install baxxon

Quick Start

To start a new Baxxon project, you must explicitly run the initialization command after installing the package. This will configure your project and scaffold the default site structure.

npx baxxon init

Baxxon will set up the following structure for you:

{my-baxxon-project}/
|
|---package.json
|---node_modules/
|
|---sites/
    |---_default/
        |---modules/
        |---public/
            |---css/

Manual Setup & Examples

You can use the Baxxon CLI to manage virtual hosts and load architectural examples. All CLI activity is logged to cli.log in your project root for easy auditing and troubleshooting.

Add Virtual Host

Scaffolds a new directory and registers the domain in your configuration. The CLI prevents overwriting existing domain mappings.

npx baxxon add <domain> [dir]

Load Example

Loads a template into a specified directory (defaults to _default). The target directory must already exist and be mapped in your vhosts configuration.

npx baxxon load <type> [dest]
npm run baxxon

Available Example Types:

• static: Zero-config baseline for physical assets.
• dynamic: Server-side logic and Slash-Param parsing.
• api: Client-server interaction with Network Resiliency.
• spa: Advanced SPA architecture with TextDB persistence.

Configuration

Baxxon uses "Convention over Configuration". Default values can be overridden in your project's package.json file under the "baxxon" key:

{
  "name": "my-app",
  "baxxon": {
    "server": {
      "portHttp": 8080
    },
    "vhosts": {
      "domainDirs": {
        "example.com": "example-site"
      }
    }
  }
}

Docs

* [Website](https://baxxon.ca/)
* [GitHub](https://github.com/lornetaylor/baxxon)

Security Issues

If you discover a security vulnerability in Baxxon, please report it via the GitHub repository.

Author

The original author of Baxxon is Lorne Taylor

License

MIT