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

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

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

Part II: Building Applications

• Local vs. shared state
• State persistence strategies (localStorage, IndexedDB, OPFS)
• State synchronization patterns
• Optimistic updates
• 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: 21 chapters + 7 appendices + index
• Total Word Count: ~82,000 words
• Code Examples: 200+ complete, working examples
• Components Documented: 13 core LARC components
• Recipes: 10+ practical, copy-paste ready patterns

Browser Compatibility

LARC requires modern browsers with support for:

• Custom Elements v1 (Chrome 54+, Firefox 63+, Safari 10.1+, Edge 79+)
• Shadow DOM v1 (Chrome 53+, Firefox 63+, Safari 10+, Edge 79+)
• ES Modules (Chrome 61+, Firefox 60+, Safari 11+, Edge 79+)
• Import Maps (Chrome 89+, Firefox 108+, Safari 16.4+, Edge 89+)

• Chrome/Edge: 89+ (March 2021)
• Firefox: 108+ (December 2022)
• Safari: 16.4+ (March 2023)

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.