DEV Community: Víctor García

Agent Orchestration in OpenCode

Víctor García — Wed, 08 Apr 2026 09:06:59 +0000

Most AI tooling talks about "agents" as if they are magic. In practice, the interesting part is not the agent. It is the orchestration layer: who gets to do what, when work is delegated, how permissions are enforced, and how results come back.

That is where OpenCode gets interesting.

OpenCode does not treat agents as loose prompts glued onto a model. It treats them as a runtime system. Native agents are defined in code. File-based agents are loaded from Markdown. Both are merged into the same registry, then executed through the same prompt, permission, and session pipeline.

At the center of that system is the task tool.

When one agent delegates work, it does not simply "call another prompt." It creates or resumes a child session, selects a subagent, passes a scoped instruction, and receives a result back in a structured form. That makes delegation session-based, resumable, and inspectable.

That matters because orchestration is more than routing. It is control.

Here is the OpenCode model:

Agents live in a shared runtime registry.
Permissions decide which tools and delegation targets are actually available.
Prompts shape behavior, but permissions enforce capability.
Delegation happens through child sessions, not inline prompt chaining.
The parent agent stays in control while subagents do isolated work.

One of the clearest examples is our Agent Orchestrator, which is intentionally restricted: it is a primary agent denied direct execution tools like edit, bash, read, glob, and grep. It is allowed to use task, skills, and todo management—in other words, it is designed to think in terms of routing and coordination, not direct execution.

That design forces the right behavior.

The orchestrator does not research on its own. It does not implement on its own. It does not document on its own. It classifies the request, decides whether work should be split, chooses the right specialist, and delegates.

So who are "we" when we use it?

We are not a single monolithic agent. We are a coordinated system of specialists.

The orchestrator hands work to the right subagent for the job:

exploration agents for codebase discovery and tracing
librarian agents for reference gathering and documentation lookup
oracle-style agents for higher-order reasoning and tradeoff analysis
writer agents for final drafting, rewriting, and polish
general agents for broader multi-step execution

That is the real value of orchestration. It turns "an AI assistant" into an operating model.

OpenCode also gets an important architectural detail right: permissions are the control plane. The runtime filters tools before the model even sees them, then checks permissions again at execution time. That means orchestration is not based on trust alone. It is bounded by policy.

The result is a cleaner division of labor:

orchestrator routes
explore and librarian research
build, general, dev, and fixer implement
writer writes

And because delegated work runs in child sessions, context does not sprawl uncontrollably across every step. The parent can coordinate the workflow without inheriting all the noise of every subtask.

That is why agent orchestration in OpenCode feels less like prompt engineering and more like systems design.

It is not about creating one super-agent. It is about building a disciplined network of agents with clear roles, bounded permissions, and explicit delegation paths.

That is how we use the Agent Orchestrator: as the control layer that decides which specialist should do the work, how tasks should be split, when subtasks should run in parallel, and how results should be recombined into something useful for the user.

That model is more durable than the "one agent does everything" pattern. It is easier to reason about, easier to extend, and safer to operate.

And as agentic systems mature, I think that distinction will matter more and more.

If the first wave of AI products was about generating outputs, the next wave will be about coordinating capabilities.

OpenCode shows what that can look like in practice.

References:

Server-First Web Component Architecture: SXO + Reactive Component

Víctor García — Tue, 13 Jan 2026 18:21:25 +0000

Web components offer native UI primitives. However, they often introduce complex lifecycles, Shadow DOM issues, and verbose code.

SXO + Reactive Component solves this. It combines server-side rendering with vanilla JSX and a signal-based reactive system. You get declarative authoring, instant page loads, and progressive enhancement without hydration.

Server-First, Reactivity-Second

SXO inverts the traditional model:

Server: Renders semantic HTML wrapped in custom elements (e.g., <product-card>).
Client: A lightweight reactive runtime (~4.8KB) binds state and behavior to the existing DOM.

There is no hydration pass. The HTML is the source of truth.

Core Concepts

Reactive Components use $-prefixed attributes to link HTML to behavior.

$state="key": Initializes state from text content. Updates reflect automatically.
$bind-*="key": Two-way binds attributes (like value or checked) to state.
$on*="method": Binds events to client-side handlers.
define(tag, setup): Defines client logic, state, effects ($effect), and events ($on).

Product Card

Lets create a product card with a quantity selector and a "Favorite" toggle.

1. Server Component (JSX)

Renders accessible HTML on the server. No client-side logic is included here.

// src/components/product-card.jsx
export function ProductCard({ title, price, image }) {
  return (
    <product-card class="card">
      <img src={image} alt={title} />
      <h3>{title}</h3>
      <p>${price}</p>

      <div class="controls">
        <button type="button" $onclick="decrement" aria-label="Decrease">-</button>
        <input type="number" $bind-value="qty" value="1" min="1" aria-label="Qty" />
        <button type="button" $onclick="increment" aria-label="Increase">+</button>
      </div>

      <button
        type="button"
        $onclick="toggleFavorite"
        $bind-attr="favoriteAttrs"
        aria-pressed="false"
        class="btn-icon"
      >
        ♥
      </button>
    </product-card>
  );
}

2. Client Enhancer

Attaches behavior to the server-rendered markup.

