LARC

Lightweight Asynchronous Relay Core - A minimal, message-based framework for building reactive web applications with zero dependencies. ![npm version](https://www.npmjs.com/package/@larcjs/core) ![npm version](https://www.npmjs.com/package/@larcjs/ui) ![npm downloads](https://www.npmjs.com/package/@larcjs/core) ![CI Status](https://github.com/larcjs/larc/actions) ![License: MIT](https://opensource.org/licenses/MIT) ![PRs Welcome](./CONTRIBUTING.md)

📦 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-lite

Quick Start

<!DOCTYPE html>
<html>
<head>
  <title>My LARC App</title>
</head>
<body>
  <!-- Include the PAN bus -->
  <pan-bus debug="true"></pan-bus>

  <!-- Your content here -->
  <div id="app"></div>

  <script type="module">
    import { PanClient } from '@larcjs/core';

    const client = new PanClient();

    // Subscribe to messages
    client.subscribe('user.login', (msg) => {
      console.log('User logged in:', msg.data);
    });

    // Publish messages
    client.publish({
      topic: 'user.login',
      data: { username: 'alice', timestamp: Date.now() }
    });
  </script>
</body>
</html>

Package Overview

Core Packages:

@larcjs/core (v2.0.0) - Full-featured messaging bus with routing and debug tools
@larcjs/core-lite (v2.0.0) - Lightweight 9KB version (perfect for production) ⭐
@larcjs/ui (v2.0.0) - UI component library

Add-ons:

@larcjs/core-routing (v2.0.0) - Dynamic message routing (8KB)
@larcjs/core-debug (v2.0.0) - Debug and tracing tools (3KB)

Framework Integrations:

@larcjs/react-adapter - React hooks for PAN bus
create-larc-app - CLI for scaffolding new projects

TypeScript Support:

@larcjs/core-types - Type definitions for @larcjs/core
@larcjs/ui-types - Type definitions for @larcjs/ui

Documentation

🛠️ Developing LARC Locally

This section is for contributors who want to work on LARC itself.

Prerequisites

Node.js >= 18.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 install

Repository Structure

larc/
├── packages/                   → Published packages (npm workspaces)
│   ├── core/                   → @larcjs/core
│   ├── components/             → @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 explorer

Development 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:dev

Publishing 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 publish

Running Examples

# Serve examples locally
cd packages/examples
python3 -m http.server 8888
# Visit http://localhost:8888

Building Documentation

# Build and serve docs
npm run dev --workspace @larcjs/site

# Or manually
cd site
npm run build
npm run serve

Testing

# Test everything
npm test

# Test specific packages
npm run test:core
npm run test:components

# Test with coverage
cd packages/core
npm run test:coverage

🤝 Contributing

We welcome contributions! Here's how to get started:

Fork the repository

Clone your fork: git clone https://github.com/YOUR-USERNAME/larc.git

Install dependencies: npm install

Create a feature branch: git checkout -b feature/my-feature

Make your changes and add tests

Test your changes: npm test

Commit with clear messages

Push to your fork

Submit a pull request

See 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:components | 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 | 2.0.0 | Full-featured messaging bus | | @larcjs/core-lite | 2.0.0 | Lightweight 9KB version ⭐ | | @larcjs/ui | 2.0.0 | UI component library | | @larcjs/core-routing | 2.0.0 | Message routing add-on | | @larcjs/core-debug | 2.0.0 | Debug tools add-on | | @larcjs/core-types | 2.0.0 | TypeScript types | | @larcjs/ui-types | 2.0.0 | TypeScript types | | @larcjs/react-adapter | 2.0.0 | React integration | | create-larc-app | 2.0.0 | Project scaffolding CLI |

🔗 Links

Website: larcjs.com
Documentation: larcjs.github.io/larc
Examples: larcjs.github.io/larc/examples
npm Organization: @larcjs
GitHub: github.com/larcjs

📄 License

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.