![[ICO]](/icons/blank.gif){kind=icon}
![[PARENTDIR]](/icons/back.gif){kind=icon}
![[DIR]](/icons/folder.gif){kind=icon}
![[DIR]](/icons/bomb.gif){kind=icon}
![[TXT]](/icons/text.gif){kind=icon}
LARC
Lightweight Asynchronous Relay Core - A minimal, message-based framework for building reactive web applications with zero dependencies.       
๐ฆ Using LARC in Your App
LARC provides a lightweight messaging bus and component library for building modern web applications. Perfect for microfront ends, event-driven architectures, and composable UIs.
Installation
# Core messaging bus (required)
npm install @larcjs/core
# Optional: UI component library
npm install @larcjs/ui
# Or start with the lightweight version (9KB)
npm install @larcjs/core-liteQuick Start
<!DOCTYPE html>
<html>
<head>
<title>My LARC App</title>
</head>
<body>
<!-- Your content here -->
<div id="app"></div>
<script type="module">
// Import from CDN - includes bus and client
import { PanClient, ensureBus } from 'https://cdn.jsdelivr.net/npm/@larcjs/core@3.0.1/index.js';
// Ensure bus exists
ensureBus();
const client = new PanClient();
await client.ready();
// Subscribe to messages
client.subscribe('user.login', (msg) => {
console.log('User logged in:', msg.data);
document.getElementById('app').innerHTML = `<h1>Welcome, ${msg.data.username}!</h1>`;
});
// Publish messages
client.publish({
topic: 'user.login',
data: { username: 'alice', timestamp: Date.now() }
});
</script>
</body>
</html>import { PanClient, ensureBus } from '@larcjs/core';
ensureBus();
const client = new PanClient();
await client.ready();
client.subscribe('app.*', (msg) => console.log(msg));
client.publish({ topic: 'app.ready', data: { version: '1.0' } });Package Overview
Core Packages:@larcjs/core(v3.0.1) - Full-featured messaging bus with routing and debug tools@larcjs/core-lite(v3.0.1) - Lightweight 9KB version (perfect for production) โญ@larcjs/ui(v3.0.1) - UI component library
@larcjs/core-routing(v3.0.1) - Dynamic message routing (8KB)@larcjs/core-debug(v3.0.1) - Debug and tracing tools (3KB)
@larcjs/react-adapter- React hooks for PAN buscreate-larc-app- CLI for scaffolding new projects
@larcjs/core-types- Type definitions for @larcjs/core@larcjs/ui-types- Type definitions for @larcjs/ui
Documentation
- ๐ Full Documentation
- ๐ Getting Started Guide
- ๐ API Reference
- ๐ก Examples
- โ FAQ
๐ ๏ธ Developing LARC Locally
This section is for contributors who want to work on LARC itself.
Prerequisites
- Node.js >= 22.0.0
- Git
Setup
# Clone the repository
git clone https://github.com/larcjs/larc.git
cd larc
# Install all dependencies (npm workspaces)
npm install
# Or use pnpm if you prefer
pnpm installRepository Structure
larc/
โโโ packages/ โ Published packages (npm workspaces)
โ โโโ core/ โ @larcjs/core
โ โโโ ui/ โ @larcjs/ui
โ โโโ core-lite/ โ @larcjs/core-lite (9KB)
โ โโโ core-routing/ โ @larcjs/core-routing
โ โโโ core-debug/ โ @larcjs/core-debug
โ โโโ core-types/ โ TypeScript types
โ โโโ components-types/ โ TypeScript types
โโโ apps/ โ Demo applications
โโโ examples/ โ Code examples
โโโ devtools/ โ Chrome DevTools extension
โโโ cli/ โ create-larc-app
โโโ react-adapter/ โ React integration
โโโ registry/ โ Component registry
โโโ vscode-extension/ โ VS Code extension
โโโ docs/ โ Documentation & guides
โโโ playground/ โ Interactive component explorerDevelopment Workflows
#### Working on Core or Components
The core runtime and component library are in the packages directory:
# Work on core
cd packages/core
npm install
npm run build
npm test
# Work on components
cd packages/ui
npm install
npm run build
npm test#### Working on Packages
# Work on core-lite
cd packages/core-lite
# Make changes...
npm run build:minify
# Work on types
cd packages/core-types
# Edit type definitions...#### Using npm Workspaces
Run commands across all workspaces:
# Build all packages
npm run build
# Test all packages
npm run test
# Run specific workspace
npm run build --workspace @larcjs/core
npm run test --workspace @larcjs/ui
npm run dev --workspace @larcjs/site#### Using pnpm (Alternative)
If you prefer pnpm, all the original scripts are preserved:
# Build all packages
pnpm run pnpm:build
# Test all packages
pnpm run pnpm:test
# Dev mode (parallel)
pnpm run pnpm:devPublishing Packages
Packages are published to npm from the monorepo:
# Publish a specific package
cd packages/core-lite
npm publish
# Publish core or components
cd packages/core
npm publish
cd packages/ui
npm publishRunning Examples
# Serve examples locally
cd examples
python3 -m http.server 8888
# Visit http://localhost:8888Building Documentation
# Build and serve docs
npm run dev --workspace @larcjs/site
# Or manually
cd site
npm run build
npm run serveTesting
Current Status:- โ @larcjs/core: 261 tests passing (87 tests ร 3 browsers)
- โ @larcjs/ui: 165 tests passing (55 tests ร 3 browsers)
# Test everything
npm test
# Test specific packages
npm run test:core
npm run test:ui
# Test with coverage
cd packages/core
npm run test:coverageAll UI components are tested end-to-end across Chromium, Firefox, and WebKit using Playwright.
๐ค Contributing
We welcome contributions! Here's how to get started:
git clone https://github.com/YOUR-USERNAME/larc.gitnpm installgit checkout -b feature/my-featurenpm testSee CONTRIBUTING.md for detailed guidelines.
๐ Available Scripts
| Script | Description |
|--------|-------------|
| npm run build | Build all workspace packages |
| npm run test | Run tests across all packages |
| npm run dev | Start development mode |
| npm run lint | Lint all packages |
| npm run serve | Serve examples on port 8000 |
| npm run build:core | Build only @larcjs/core |
| npm run build:ui | Build only @larcjs/ui |
| npm run test:core | Test only @larcjs/core |
| npm run dev:site | Run documentation site |
For pnpm users, all scripts are available with the pnpm: prefix:
npm run pnpm:build,npm run pnpm:test, etc.
๐ฆ Published Packages
These packages are published to npm:
| Package | Version | Description | |---------|---------|-------------| | @larcjs/core | 3.0.1 | Full-featured messaging bus | | @larcjs/core-lite | 3.0.1 | Lightweight 9KB version โญ | | @larcjs/ui | 3.0.1 | UI component library | | @larcjs/core-routing | 3.0.1 | Message routing add-on | | @larcjs/core-debug | 3.0.1 | Debug tools add-on | | @larcjs/core-types | 3.0.1 | TypeScript types | | @larcjs/ui-types | 3.0.1 | TypeScript types | | @larcjs/react-adapter | 3.0.1 | React integration | | create-larc-app | 3.0.1 | Project scaffolding CLI |
๐ Links
- Website: larcjs.com
- Documentation: larcjs.com
- Examples: larcjs.com/examples
- npm Organization: @larcjs
- GitHub: github.com/larcjs
- Discord: Join our Discord
๐ License
MIT ยฉ LARC Contributors
Note: This repository uses npm workspaces for monorepo management. All packages are published under the
@larcjs npm organization.
Demo: Check out the Wiki Explorer - a live demo showcasing LARC's tree navigation and markdown rendering components.