Iridium

Iridium is a markdown-native web framework built around .ir files and exposed as a Vite plugin. This repository now includes:

• file-based routing for app src/pages
• reusable .ir components from app src/components and src/layouts
• ---page, ---mdstyle, and ---ts blocks
• markdown rendering with {expression} interpolation
• built-in markdown defaults for hierarchy and spacing even without ---mdstyle
• ---mdstyle defaults that still yield to explicit wrapper and element text classes
• @if, @each, @as, @link, @click, @bind, @slot, @props, and inline element decorators
• Vite-powered dev/build flow with prerendered static routes
• bundled client runtime for true island hydration and subtree rerendering
• client-side @link navigation between Iridium pages
• colocated .ir.ts execution with imported modules and top-level await on the server
• Tailwind CSS bundled through Vite with .ir files included in class scanning
• a publishable package build in dist/
• a consumer verification app in examples/package-app
• a reusable language-analysis layer and VS Code extension in extensions/vscode

Getting Started

bun install
bun run build:package
cd examples/package-app
bun install
bun run dev

Then open the local Vite URL from the example app.

Install In Another Project

bun add iridium vite tailwindcss @tailwindcss/vite

import tailwindcss from "@tailwindcss/vite";
import { defineConfig } from "vite";
import { iridium } from "iridium";

export default defineConfig({
  plugins: [tailwindcss(), iridium()],
});

Then add your .ir files under:

src/
  pages/
  components/
  layouts/

Vite Integration

Iridium is wired through vite.config.ts using the exported iridium() plugin from index.ts.

• bun run dev in your app starts Vite with Iridium route handling
• bun run build in your app prerenders static .ir routes into dist
• Tailwind styles are loaded from src/styles/iridium.css through the Vite asset graph
• colocated .ir.ts files can import sibling modules and export SSR-ready values
• dynamic routes such as [slug].ir can be prerendered by passing getStaticPaths to iridium()
• pages can also export staticParams from inline ---ts or a colocated .ir.ts

import tailwindcss from "@tailwindcss/vite";
import { defineConfig } from "vite";
import { iridium } from "./index";

export default defineConfig({
  plugins: [
    tailwindcss(),
    iridium({
      getStaticPaths(route) {
        if (route.routePath === "/blog/:slug") {
          return [{ slug: "hello-world" }, { slug: "launch-post" }];
        }

        return [];
      },
    }),
  ],
});

---ts
export function staticParams() {
  return [{ slug: "hello-world" }, { slug: "launch-post" }]
}
---

Project Layout

src/
  pages/
  components/
  layouts/

Pages map to routes. Components and layouts are auto-resolved by filename.

This framework repository keeps its demo app in examples/package-app so the package source stays focused on the framework itself.

Package Build

Build the publishable package with:

bun run build:package

This emits the public package into dist/ and exposes:

• iridium
• iridium/runtime/client
• iridium/language

Editor Support

The repository includes a VS Code extension at extensions/vscode.

cd extensions/vscode
bun install
bun run build

The shared language intelligence lives in the main package so other editors can reuse it through iridium/language instead of reimplementing Iridium parsing and project resolution themselves.

To test the published shape locally:

npm pack
cd examples/package-app
bun install
bun run build

examples/package-app is wired as a real consumer app that installs the packed tarball rather than importing the framework source directly.

Current Boundaries

This implementation is now usable for real .ir pages, but there are still a few framework-level gaps:

• hydration boundaries are node-level islands, but there is not yet a compiler pass that hoists static island internals or does deeper payload deduplication
• inline ---ts blocks support top-level await, but inline module code is still less capable than colocated .ir.ts files
• inline scripts are merged with colocated scripts for runtime scope, but inline code should not yet depend on colocated exports at module-evaluation time
• dynamic route params now support build-time expansion from both Vite config and page-module exports, but there is not yet a dedicated ---page syntax for them