Lesson 09 of 10

CLI & Dev Server

Master every command, flag, and workflow tool OrbLayout provides — from scaffolding to live-reload development to production builds.

In This Lesson

CLI Overview
orb init
orb build
orb dev
orb clean
Configuration (orb.config.json)
npm Scripts
Programmatic API
Checkpoint

CLI Overview

OrbLayout ships with a single CLI binary: orb. Every command starts with it.

All Commands terminal

orb init           # Scaffold a new project
orb build          # Compile .orb → HTML
orb build --minify # Compile + minify HTML/CSS/JS
orb dev            # Dev server with live reload
orb dev --port 8080# Custom port
orb clean          # Remove dist/ folder
orb help           # Show help
orb version        # Show version (v1.2.0)

Command	What It Does	Flags
`init`	Creates project folders + starter files	—
`build`	Compiles all pages to `dist/`	`--minify`
`dev`	Starts dev server + watches files	`--port <num>`
`clean`	Empties the `dist/` directory	—
`help`	Displays all commands & options	—
`version`	Prints the installed version	—

orb init — Scaffold a Project

Run orb init in an empty directory to generate the full project structure.

Terminal bash

mkdir my-site && cd my-site
npx orblayout init

What gets created

Output

  ╔═══════════════════════════════════════╗
  ║     ◉  O r b L a y o u t  v1.2.0    ║
  ║     Static Site Builder               ║
  ╚═══════════════════════════════════════╝

  Scaffolding new OrbLayout project...

  ✓ Created pages/
  ✓ Created components/
  ✓ Created layouts/
  ✓ Created assets/
  ✓ Created orb.config.json
  ✓ Created layouts/main.layout
  ✓ Created components/header.orb
  ✓ Created components/footer.orb
  ✓ Created pages/index.orb

  ──────────────────────────────────
  Project scaffolded! Run:

    orb build    — Build static HTML
    orb dev      — Start dev server

💡

Safe to run again. orb init only creates files that don't already exist — it will never overwrite your work.

orb build — Compile Your Site

Compiles every .orb file in pages/ into static HTML in dist/.

Terminal bash

orb build

Output

  Building pages...

  ✓ index.orb → index.html
  ✓ about.orb → about.html
  ✓ blog/post-1.orb → blog/post-1.html
  ✓ Assets copied

  ──────────────────────────────────
  Done! 3 page(s) compiled in 24ms
  Output: dist/

The build pipeline

📋

Here's exactly what happens during a build:

Empty dist/ folder (clean start)
Discover all .orb files in pages/
For each page: parse data → resolve imports → process components → process loops → process conditionals → process with blocks → apply filters → resolve variables → inject layout → collect styles
Minify HTML (if --minify flag)
Write output to dist/
Copy assets/ → dist/assets/

--minify flag

Produces smaller HTML for production:

Minified build bash

orb build --minify

# What minification does:
# - Removes whitespace
# - Removes HTML comments
# - Removes redundant attributes
# - Minifies inline CSS & JS

Subdirectories

Nested folders in pages/ create matching directories in output:

Source pages/

pages/
├── index.orb
├── about.orb
└── blog/
    ├── post-1.orb
    └── post-2.orb

Output dist/

dist/
├── index.html
├── about.html
└── blog/
    ├── post-1.html
    └── post-2.html

orb dev — Development Server

Start a local server that watches your files and auto-refreshes the browser when you save.

Terminal bash

orb dev

# Or with custom port:
orb dev --port 8080

Output

  Building...

  ✓ index.orb → index.html
  ✓ Assets copied

  🌐 OrbLayout dev server running at http://localhost:3000
  Watching for changes...

How live reload works

⚡

OrbLayout uses SSE (Server-Sent Events) — no WebSocket dependency needed.

Watch: Chokidar monitors pages/, components/, layouts/, and assets/
Rebuild: On file change, the entire site is rebuilt (~20ms)
Notify: SSE sends "reload" to all connected browsers
Refresh: JavaScript in the page calls window.location.reload()

What gets served