// src/components/product-card.client.js
import { define } from "@qery/reactive-component";

define("product-card", ({ $state, $on, $compute }) => {
  // 1. Initialize State
  $state.qty = 1;
  $state.isFavorite = false;

  // 2. Compute aria-pressed attribute declaratively
  //    and falsy values remove them
  $compute("favoriteAttrs", ["isFavorite"], (isFavorite) => ({
    "aria-pressed": isFavorite ? "true" : "false",
  }));

  // 3. Define Actions
  $on.increment = () => $state.qty++;
  $on.decrement = () => {
    if ($state.qty > 1) $state.qty--;
  };

  $on.toggleFavorite = () => {
    $state.isFavorite = !$state.isFavorite;
  };
});

3. Page Composition

Compose the component in a server route.

// src/pages/products/index.jsx
import { ProductCard } from "../../components/product-card.jsx";

export default function ShopPage({ products }) {
  return `
    <!DOCTYPE html>
    <html lang="en">
      <head>
        <title>Shop</title>
        <link rel="stylesheet" href="/styles.css">
      </head>
      <body>
        <main>
          ${products.map(p => ProductCard(p)).join('')}
        </main>
      </body>
    </html>
  `;
}

Key Advantages

Instant Interaction: The UI is visible immediately. No loading spinners or layout shifts.
Simple State: Signal-based state management without complex providers.
Zero-Config: Automatic bundling of per-route client entries.

Resources

SXO: Optimized Server-Side JSX. Build Simple. Build Fast

Víctor García — Sat, 23 Aug 2025 17:09:27 +0000

If you're looking to build high-performance websites without the complexity of client-side frameworks, SXO is a server-side JSX framework designed for speed and simplicity. It skips React's overhead, offering a lean alternative for server-rendered content.

SXO delivers:

Composable JSX optimized for server rendering.
Intuitive, explicit directory-based routing.
Blazing-fast builds powered by esbuild and a Rust/WASM JSX precompiler.
A unified CLI for development, building, and serving.
Predictable output with separate client/server bundles and a route manifest.

GitHub: gc-victor/sxo

Key Features & Architecture

SXO combines a powerful toolchain with a simple structure:

Routing: Define routes with folders. Each index.(jsx|tsx) file in src/pages becomes a route, supporting dynamic segments like [slug].
Pages: Each page exports a JSX render function and optional head metadata for titles, scripts, and styles.
Performance: A Rust-powered JSX precompiler and esbuild ensure top-tier build speed.
Reactivity: Add partial interactivity with reactive islands ([reactive-component]) without a full client framework.
DX: The dev server uses SSE for precise hot-replacement, updating only changed fragments without a full refresh.

Project Structure:

your-app/
├── src/
│   ├── components/     # Optional - @components alias
│   ├── utils/          # Optional - @utils alias
│   ├── middleware.js   # For custom request handling
│   └── pages/
│       ├── index.html  # HTML shell
│       ├── global.css  # Global styles
│       ├── index.jsx   # Route: /
│       └── about/
│           └── index.jsx # Route: /about
└── package.json

Build Output:

dist/client/: Hashed static assets (CSS, JS).
dist/server/: Server bundles and a routes.json manifest.

Get Started in Seconds

Begin without installation using npx or pnpm dlx:

npx sxo dev

Example Page (src/pages/index.jsx):

import { Page } from "@components/Page";

export const head = { title: "Home" }; // Injected metadata

export default () => (
  <Page>
    <h1>Welcome to SXO</h1>
  </Page>
);

Core Commands:

sxo dev – Start dev server with hot-reload.
sxo build – Create production builds.
sxo start – Serve the production build.
sxo clean – Remove build artifacts.

Advanced Configuration

Middleware: Add src/middleware.js to handle logic like authentication, logging, or headers. Export a single function or an array. Changes are reloaded in development.

Custom Paths/Ports: Override defaults via CLI flags:

sxo start --pages-dir ./src/pages --port 4011

Why Choose SXO?

SXO is a powerful, minimal foundation for server-rendered sites like blogs, documentation, or landing pages. It offers:

Unmatched Build Speed from esbuild and Rust.
A Clean Developer Experience with simple conventions and APIs.
Granular Updates for rapid iteration in development.
Zero Framework Lock-in, allowing you to add reactivity only where needed.

It’s the ideal tool for developers who want the familiar component model of JSX without the overhead and complexity of a full client-side framework.

Documentation That Developers Actually Want to Write

Víctor García — Sun, 09 Mar 2025 14:45:40 +0000

Documentation is an essential part of software development in the open-source world. We all know it's crucial, yet somehow, it always ends up as a collection of outdated markdown files and half-finished README.md lurking in our repositories. That's exactly why Query Docs exists—not to reinvent documentation but to make it actually work for both contributors and developers.

I created Query Docs because I was drowning in half-baked documentation solutions that felt like trying to solve a Rubik's Cube blindfolded. The frustration was real: great software deserves great documentation, but the tools to create it often felt like they were working against us.

What do Query Docs do? It takes your existing markdown files—the ones you're already writing—and transforms them into a complete documentation site. The kind that doesn't make your users want to file a bug report just to navigate it.

And no, this isn't another "60-second setup" tool that secretly requires a PhD in configuration files to use properly.

