Building with LARC: A Reference Manual

About This Book

"Building with LARC: A Reference Manual" is the definitive technical reference for LARC developers. Unlike the narrative tutorial "Learning LARC," this book is organized for quick reference, comprehensive API documentation, and practical problem-solving.

This book follows the O'Reilly programming book tradition—starting with philosophy and context, moving through practical implementation, and concluding with exhaustive API documentation and quick-reference appendices.

📦 Building the Book

This book can be built in multiple formats:

• QUICKSTART.md - Get started in 3 easy steps
• BUILD.md - Complete build documentation
• Build Script: ./build-book.sh - Generates HTML, PDF, and EPUB

# Quick build (all formats)
./build-book.sh

# Or use Make/npm
make
npm run build

• 📄 HTML - output/html/building-with-larc.html
• 📕 PDF - output/pdf/building-with-larc.pdf
• 📱 EPUB - output/epub/building-with-larc.epub

Table of Contents

Part I: Foundations

• What is LARC?
• Who should use this book
• How to use this book
• Relationship to "Learning LARC"
• Prerequisites and assumptions
• Book conventions and notation

• The state management crisis
• Message-passing architecture
• DOM-native communication principles
• Zero-dependency, zero-build philosophy
• Progressive enhancement and graceful degradation
• Comparison to other approaches (Redux, Vuex, MobX, Context API)

• Origins and motivation
• Design decisions and trade-offs
• Evolution of the PAN (Page Area Network) concept
• Real-world use cases and applications
• Community and ecosystem

• Message bus architecture
• Pub/sub pattern in depth
• Topics and routing
• Message lifecycle
• Components and composition
• State management strategies
• Event envelopes and metadata

• Installation and setup
• Project structure recommendations
• Development environment
• Serving static files
• Browser requirements and compatibility
• DevTools and debugging setup

Part II: Building Applications

• Publishing messages
• Subscribing to topics
• Wildcard patterns
• Message retention
• Unsubscribing and cleanup

• Creating web components
• Component lifecycle
• Shadow DOM considerations
• Connecting components via PAN bus
• Component communication patterns
• Reusable component design

• Local vs. shared state
• State persistence strategies
• IndexedDB integration
• OPFS (Origin Private File System)
• Synchronization patterns
• Conflict resolution

• Client-side routing with pan-routes
• Route definitions and patterns
• Navigation guards
• Deep linking
• History management
• SEO considerations

• Form handling patterns
• Schema-driven forms
• Validation strategies
• File uploads
• Rich text editing
• Markdown integration

• REST API integration
• GraphQL connectors
• WebSocket communication
• Server-Sent Events (SSE)
• Error handling and retries
• Caching strategies

• JWT authentication patterns
• Session management
• Role-based access control
• Security best practices
• Protected routes
• Token refresh strategies

• WebSocket integration
• SSE for live updates
• BroadcastChannel for multi-tab sync
• Web Workers for background tasks
• Real-time collaboration patterns

• OPFS file operations
• File browser components
• Upload and download
• File type filtering
• Directory navigation
• Storage quotas and limits

• CSS custom properties
• Theme system architecture
• Light/dark mode
• Theme provider component
• Dynamic theme switching
• Responsive design patterns

• Message filtering and routing efficiency
• Component lazy loading
• Virtual scrolling for large lists
• Debouncing and throttling
• Memory management
• Bundle size optimization

• Unit testing components
• Integration testing message flows
• E2E testing with PAN apps
• Mocking the bus
• Testing async operations
• Test utilities and helpers

• Error boundaries
• Message tracing
• DevTools integration
• Logging strategies
• Error reporting
• Common pitfalls and solutions

• Message forwarding and bridging
• Multi-bus architectures
• Backend integration strategies
• Micro-frontends with LARC
• Plugin systems
• Middleware patterns

• Build considerations (or lack thereof)
• CDN deployment
• Caching strategies
• Performance monitoring
• Production debugging
• Versioning and upgrades

Part III: Component Reference

• pan-bus: Message bus with pub/sub architecture
• pan-theme-provider: Theme management system
• pan-theme-toggle: Theme switching UI control
• pan-routes: Message routing and transformation

• pan-store: Reactive state management
• pan-idb: IndexedDB integration

• pan-files: File browser with OPFS
• pan-markdown-editor: Rich markdown editor
• pan-markdown-renderer: Markdown display

• pan-data-connector: REST API integration
• pan-graphql-connector: GraphQL client
• pan-websocket: WebSocket communication
• pan-sse: Server-Sent Events

• pan-debug: Message tracing and debugging
• pan-forwarder: HTTP message forwarding

Part IV: Appendices

• Standard topic conventions
• Reserved topics
• Topic naming best practices
• Topic hierarchy patterns

• Envelope structure
• Standard fields
• Metadata
• Versioning

• Bus configuration
• Component configuration
• Global settings
• Environment variables

• Upgrading from older versions
• Breaking changes
• Deprecation notices
• Migration patterns

• Common use cases
• Code snippets
• Design patterns
• Anti-patterns to avoid

• Technical terms
• LARC-specific terminology
• Web standards references

• Official documentation
• Community links
• Example applications
• Related projects
• Further reading

• Comprehensive alphabetical index of all topics, APIs, components, and concepts

Book Statistics

• Total Chapters: 25 chapters + 7 appendices + index
• Total Word Count: ~115,000 words
• Code Examples: 200+ complete, working examples
• Components Documented: 13 core LARC components
• Recipes: 10 practical, copy-paste ready patterns

How to Use This Book

As a Learning Resource

As a Reference

As a Problem-Solving Guide

• Chapter 18 for debugging issues
• Appendix E for common patterns and recipes
• Part II chapters for implementation guidance
• Part III for component-specific solutions

For Migration and Maintenance

Companion Materials

• Learning LARC - Narrative tutorial for beginners
• LARC Examples - Working demo applications at /examples
• LARC Demo Apps - Production-quality sample apps at /apps
• Component Source Code - Reference implementation at /core
• API Documentation - Generated docs at /docs/api

Document Conventions

Throughout this book:

• Code blocks show complete, runnable examples
• Component names appear in monospace: pan-bus
• Message topics use dot notation: user.login.success
• Attributes are shown with values: debug="true"
• Methods include parentheses: subscribe()
• File paths are absolute from project root: /src/app.js

About the Authors

This reference manual was created to complement the LARC framework and provide developers with comprehensive, accurate documentation for building production applications.

For questions, contributions, or feedback, see Appendix G: Resources.

License

This documentation is provided as part of the LARC project and follows the same license as the framework.