Creating Frameworks

RayQuiro supports a simple framework publishing model. Any GitHub repository containing .rq source files and a rqframework.json manifest can be installed and imported by any RayQuiro user.

This page explains how to create, structure, and publish your own framework.

---

📁 Repository Structure

A minimal RayQuiro framework repository looks like this:

my-logger/
├── rqframework.json      ← required manifest
├── main.rq               ← main entry point
└── README.md             ← optional but recommended

You can also split functionality across multiple files and import them inside main.rq:

my-logger/
├── rqframework.json
├── main.rq
├── core.rq
└── format.rq

---

📄 The rqframework.json Manifest

The rqframework.json file must be placed in the root of your repository. It describes your framework's metadata.

Full Example

{
  "name": "logger",
  "version": "1.0.0",
  "description": "A simple structured logger for RayQuiro.",
  "author": "yourname",
  "entry": "main.rq"
}

Fields

Field	Required	Description
name	✅	The import name users will use (e.g. import logger;)
version	✅	Semantic version string (e.g. "1.0.0")
description	✅	Short description of the framework
author	✅	Author name or GitHub username
entry	✅	The root .rq file rqio should load when importing this framework

Note: The entry field must point to a file that exists at the top level of the repository. Subdirectory paths like "src/main.rq" are not supported.

---

✍️ Writing the Entry File

The entry file (main.rq by default) should define the public API of your framework using top-level functions and variables:

// main.rq — public API of the logger framework

fn info(message) {
    print("[INFO]", message);
}

fn warn(message) {
    print("[WARN]", message);
}

fn error(message) {
    print("[ERROR]", message);
}

Users will then call functions through the import alias:

import logger;

logger.info("Server started on port 8080");
logger.warn("Rate limit approaching");
logger.error("Connection failed");

Or with a custom alias:

import logger as log;

log.info("Ready");

---

🚀 Publishing Your Framework

Install (for users)

Once your repository is on GitHub, users can install it immediately:

# Install globally (available to all projects)
rqio framework install yourusername/my-logger

# Install a specific branch
rqio framework install yourusername/my-logger@dev

# Install project-local only
rqio framework install yourusername/my-logger --local

Approved Registry

To get your framework listed in the official rqio install registry (so users can just run rqio install logger), submit your framework to the RayQuiro Assets registry.

The registry format (frameworks.json) looks like:

{
  "frameworks": [
    {
      "name": "logger",
      "repo": "yourusername/my-logger",
      "branch": "main",
      "description": "A simple structured logger for RayQuiro."
    }
  ]
}

---

💡 Best Practices

• Keep the framework focused on a single concern.
• All public functions should be defined at the top level of the entry file.
• Include a README.md with a usage example.
• Use semantic versioning in rqframework.json.
• Test that your framework installs cleanly via rqio framework install yourusername/repo before publishing.