Here's what you get:

Navigation that doesn't hate your users: A clear page hierarchy with intuitive structure (yes, even for complex products)
Search that works: Type a term and find relevant results—seems basic, but it's surprisingly rare
Workflows that don't fight you: Your content stays in simple markdown—easy to update, version, and collaborate on
Full syntax highlighting: Code blocks that are readable, with proper language detection

Ready to transform your documentation experience? It takes seconds to get started without the usual headaches:

1. Create a new project using the Query CLI:

Use either of these commands—whatever works for you:

# With pnpm
pnpm dlx @qery/query create

# With npm
npx @qery/query create

When prompted, select the docs project type. This sets up everything with sensible defaults.

2. Launch your development server:

Navigate to your new project directory and run:

pnpm dev

3. View your site:

Open your browser and go to http://localhost:3000. Your starter documentation site is ready for your content.

Tada!

Here's where the frustration-free experience really begins. Create a SUMMARY.md file—it's like a table of contents that makes sense to humans:

# Summary

## Intro Stuff  
- [What Even Is This?](index.md) Your elevator pitch  
- [Quick Start](getting-started.md) The "shut up and let me code" section  

## Features  
- [Feature X](features/x.md) The thing your VP overpromised to clients  
- [Feature Y](features/y.md) The thing that actually works

Each link points to a markdown file. Your index.md could be as simple as:

# Welcome to Our App

We made a thing! It (probably) won't crash.

## What's This For?

Imagine [insert competitor] but with fewer existential crises during setup.

Query Docs is designed with a simple, logical structure that stays out of your way:

src/  
└── docs/   # Your markdown lives here  
└── api/    # Search endpoints  
└── pages/  # Where the server turns MD into HTML

When you organize your content, it creates a file-based routing system that mirrors your documentation's logical structure. The docs generator produces JSON files containing all the necessary information—content, navigation links, table of contents—ready for your server to render.

Query's JSX Server-Side Rendering lets you build dynamic documentation pages with a component-based architecture—without loading your users' browsers with unnecessary JavaScript. The result? Fast-loading docs that work everywhere, even on that ancient laptop your QA person refuses to upgrade.

Documentation shouldn't look like it was styled by someone who thinks "UX" is a myth. Query Docs uses Tailwind to make your docs match your brand without requiring design expertise.

Let's talk about search—what's the point of documentation if no one can find anything? Query Docs pre-builds a search index, so when users type a keyword from your content, they get relevant results. There's no spinning up Elasticsearch, no extra configuration, or third parties—just functional search that understands your content.

Beyond the basics, Query Docs includes features that solve real documentation problems:

Smart navigation: Automatically generates previous/following links between pages
Hierarchical TOC: Creates structured navigation from your content organization
Customizable templates: Use your own JSX templates for complete control
Metadata support: Add YAML frontmatter for additional page information

Is It Perfect? Of course not—no documentation system is. However, Query Docs focuses on solving the problems that matter to open-source creators and their users. The goal isn't perfection; it's making documentation less painful and more useful.

So, should you give Query Docs a try? If you're tired of documentation being the worst part of your development process, absolutely. At worst, you'll save a few hours of frustration. At best, you might—and I say this with cautious optimism—not hate writing docs anymore.

And that might be the most revolutionary feature of all.

Learn More About Query Docs

Disclaimer: As a dyslexic, I rely on AI tools to help write and organize blog articles. While I review the content, AI helps me articulate my thoughts more clearly.

Reactive Component Hot Reloading with State Preservation

Víctor García — Tue, 11 Feb 2025 14:30:39 +0000

Modern web development demands creating responsive and fluid user experiences. However, traditional approaches often require a full page refresh to apply code changes, which clears user inputs, authentication data, and navigation history—forcing developers to recreate testing conditions after every update. To overcome these challenges, developers have embraced hot reloading, a technique that updates code in real-time while preserving the application's state, resulting in a more efficient development process.

Hot reloading enables developers to see immediate changes in the UI and continue testing without resetting the application. Among the various tools that utilize this capability, Reactive Component is designed to manage its own state and data flow, which makes it well-suited for hot reloading. This component maintains an accurate record of its current state and updates the user interface automatically when changes occur. This built-in capability simplifies tracking and preserving state during code updates. The clear separation of state management within the reactive component ensures that any updates can be applied without disrupting the overall application behavior.

Building on the robust state management of Reactive Components, the hot reload mechanism continuously monitors source files using Server-Sent Events (SSE). When a modification is detected, the current application state is captured and stored. The updated code is then applied by creating new component instances without interrupting user interactions. Finally, the preserved state is reattached to these new components, ensuring that all user inputs and data persist accurately. This method streamlines updates and enables real-time adjustments without the overhead of rebuilding the entire application state.

Despite the hot reload mechanism's efficiency, ensuring optimal performance requires further attention to code efficiency. Developers should optimize code to minimize computational overhead during updates. This includes streamlining DOM operations, applying debouncing techniques, and ensuring efficient serialization and deserialization of state data. If issues occur, reviewing state preservation logs and verifying event handler reattachment and property recalculation can help identify and resolve problems.

