Loading repository data…
Loading repository data…
gc-victor / repository
SXO is a multi-runtime server-side JSX tool for Node.js, Bun, Deno, and Cloudflare Workers. It includes SXOUI, a framework-agnostic UI library inspired by shadcn/ui
A fast, minimal architecture convention and CLI for building websites with server‑side JSX. No React, no client framework, just composable JSX optimized for the server, a clean directory-based router, hot replacement, and powered by esbuild plus a Rust JSX transformer.
Multi-Platform Library: SXO runs seamlessly across Node.js, Bun, Deno, and Cloudflare Workers. The CLI automatically detects your runtime and loads the optimized adapter, while providing a consistent development and production experience across all platforms.
index.(jsx|tsx)).<html>, <head>, and <body>.--loaders ".svg=file" --loaders ".ts=tsx").--public-path), env (PUBLIC_PATH), or config; empty string "" allowed for relative URLs.SXO is designed as a truly multi-runtime library that runs seamlessly across different JavaScript runtimes:
The SXO CLI automatically detects your JavaScript runtime and loads the appropriate platform adapter:
# Same command works everywhere
npx sxo dev # Development server
npx sxo start # Production server
Runtime Detection: The CLI checks globalThis.Bun and globalThis.Deno to identify the current platform, falling back to Node.js. Each adapter uses platform-native APIs (e.g., Bun.serve(), Deno.serve(), http.createServer()) for optimal performance.
Shared Core Logic: All adapters share the same Web Standard-based core (Request/Response), ensuring consistent behavior across platforms. Routing, SSR, static file serving, and middleware execution work identically everywhere.
Cloudflare Workers: Due to its unique environment, Cloudflare Workers requires a custom entry point using the sxo/cloudflare export and a factory pattern (see Platform Adapters).
Model
src) containing:
components directory with JSX componentsutils directory with utility functionsmiddleware.js defining user middleware chainsrc/pages) containing:
global.css (optional)index.(tsx|jsx)index.* page file becomes a route.<clientDir>/index.(ts|tsx|js|jsx) inside that route directory is added as a client entry (default clientDir is "client"; precedence: .ts > .tsx > .js > .jsx).global.css, if present, is added as a shared stylesheet entry for every route.dist/clientdist/serverdist/server/routes.jsonAliases Available in both client & server builds:
@components -> src/components
@pages -> src/pages
@utils -> src/utils
Install & run (no install needed if using npx):
npx sxo dev
or
pnpm dlx sxo dev
Example structure:
your-app
├── src
│ ├── middleware.js
│ ├── components
│ │ ├── Page.jsx
│ │ └── Header.jsx
│ └── pages
│ ├── global.css
│ ├── index.jsx
│ └── about
│ ├── index.jsx
│ └── client
│ └── index.js
└── package.json
Example component:
// src/components/Page.jsx
export function Page({ children }) {
return <div className="page">{children}</div>;
}
Example page:
// src/pages/index.jsx
import { Header } from "@components/Header.js";
export default () => (
<html lang="en">
<head>
<meta charSet="UTF-8" />
<title>Home</title>
</head>
<body>
<Header title="Home" />
<p>Welcome to SXO.</p>
</body>
</html>
);
Commands:
sxo create <project> # Create a new SXO project from templates (prompts for runtime; defaults to node)
sxo add <component> # Add a component from the basecoat library to src/components
sxo dev # Start the development server with hot replace
sxo build # Build the project for production (client and server bundles)
sxo start # Start the production server to serve built output
sxo clean # Remove the output directory (clean build artifacts)
sxo generate # Pre-render static routes to HTML after a successful build
Create a new project:
# Create a new project in a new directory
sxo create my-app
# Create a project in the current directory
sxo create .
# Or omit the name entirely (uses current directory name)
sxo create
Runtime Selection:
When you run the command, you'll see an interactive prompt to select your target runtime:
Select a runtime:
1) node (default)
2) bun
3) deno
4) workers
>
node (default)1 → selects node2 → selects bun3 → selects deno4 → selects workers (Cloudflare Workers)In non-interactive environments (CI, tests), the prompt is skipped and node is used automatically.
Templates are fetched from the gc-victor/sxo repository under templates/<runtime>/....
Existing Directory:
If the target directory already exists, you'll be prompted to confirm overwriting:
Create SXO template in "my-app"? (This will overwrite existing files.) (y/N)
Full Example Workflow:
# 1. Create the project
sxo create my-app
# 2. Select runtime when prompted (or press Enter for node)
# > 2 (selects bun)
# 3. Follow the next steps printed by the CLI
cd my-app
pnpm install
pnpm run dev
Add components from SXOUI:
# Add a button component
sxo add button
# Add a dialog component
sxo add dialog
# Components are installed to src/components/
# Browse all available components at https://sxoui.com
SXOUI Component Library: SXO includes access to 25+ production-ready components via the sxo add command. Visit sxoui.com to browse the complete component library with live demos, accessibility documentation, and copy-paste ready code examples.
Point to a different pages directory:
sxo build --pages-dir examples/node/src/pages
sxo start --pages-dir examples/node/src/pages --port 4011
Configure custom esbuild loaders for the server build:
# Via CLI flags (repeatable or comma-separated)
sxo dev --loaders ".svg=file" --loaders ".ts=tsx"
sxo build --loaders "svg=file,ts=tsx"
# Via environment variable (JSON format)
LOADERS='{"svg":"file",".ts":"tsx"}' sxo dev
# Via config file (sxo.config.json or sxo.config.js)
{
"loaders": {
".svg": "file",
".ts": "tsx"
}
}
🎨 sxoui.com — Production-ready components for SXO
SXOUI is a comprehensive component library built specifically for SXO, featuring 25+ accessible, semantic, and performant components that work with server-side rendering and optional client-side interactivity.