Feature	Details
Static files	Served from `dist/`
Clean URLs	`/about` → `about.html`
Directory indexes	`/blog/` → `blog/index.html`
MIME types	HTML, CSS, JS, JSON, PNG, JPG, SVG, fonts
SSE endpoint	`/__orb_reload`
404 page	Built-in styled dark-theme 404

Press Ctrl+C to stop the server gracefully.

orb clean — Clear Output

Removes everything inside dist/. Useful before a fresh production build.

Terminal bash

orb clean

# Then rebuild from scratch:
orb build --minify

Configuration — orb.config.json

Every OrbLayout project reads its settings from orb.config.json in the project root.

orb.config.json json

{
  "pagesDir":      "pages",
  "componentsDir": "components",
  "layoutsDir":    "layouts",
  "outputDir":     "dist",
  "assetsDir":     "assets",
  "minify":        false,
  "pretty":        true
}

Key	Default	Description
`pagesDir`	`"pages"`	Directory containing your `.orb` source files
`componentsDir`	`"components"`	Directory for reusable component files
`layoutsDir`	`"layouts"`	Directory for `.layout` templates
`outputDir`	`"dist"`	Where compiled HTML is written
`assetsDir`	`"assets"`	Static files copied to output as-is
`minify`	`false`	Enable HTML minification (also via `--minify` flag)
`pretty`	`true`	Pretty-print output HTML

Custom directory names

You can rename any directory:

Custom config json

{
  "pagesDir":      "src/views",
  "componentsDir": "src/ui",
  "layoutsDir":    "src/templates",
  "outputDir":     "build",
  "assetsDir":     "public",
  "minify":        true
}

📋

If orb.config.json doesn't exist, OrbLayout uses the defaults. You only need to include keys you want to change.

npm Scripts

Add OrbLayout commands to your package.json for convenience:

package.json json

{
  "name": "my-site",
  "scripts": {
    "dev":   "orb dev",
    "build": "orb build",
    "prod":  "orb clean && orb build --minify",
    "clean": "orb clean"
  }
}

Usage bash

npm run dev    # Start dev server
npm run build  # Build site
npm run prod   # Clean + minified production build

Programmatic API

Use OrbLayout from your own Node.js scripts — perfect for custom build pipelines, CI/CD, and automation.

build-script.js javascript

const { loadConfig, OrbCompiler, OrbBuilder, OrbDevServer } = require("orblayout");

// Load config from current directory
const config = loadConfig(__dirname);

// ── Option 1: Full build ──
const builder = new OrbBuilder(config);
const result = await builder.build();
console.log(`Built ${result.pages} pages in ${result.time}ms`);

// ── Option 2: Compile a single page ──
const compiler = new OrbCompiler(config);
const html = compiler.compilePage("pages/index.orb");

// ── Option 3: Start dev server ──
const server = new OrbDevServer(config);
await server.start(3000);

Custom filters via API

const { loadConfig, OrbCompiler } = require("orblayout");

const config = loadConfig(__dirname);
const compiler = new OrbCompiler(config);

// Register your own filter
compiler.registerFilter("shout", (value) => {
  return value.toUpperCase() + "!!!";
});

compiler.registerFilter("dollars", (value) => {
  return "$" + Number(value).toFixed(2);
});

// Now {{ greeting | shout }} → "HELLO!!!"
// And {{ price | dollars }} → "$9.99"

Exported modules

Export	Type	Description
`loadConfig(rootDir)`	Function	Reads `orb.config.json` and returns resolved config object
`OrbCompiler`	Class	Core compiler — `.compilePage(path)`, `.registerFilter(name, fn)`
`OrbBuilder`	Class	Build orchestrator — `.build()` discovers & compiles all pages
`OrbDevServer`	Class	Dev server — `.start(port)`, `.stop()`

✅ Lesson 9 Checkpoint

You should now be able to:

Use every CLI command: init, build, dev, clean, help, version
Build minified production HTML with --minify
Run a live-reloading dev server with custom ports
Configure orb.config.json with custom directories
Set up npm scripts for a professional workflow
Use the programmatic API to build custom tooling
Register custom filters via compiler.registerFilter()

← Previous Advanced Features Next Lesson → Build a Real Project