With these optimizations in place, hot reloading becomes an indispensable tool for developing complex applications. It allows developers to update styles, animations, or functionality while keeping the current state intact, ensuring that the application displays real-time data and maintains uninterrupted user interactions.

In summary, Reactive Component hot reloading represents an important advancement in the web development process. Developers can test and iterate quickly on new features and design modifications by enabling updates without losing the application state. This method saves time and supports a more reliable and consistent development experience. As development practices evolve, ensuring effective state preservation will remain fundamental to creating robust web applications.

Additional Resources

Explore the Reactive Component repository on GitHub.
The Reactive Component package on NPM.
Dive directly into the code of the Hot Reload system.

Disclaimer

As a dyslexic, I rely heavily on AI to help write and organize my blog articles. While I review and shape the content, AI helps me write down my thoughts.

https://dev.to/gc-victor/ai-a-game-changing-tool-for-people-with-dyslexia-1mfo

AI: A Game-Changing Tool for People with Dyslexia

Víctor García — Wed, 15 Jan 2025 10:37:35 +0000

As someone living with dyslexia, I've always had a complex relationship with writing. While my mind is full of ideas and insights I want to share, transforming those thoughts into coherent written content has been a constant challenge. That's why I want to share how artificial intelligence has become an invaluable tool in my writing process and why it represents a breakthrough for many people with dyslexia who want to express themselves through writing.

I have always hidden my dyslexia, but I have come to realize that it is a part of who I am. This realization became even more profound when I discovered that my daughter has it, too. I now understand that keeping it hidden isn't helping either of us, and I need to be open to supporting her journey. It has shaped my perspective on the world and how I interact with it. I have learned to embrace my dyslexia as a unique lens through which I view the world, and I am grateful for the insights and creativity it has brought into my life.

Living with Dyslexia: More Than Just Spelling Challenges

Before diving into how AI helps, it's important to understand that dyslexia affects more than just spelling. While most people are aware that dyslexia can cause spelling difficulties, fewer understand that it can also affect other critical skills, such as reading comprehension, writing fluency, express themselves clearly, and the ability to organize thoughts on paper. Some of the common challenges we face include:

Word Recall: Often, we know what we want to say, but finding the right word feels like trying to catch smoke with our hands. The word is floating in our minds but just out of reach.
Spelling Inconsistency: The same word might be spelled correctly one minute and incorrectly the next. It's not about memorization but how our brains process and recall spelling patterns.
Organizational Challenges: Our thoughts often come in bursts of creativity, but organizing them into a logical flow can feel overwhelming. It's like having all the puzzle pieces but struggling to see how they fit together.
Working Memory Limitations: While writing, we might forget the beginning of our sentence by the time we reach the end, making it difficult to maintain coherent thoughts throughout longer pieces.
Time Management: Tasks that might take others an hour can take us significantly longer, leading to frustration and sometimes even abandoning writing projects altogether.

The Traditional Writing Process: A Mountain to Climb

For years, my writing process involved multiple steps that were both time-consuming and mentally exhausting:

Writing everything down as quickly as possible before the thoughts escaped
Reviewing and reorganizing the jumbled mess of ideas
Checking and rechecking spelling
Having others proofread my work
Making corrections and starting the process again

This approach wasn't just inefficient – it was demoralizing. Despite having valuable insights to share, the mechanical aspects of writing often overshadowed the actual content I wanted to convey.

Enter AI: A Bridge Between Thoughts and Written Expression

When I started using AI as a writing tool, it felt like finally finding the missing piece of the puzzle. AI doesn't just correct spelling or grammar – it serves as an intelligent partner in the writing process. Here's how it transforms the writing experience for people with dyslexia:

1. Immediate Feedback and Correction

Instead of writing an entire piece and then facing the daunting task of editing, AI provides real-time suggestions. This immediate feedback helps build confidence and maintains the flow of thoughts without getting caught up in mechanical details.

2. Organization and Structure

When I share my ideas with AI, even in their raw, unstructured form, it helps organize them into a coherent narrative. It's like having a writing partner who can help arrange my thoughts while preserving my unique voice and perspective.

3. Word Finding Support

When I struggle to find the right word, I can describe what I'm trying to say, and AI suggests appropriate terms. This feature has saved countless hours of frustrating searching through my mental dictionary.

4. Consistency in Expression

AI helps maintain consistency throughout longer pieces, which can be particularly challenging for people with dyslexia. It remembers the context and can suggest ways to keep ideas connected and flowing naturally.

Breaking Down the Stigma

One of the most critical aspects of using AI for writing is addressing the stigma that sometimes comes with it. Let me be clear: using AI as a writing tool is not cheating or taking shortcuts. It's about:

Creating equal opportunities for everyone
Focusing on the content rather than the mechanics
Using available tools to express ourselves more effectively
Maintaining our authentic voice while overcoming technical challenges

Just as someone who wears glasses isn't "cheating" at seeing, using AI tools isn't cheating at writing. It's about accessing the support we need to express ourselves clearly and effectively.

How I Use AI in My Writing Process

My current writing process with AI looks something like this:

Using System Prompt: I provide the AI with a system prompt for writing and let it generate a draft based on the information provided.
Brain Dump: I share my initial thoughts with the AI without worrying about spelling, organization, or grammar.
Provide References: I share any relevant research or resources with the AI to help it understand the context of my writing.
Review and Refinement: I review the AI's suggestions, accepting what feels right and adjusting what doesn't.
Final Polish: A final review ensures everything flows naturally and accurately represents my thoughts.

