XYONL Framework

XYONL is a lightning-fast, lightweight full-stack meta-framework designed for developers who want the power of modern component-based architectures (like Next.js or Vue) combined with ultra-fast static compilation and seamless Single Page Application (SPA) client-side routing.

It parses .xyonl markup templates containing HTML, scoped CSS, and build-time sandboxed JS scripts, generating optimized .html pages and JSON transition fragments (.frag) for instant navigation.

Key Features

• Component-Based Architecture: Create reusable .xyonl components with full <slot /> content injection and dynamic props.
• Build-Time JS Sandbox: Execute page-level Javascript code safely at build time inside isolated Node.js vm contexts. Load APIs, build databases, or preprocess states during compilation.
• Client Reactivity Agent: Injects a lightweight 100-line Proxy-based state engine for instant two-way DOM data binding (xy-model and {{variable}}) with zero runtime frameworks.
• Instant SPA Navigation: Hovering over links pre-fetches page transition fragment JSON payloads (.frag). Smooth mix transitions and loading indicators make page transitions instantaneous.
• Asset Compression Pipeline: Copies assets recursively from assets/ to dist/assets/, converting images to optimized .webp format automatically using sharp.
• SSE Live Reload Server: Includes an built-in Server-Sent Events development server and watcher that recompiles code and reloads browsers automatically on file changes.

Quick Start & Syntax Examples

Every template in an XYONL project uses the .xyonl extension and wraps its markup, styles, and logic inside a root <app> tag.

1. Basic Page with Reactivity (index.xyonl)

<app title="Home Dashboard" description="My reactive SSG application homepage">
    <script>
        // Page-level build-time script and initial reactive state
        welcomeMessage = "Welcome to XYONL!";
        counter = 0;
        
        // This output variable replaces the script tag at compile-time
        output = `<p class="timestamp">Compiled on: ${new Date().toLocaleDateString()}</p>`;
    </script>

    <div class="page-content">
        <h1>{{ welcomeMessage }}</h1>
        <script>output;</script>

        <p>Current Count: <span data-xy-bind="counter">0</span></p>
        
        <!-- Two-way data binding input -->
        <input type="text" xy-model="welcomeMessage" placeholder="Type to update heading..." />
        
        <a href="about.html">Go to About Page</a>
    </div>

    <style>
        body {
            font-family: system-ui, sans-serif;
            background: #0f172a;
            color: #f8fafc;
            padding: 40px;
        }
        .timestamp {
            color: #64748b;
            font-size: 0.85rem;
        }
    </style>
</app>

2. Global Layout Template (layout.xyonl)

Save a layout.xyonl file in your root folder to wrap all pages automatically with a persistent layout and styling shell:

<app component title="{{title}}">
    <header class="header">
        <nav>
            <a href="index.html">Home</a> | 
            <a href="about.html">About</a> |
            <a href="contact.html">Contact</a>
        </nav>
    </header>

    <main class="page-content">
        <!-- Inner page content is injected here -->
        <slot />
    </main>

    <footer>
        <p>&copy; 2026 XYONL Framework</p>
    </footer>
</app>

3. Reusable Components (card.xyonl)

Create reusable components by adding the component attribute to the root <app> tag:

<app component>
    <div class="card">
        <h3>{{ title }}</h3>
        <div class="card-body">
            <slot />
        </div>
    </div>
    <style>
        .card { 
            border: 1px solid #334155; 
            padding: 20px; 
            border-radius: 8px; 
            background: #1e293b;
        }
    </style>
</app>

Importing components in pages:

<app title="Dashboard">
    <div class="page-content">
        <!-- Pass static attributes as props -->
        <import src="card.xyonl" title="User Profile">
            <p>This content is injected into the component slot!</p>
        </import>
    </div>
</app>

Running the Compiler

You can compile your XYONL project either by invoking the local entry point script or by using the global NPX command which always runs the latest published version.

• Local run (directly from the cloned repository):

  node main.js

• Recommended NPX run (no need to install or update the package manually):

  npx xyonl@latest

  This ensures you are always using the most recent version of the compiler.

Build & Development Commands

XYONL is easy to configure and run via Node.js CLI commands. While you can run it locally using the repository entry point (node main.js), it is highly recommended to run the compiler using npx to ensure you are always using the latest global version:

Recommended: Using NPX (Global Run)

To run validation checks and compile all pages into the static dist/ directory:

npx xyonl@latest

To compile, start the recursive file watcher, and host a live-reload development server at http://localhost:3000:

npx xyonl@latest --run

Alternative: Repository Local Run

If you have cloned this repository and want to run the compiler scripts directly:

1. Install dependencies first:

   npm install

2. Compile production build:

   node main.js

3. Start development watcher and live-reload server:

   node main.js --run

Developer Documentation

For detailed guides, architecture blueprints, detailed API definitions, and advanced tutorial demos, see the full developer reference manual:

• XYONL Technical Reference Manual (documentation.md)