The Future of Writing with Dyslexia

Integrating AI into the writing process represents more than just a technological advancement – it's a democratization of written expression. For those of us with dyslexia, it means:

More confidence in professional communication
Increased willingness to share our ideas and perspectives
Reduced anxiety about written expression
More time focusing on content rather than mechanics
Enhanced autonomy when writing and creating content

Maintaining Authenticity

One common concern about using AI for writing is maintaining an authentic voice and original thoughts. As someone who uses AI regularly, I can confidently say that AI is a tool for expression, not a replacement for personal voice. The ideas, perspectives, and insights are still entirely our own – AI helps us present them more effectively.

Conclusion: Embracing the Future of Writing

As we continue to advance technologically, it's crucial to recognize and embrace tools that make life more accessible for everyone. AI-assisted writing isn't about replacing human creativity or thought — it's about breaking down barriers that have historically prevented some of us from effectively sharing our voices with the world.

For those with dyslexia who might be hesitant about using AI tools for writing, I encourage you to try them. They offer the support needed to share your valuable perspectives with the world more confidently and effectively.

Remember: your thoughts and ideas matter, and using AI to help express them more clearly doesn't make them less valuable or authentic. It is just the tool that allows your voice to reach the audience it deserves.

Disclaimer

As someone with dyslexia, I utilize AI tools extensively to assist in writing and structuring my blog posts. Although the ideas and direction are my own, AI technology helps me translate my thoughts into written form.

Building Static HTML Pages with JSX Server-Side Rendering

Víctor García — Mon, 13 Jan 2025 15:56:44 +0000

Introduction

Have you ever visited a website that took forever to load? Frustrating, isn't it? Fast loading times and smooth user experiences aren't just nice-to-haves—they're essential for keeping visitors around and ranking high on search engines. Server-Side Rendering (SSR) with JSX presents an effective solution to these challenges. Unlike client-side rendering, where JavaScript constructs the page within the user's browser, SSR generates the complete HTML on the server before sending it to the client. This approach offers significant benefits for performance, Search Engine Optimization (SEO), and overall simplicity.

In this article, we'll explore developing static sites with JSX, focusing on the rationale, benefits, and best practices for this development strategy. Whether you're a developer looking to improve website performance, enhance SEO, simplify deployment, or explore new approaches to web development, this guide will provide valuable insights.

Why Choose SSR with JSX for Your Static Sites?

Several key advantages make JSX-based SSR an attractive choice for building static websites.

If you've worked with React before, you'll feel right at home with JSX. It uses a component-based architecture that makes it intuitive to adopt, promoting code reusability and maintainability. The result? Cleaner, more organized projects with quicker development cycles.

Imagine visiting a website and seeing the content instantly—no waiting for JavaScript to piece everything together. That's the power of SSR. By sending fully formed HTML to the browser, users experience faster initial page loads, especially those on slower networks or devices. Faster loading means happier users and lower bounce rates.

Search engines love fully rendered HTML. SSR ensures crawlers receive complete page content upfront, making indexing and ranking your site easier. This translates to better search visibility and a competitive edge.

With SSR, there's less reliance on client-side JavaScript for rendering. This results in smaller payloads and better security since there's less code running in the browser.

Choosing the Right Tool

With so many tools claiming to make web development easier, how do you pick the right one? Join Query, a lightweight framework that simplifies JSX-based SSR without adding unnecessary complexity. Query offers an unusual approach by implementing an optimized JSX transform similar to Deno's JSX precompile transform. This transform prioritizes generating static HTML strings whenever possible, minimizing object creation and garbage collection overhead, resulting in significantly faster rendering times.

Why Choose Query?

Forget the headaches of managing separate backend servers and databases. Query combines both into a single, streamlined system. This means you can write efficient SQL queries directly within your server-side functions, avoiding the complexity of ORMs and database clients. It's all about keeping things simple and efficient.

Built on a highly optimized JavaScript runtime powered by QuickJS, Query offers fast startup times and efficient execution. Its built-in caching mechanism further enhances performance by storing function responses, reducing database load and latency. This focus on speed makes Query a standout choice for server-side rendering, especially in applications with many components.

Query's file-based routing, JSX support, and direct database access reduce boilerplate and configuration. This allows you to focus on what really matters—building your application logic. Its intuitive API ensures that developers of all levels can quickly get up to speed.

Testing your code shouldn't be a chore. Inspired by Jest and Bun's test runner, Query's built-in test suite makes testing seamless. With familiar functions like test, describe, and expect, writing and managing tests without extra tools is easy.

Deploying your app globally is so simple with Query's integration with Fly.io. Using LiteFS for distributed SQLite database replication, you can ensure low-latency access for users across different regions. Say goodbye to complex deployment pipelines.

Query handles asset storage and serving, so you don't need external services like Amazon S3. This keeps your workflow simple and your assets closely tied to your application.

Choosing the right tool for your project involves understanding your specific needs. If you're focused on content-heavy projects like blogs, documentation sites, or landing pages, consider your project's complexity, scalability, and the level of control you want over the development process when evaluating options.

Conclusion

Server-side rendering with JSX offers a compelling approach to building high-performance static HTML websites. By leveraging the component model and optimizing for performance and SEO, you can create fast, scalable, and maintainable sites that provide an excellent user experience. This method is particularly well-suited for projects with predominantly static content, such as blogs, documentation sites, and landing pages.

Whether you're building a blog or a documentation site or just curious about new approaches to web development, SSR with JSX offers plenty of benefits. Why not give Query a try and see how it changes your workflow?

For projects seeking a simple, performant, and readily deployable solution that combines server-side rendering with JSX and direct database access, Query emerges as a strong contender. Its optimized JSX transform contributes to enhanced performance, making it an attractive option for those prioritizing speed and efficiency. While other frameworks might boast larger ecosystems and more mature communities, Query's unique approach streamlines development and deployment, presenting a viable alternative for a wide range of projects.

Disclaimer

As a dyslexic, I rely heavily on AI to help write and organize my blog articles. While I review and shape the content, AI helps me write down my thoughts.

References

Building a Minimal Blog with Query

Víctor García — Fri, 11 Oct 2024 16:22:33 +0000

This tutorial will guide you through creating a basic blog application using Query. You'll see how Query simplifies the development process by handling the database, backend, and frontend in one cohesive system.

Step 1: Set up a new Query project

First, create a new Query project:

pnpm dlx @qery/query create

Select the minimal project template and follow the prompts to create a new project. The minimal template provides a simple starting point for building simple web applications with Query.

Step 2: Define the database schema

Query uses SQLite databases for data storage. SQLite is a lightweight, file-based database well-suited for small—to medium-sized applications. It provides a simple and efficient way to store and retrieve data without the need for a separate database server.

In this example, we'll define the schema for our blog application using SQLite. Create a file migrations/blog.sql with the following contents:

CREATE TABLE IF NOT EXISTS post (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    title TEXT NOT NULL,
    content TEXT NOT NULL,
    created_at INTEGER DEFAULT (strftime('%s', 'now'))
);

This SQLite statement creates a table named post with the following columns:

id: An auto-incrementing integer that serves as the primary key for each post.
title: A text column to store the post's title.
content: A text column to store the content of the post.
created_at: An integer column to store the creation timestamp of the post, defaulting to the current Unix timestamp.

You can define your database schema using SQL files and manage its evolution over time by creating additional migration files.

Step 3: Create the views

In this project, we are using a combination of HTML and TypeScript files for server-side rendering. HTML files define the static structure of the page, while TypeScript files handle dynamic content and data fetching.

Create a file src/pages/index.html:

<div>
  <h1>My Blog</h1>

  <a href="/new">Create New Post</a>
</div>

<main>
  <!-- POSTS -->
</main>

Create a file src/pages/get.index.ts:

import { Database } from "query:database";

import html from "./index.html";

interface Post {
    title: string;
    content: string;
    created_at: number;
}

export async function handleRequest(_: Request) {
    const db = new Database("blog.sql");
    const posts: Post[] = db.query("SELECT * FROM post ORDER BY created_at DESC");

    const body = html.replace("<!-- POSTS -->", generatePostsHTML(posts));

    return new Response(body, {
        status: 200,
        headers: {
            "Content-Type": "text/html; charset=utf-8",
        },
    });
}

function generatePostsHTML(posts: Post[]) {
    return posts
        .map((post) => `
            <article>
                <h2>${post.title}</h2>
                <p>${post.content}</p>
                <p>Posted on ${new Date(post.created_at * 1000).toLocaleString()}</p>
            </article>
        `,
        ).join("");
}

In the get.index.ts file, we import the Database class from query:database to interact with the SQLite database. Inside the handleRequest function, we create a new instance of the Database class and use the query method to fetch all posts from the post table, ordering them by the created_at column in descending order.

The generatePostsHTML function takes the fetched posts and generates the corresponding HTML markup for each post. The generated HTML is then used to replace the  placeholder in the HTML template.

Finally, the handleRequest function returns a Response object with the generated HTML as the body and the appropriate headers.

Create files src/pages/new/index.html and src/pages/new/get.index.ts:

<h1>Create New Post</h1>

<form action="/api/post" method="POST">
    <input type="text" name="title" placeholder="Title" required>
    <textarea name="content" placeholder="Content" required></textarea>
    <button type="submit">Create Post</button>
</form>

import html from "./index.html";

export async function handleRequest(_: Request) {
    return new Response(html, {
        status: 200,
        headers: {
            "Content-Type": "text/html; charset=utf-8",
        },
    });
}

The src/pages/new/get.index.ts file is another TypeScript file that handles the rendering of the "Create New Post" page. It simply returns the HTML content imported from index.html as the response.

Step 4: Create API endpoints

In Query, API endpoints are defined using JavaScript or TypeScript files with a specific naming convention. The file name prefix determines the HTTP method (delete, get, patch, post, put), and the folder structure defines the route.

Create a file src/api/post/post.index.ts:

import { Database } from "query:database";

export async function handleRequest(req: Request) {
    const formData = await req.formData();
    const title = formData.get("title") as string;
    const content = formData.get("content") as string;

    const db = new Database("blog.sql");
    db.query("INSERT INTO post (title, content) VALUES (?, ?)", [title, content]);

    const url = new URL(req.url);
    return Response.redirect(`${url.origin}/`, 303);
}

The handleRequest function is Query's entry point for each function route. It receives a Request object as a parameter and returns a Response. The Request object contains information about the incoming HTTP request, such as the URL, headers, and body. You can use this information to process the request and generate an appropriate response.

Inside the handleRequest function, you can access the database using the Database class imported from query:database. To create a new instance of the Database class, you need to provide the name of the database file. We use blog.sql as the database file name in this example.

The Database class provides a query method that allows you to execute SQL queries against the SQLite database. You can use placeholders (?) in your SQL queries to prevent SQL injection attacks. The placeholder values are passed as an array in the second argument of the query method.

Step 5: Run the application

Start the Query development server:

query dev

Visit http://localhost:3000 in your browser to see your blog in action!

Conclusion

This example shows how Query simplifies web development by providing an integrated approach to handling databases, API routes, and server-side rendering.

Query uses SQLite databases, which are lightweight, file-based databases that are easy to set up and use. You can define your database schema using SQL files and control their version with your application code.

The handleRequest function is the entry point for each API route and allows you to process incoming requests and generate appropriate responses. By importing the Database class from query:database, you can easily interact with the SQLite database and execute SQL queries using the query method.

Query's combination of HTML and TypeScript enables you to define the static structure of your pages and handle dynamic content and data fetching. The handleRequest function in TypeScript files can access the database, fetch data, and generate the final HTML response.

With Query, you can focus on building your application's functionality without worrying about setting up and managing separate services for the database, backend, and frontend.

Cache, Store, and Serve All in One: Manage Your Website with SQLite Power

Víctor García — Tue, 16 Apr 2024 13:40:05 +0000

Query is a one-file system that uses SQLite to cover most of the full-stack development and infrastructure needs for small websites.

Query Mental Model

This is a mental model to guide you when working with Query.

I do not need a database server (PostgreSQL or MySQL), as I can connect to my SQLite databases remotely using the Query APIs, the CLI, and the functions.
I do not need a JavaScript runtime (NodeJS, Deno, or Bun), as Query offers its own.
I do not need a JavaScript backend framework (NextJS, Remix or Astro), as Query provides functions to serve Pages and APIs.
I do not need a caching system (Redis) for my function, as Query caches them in SQLite and serves them.
I do not need a storage system (S3) for my assets, as Query stores them in SQLite and serves them.
I do not need a scaffolding tool to generate code, as Query offers its own.
I do not need to develop a back office admin area, thanks to the Query generator, as I can build one just by executing a command.
I can deploy in a couple of seconds to Query.
I can distribute it in multiple regions, thanks to Fly.io and LiteFS.

The following links are related to each mental model concept.

[1] Query API
[1] Shell
[1] Functions

[2] Query JavaScript Runtime
[2] Runtime Compatibility

[3] Functions
[3] File-System Based Router

[4] Query Cache Control

[5] Query Generator

[6] Assets

[7] Query Generator
[7] Query Generator Templates

[8] Query Function CLI
[8] Query Assets CLI

[9] Fly.io
[9] LiteFS

Create Your Side Project With A Single Command

Víctor García — Tue, 05 Mar 2024 11:12:23 +0000

Query offers a powerful code generator that assists developers in creating side projects quickly and efficiently. With Query's predefined templates, developers can automate the creation of APIs, Admin UI, database migrations, and validations, making coding effortless, maximizing efficiency, customization, and simplicity, enabling developers to create quality projects quickly.

Give it a try!

Effortless Function as a Service: A Simple Guide to Implementing it with Query

Víctor García — Thu, 21 Dec 2023 10:59:50 +0000

Query is a Rust server that provides an API, CLI, and authentication for remote interaction with SQLite databases. It has introduced "functions" to enhance your product with hosted JavaScript code accessing remote SQLite databases.

Let's explore a practical example of a Query function:

export async function handleRequest(req) {
    const db = new Database("example.sql");

    const result = await db.query("SELECT * FROM example WHERE id = ?", [1]);

    return new Response(JSON.stringify({ data: result }), {
        status: 200,
        headers: {
            "content-type": "application/json",
        },
    });
}

In this example, the function fetches data from a database table and responds with a JSON object containing the result.

A Query function follows a specific format. It exports an asynchronous function named handleRequest that takes a Request and returns a Response.

A connection to a database is required to interact with databases using the Query function. It can be achieved by utilizing the Database constructor.

const db = new Database("example.sql");

The Database constructor takes the name of the database. Once connected, it provides two essential methods:

query: Reads data from the database.
execute: Writes data to the database.

Both query and execute can accept parameters as an array or an object with placeholders like :AAA, $AAA, or @AAA.

Remember, when working with Query and LiteFS proxy, use GET to read data and DELETE|POST|PUT|PATCH to write data.

Query follows a specific folder structure to organize functions and define routes. Here's an example:

functions
├── get.index.js // GET "/"
├── post.index.js // POST "/"
├── example
    ├── get.index.js // GET "/example"
    ├── get.[slug].js // GET "/example/:slug"
    [slug]
    ├── get.index.js  // GET "/:slug"
...

The prefix determines the method used in a file (delete|get|patch|post|put).*. The remaining part of the file name defines the final segment of the route. For instance, if the file name ends with index, it represents the root of the route.

If you're looking to deploy and replicate your databases across the globe quickly, Fly.io provides a seamless solution to run a Query Server in just a few minutes.

To incorporate Query into your deployment, your Dockerfile needs to include the Query Server. Consider using a multistage Dockerfile, with the final stage being a compatible x86_64-unknown-linux-gnu image, such as debian:<suite>-slim. Refer to the LiteFS documentation for critical information on this essential system component.

Here is a sample Dockerfile for your Query Server:

FROM debian:12-slim

ADD litefs.yml /etc/litefs.yml
COPY --from=flyio/litefs:0.5 /usr/local/bin/litefs /usr/local/bin/litefs

RUN apt-get update -qq && \
    apt-get install -y --no-install-recommends \
    ca-certificates \
    sqlite3 \
    fuse3 \
    curl

# Download and install Query Server
RUN curl --proto '=https' --tlsv1.2 -LsSf https://github.com/gc-victor/query/releases/latest/download/query-server-installer.sh | sh

EXPOSE 3000

CMD ["litefs", "mount"]

Additionally, to kickstart the server, add this command to the litefs.yml configuration file:

...
exec:
  - cmd: "~/.cargo/bin/query-server"
...

With these components in place, your Query Server will be ready to deploy on Fly, providing a robust and globally accessible solution.

Let's install the toolset to deploy the functions.

We have to install the Query CLI. It is a powerful tool that lets you manage your remote SQLite databases with ease and safety.

Form macOS and Linux (not NixOS, Alpine, or Asahi):

curl --proto '=https' --tlsv1.2 -LsSf https://github.com/gc-victor/query/releases/latest/download/query-installer.sh | sh

The functions will bundle using esbuild. For that, it is required to install esbuild globally:

npm install --global esbuild

Finally, to deploy the functions, run:

query function

With their structured approach and database integration, Query functions offer a robust foundation for building scalable and efficient Function as a Service (FaaS).

Simplifying the Management of Remote SQLite Databases

Víctor García — Mon, 27 Nov 2023 09:49:38 +0000

Introduction

With the growing popularity of SQLite usage in websites, particularly with LiteFS, there is an increasing demand to manage remote databases. Query aims to give you straightforward access to your remote databases.

What is Query?

Query is a Rust server that runs alongside your application and enhances its functionality without the application's knowledge. Query provides an API, CLI, and an authentication system that enables remote interaction with your SQLite databases.

The /query entry point of Query is both powerful and simple, utilizing a basic payload consisting of a database name, a query, and parameters to send requests to remote databases.

{
  "db_name": "kv.sql",
  "query": "INSERT INTO kv (key, value) VALUES (?, ?);",
  "params": ["1", 1]
}

It also provides functions (without sandboxing by default) like Edge Functions from Vercel or Deno subhosting or Cloudflare Workers, but with direct access to your databases. They are JavaScript functions executed in Rust using a runtime based on Deno. The functions are stored in a database and can be replicated through LiteFS, putting them closer to the user.

// get.index.js
export async function handleRequest(req) {
    const db = new Database("example.sql");

    const result = await db.query("SELECT * FROM example WHERE id = ?", [1]);

    return new Response(JSON.stringify({data: result}), {
      status: 200,
      headers: {
          "content-type": "application/json",
      },
  });
}

Query allows you to create branches, it duplicates a database to be utilized in development environments.

query branch <SUBCOMMAND>

Additionally, Query provides a basic migration system that manages your databases by sending a batch of queries.

query migration <DB_NAME> <PATH>

Benefits of using Query

The benefits of using Query are endless, as it provides a robust API on top of your databases.

With Query CLI you can safely manage your databases, from creating a branch to testing a migration before executing it in production to a function that receives a request from a webhook coming from a headless CMS and manipulates the data received before inserting it into the database.

Query Studio showcases the power of Query. It is an online SQLite editor for Query, allowing you to access databases using a UI built with Bun. Using the Query API, Query Studio facilitates the creation, reading, updating, and deletion of data from databases and column fields.

How to use Query

We recommend using Query with Fly. It will help you deploy your server in minutes and replicate your databases worldwide.

The Hands-on Fly guide covers CLI installation, sign-up, and sign-in for new Fly users.

There are two ways to use Query. You can either use it as a standalone service or use it with a proxy to connect to your app. You can access your databases directly from your application and Query using the Query Proxy. On the other hand, using Query as an isolated service allows you to access the databases through HTTP requests using the API.

Using the proxy instead of the isolated service offers the advantage of easier replication and scaling, as Query and your application share the same VM.

If you are an Epic Stack user or want to explore an example using it with Query, we have published a repository for you to review. You can find the example in the Epic Stack documentation.

There is an example on the Query repository for Bun users to test the proxy feature.

How to get involved?

Get involved with Query by visiting the GitHub Page to explore the codebase and discussions. Identify areas to contribute through existing issues, participate in discussions, and submit code enhancements via pull requests. Please spread the word to build a vibrant community around Query.

Conclusion

Query is an excellent tool to empower all your LiteFS projects. I strongly suggest exploring its features; you will realize its vast potential.

References: