@owlmeans/web-client

A complete React DOM client library for OwlMeans Common applications. This package provides a web-specific implementation that extends @owlmeans/client with DOM-specific functionality, including rendering utilities, web database integration, and browser-specific services.

Overview

The @owlmeans/web-client package is the web DOM implementation of the OwlMeans client system. It provides:

• DOM Rendering: Direct integration with ReactDOM for web applications
• Web Database: Browser-based database integration with IndexedDB/localStorage
• Authentication Integration: Pre-configured web authentication services
• Browser Services: Web-specific services and utilities
• I18n Integration: Internationalization support for web applications
• Router Integration: Web-specific routing with React Router DOM
• Context Management: Enhanced context with web-specific capabilities

This package is part of the OwlMeans client implementation family:

• @owlmeans/client: Base React client library
• @owlmeans/web-client: Web DOM implementation (this package)
• @owlmeans/native-client: React Native implementation

Installation

npm install @owlmeans/web-client react react-dom react-router-dom

Core Concepts

Web-First Architecture

This library is specifically designed for web browsers and provides DOM-specific functionality that isn't available in other environments.

Enhanced Context

The web context extends the base client context with web-specific services like database storage, authentication, and browser utilities.

Integrated Rendering

Provides seamless integration with ReactDOM including support for both client-side rendering and server-side hydration.

API Reference

Factory Functions

makeContext<C, T>(cfg: C): T

Creates a web-specific application context with all necessary web services pre-configured.

import { makeContext } from '@owlmeans/web-client'
import { AppType, Layer } from '@owlmeans/context'

const context = makeContext({
  service: 'my-web-app',
  type: AppType.Frontend,
  layer: Layer.Service,
  ready: false,
  services: {},
  brand: { name: 'My Web App' },
  trusted: []
})

Parameters:

• cfg: AppConfig - Configuration object for the web context

Returns: Enhanced AppContext with web-specific capabilities

Pre-configured Services:

• Web authentication service
• Web database service
• Client resource service
• Primary host extraction

render(node: ReactNode, opts?: RenderOptions): void

Renders a React application to the DOM with web-specific optimizations.

import { render } from '@owlmeans/web-client'
import { App } from '@owlmeans/client'

render(
  <App context={context}>
    <MyApplication />
  </App>,
  {
    domId: 'root',
    onReady: true,
    hydrate: false,
    debug: true
  }
)

Parameters:

• node: ReactNode - The React element to render
• opts: RenderOptions (optional) - Rendering configuration

Core Interfaces

AppContext<C extends AppConfig>

Web-specific application context that extends ClientContext with authentication capabilities.

interface AppContext<C extends AppConfig = AppConfig> extends ClientContext<C>,
  AuthServiceAppend {
  
  // Inherited from ClientContext:
  // - Configuration management
  // - State management
  // - Modal service
  // - Debug service
  // - Module and service registration
  // - Resource management
  
  // Enhanced with authentication:
  auth(): AuthService
}

AppConfig

Configuration interface for web applications (extends ClientConfig).

interface AppConfig extends ClientConfig {
  // Inherits all ClientConfig properties
  // Can be extended with web-specific configuration
}

RenderOptions

Configuration options for DOM rendering.

interface RenderOptions {
  domId?: string        // Target DOM element ID (default: 'root')
  onReady?: boolean     // Wait for DOMContentLoaded (default: true)
  hydrate?: boolean     // Use hydration for SSR (default: false)
  debug?: boolean       // Enable debug logging (default: false)
}

React Hooks

useContext<C, T>(): T

Web-specific context hook that provides strongly typed access to the AppContext.

import { useContext } from '@owlmeans/web-client'

function MyWebComponent() {
  const context = useContext()
  
  // Access web-specific services
  const authService = context.auth()
  const dbService = context.service('web-db')
  
  // Access base client services
  const stateResource = context.state()
  const modalService = context.modal()
  
  return <div>Web Component</div>
}

Web Services

Web Database Integration

The package automatically configures web database services:

// Access web database service
const dbService = context.service('web-db')

// Store data in browser
await dbService.store('user-preferences', {
  theme: 'dark',
  language: 'en'
})

// Retrieve data from browser
const preferences = await dbService.retrieve('user-preferences')

Authentication Service

Pre-configured web authentication with persistent storage:

// Access authentication service
const authService = context.auth()

// Authentication persists across browser sessions
const isAuthenticated = await authService.authenticated()

Helper Functions

extractPrimaryHost<C, T>(context: T): void

Extracts and configures the primary host from the current browser location.

Purpose: Automatically configures the application's primary host based on the browser's current URL

Usage: Called automatically during context creation

Constants

DEFAULT_ROOT

Default DOM element ID for rendering ('root').

Components and Modules

The package provides web-specific components and modules:

I18n Integration

import { i18nModules } from '@owlmeans/web-client'

// Pre-configured internationalization modules
context.registerModules(i18nModules)

Authentication Components

import { authComponents } from '@owlmeans/web-client'

// Web-specific authentication components
// Available through the component system

Usage Examples

Complete Web Application Setup

import React from 'react'
import { makeContext, render } from '@owlmeans/web-client'
import { App } from '@owlmeans/client'
import { createBrowserRouter } from 'react-router-dom'
import { AppType, Layer } from '@owlmeans/context'

// Create web application context
const context = makeContext({
  service: 'my-web-app',
  type: AppType.Frontend,
  layer: Layer.Service,
  ready: false,
  services: {},
  brand: { 
    name: 'My Web App',
    version: '1.0.0'
  },
  trusted: ['api.myapp.com']
})

// Register application modules
context.registerModules(appModules)

// Configure and initialize
await context.configure().init()

// Create router provider
const routerProvider = (routes) => createBrowserRouter(routes)

// Define the application
function MyWebApp() {
  return (
    <App context={context} provide={routerProvider}>
      <header>My Web Application</header>
      <main>
        {/* Application content will be rendered here by the router */}
      </main>
    </App>
  )
}

// Render to DOM
render(<MyWebApp />, {
  domId: 'root',
  debug: process.env.NODE_ENV === 'development'
})

Server-Side Rendering (SSR) with Hydration

import { makeContext, render } from '@owlmeans/web-client'
import { App } from '@owlmeans/client'

// Create context with SSR data
const context = makeContext({
  ...config,
  ssrData: window.__SSR_DATA__ // Data from server
})

// Pre-populate context with SSR data
await context.configure().init()

// Hydrate the server-rendered HTML
render(
  <App context={context}>
    <MyApplication />
  </App>,
  {
    hydrate: true, // Enable hydration
    onReady: false // Don't wait for DOMContentLoaded
  }
)

Authentication-Enabled Web App

import { makeContext, useContext } from '@owlmeans/web-client'
import { modules as authModules } from '@owlmeans/client-auth'

// Create context
const context = makeContext(config)

// Register authentication modules
context.registerModules(authModules)

// Initialize
await context.configure().init()

function AuthenticatedApp() {
  const context = useContext()
  const [isAuthenticated, setIsAuthenticated] = useState(false)
  
  useEffect(() => {
    const checkAuth = async () => {
      const authService = context.auth()
      const token = await authService.authenticated()
      setIsAuthenticated(token != null)
    }
    
    checkAuth()
  }, [])
  
  if (!isAuthenticated) {
    return <LoginPage />
  }
  
  return <Dashboard />
}

// Render with authentication
render(<AuthenticatedApp />)

Web Database Usage

import { useContext } from '@owlmeans/web-client'
import { useEffect, useState } from 'react'

function DataPersistentComponent() {
  const context = useContext()
  const [data, setData] = useState(null)
  
  useEffect(() => {
    const loadData = async () => {
      // Access web database through context
      const dbService = context.service('web-db')
      
      // Load persisted data
      const savedData = await dbService.retrieve('component-data')
      setData(savedData || { count: 0 })
    }
    
    loadData()
  }, [])
  
  const saveData = async (newData) => {
    const dbService = context.service('web-db')
    await dbService.store('component-data', newData)
    setData(newData)
  }
  
  const increment = () => {
    const newData = { count: data.count + 1 }
    saveData(newData)
  }
  
  return (
    <div>
      <p>Count: {data?.count || 0}</p>
      <button onClick={increment}>Increment</button>
    </div>
  )
}

Custom Rendering Options

import { render } from '@owlmeans/web-client'

// Render to custom DOM element
render(<MyApp />, {
  domId: 'custom-root',
  debug: true
})

// Immediate rendering (don't wait for DOMContentLoaded)
render(<MyApp />, {
  onReady: false
})

// Server-side hydration
render(<MyApp />, {
  hydrate: true,
  onReady: false
})

Advanced Context Configuration

import { makeContext } from '@owlmeans/web-client'

const context = makeContext({
  service: 'advanced-app',
  type: AppType.Frontend,
  layer: Layer.Service,
  ready: false,
  
  // Web-specific configuration
  services: {
    database: { 
      type: 'indexeddb',
      name: 'my-app-db'
    }
  },
  
  // Branding
  brand: {
    name: 'Advanced Web App',
    version: '2.1.0',
    logo: '/assets/logo.png'
  },
  
  // Trusted hosts for API calls
  trusted: [
    'api.myapp.com',
    'cdn.myapp.com'
  ],
  
  // Debug configuration
  debug: {
    all: process.env.NODE_ENV === 'development',
    routing: true,
    auth: true
  }
})

// Additional service registration
context.registerService(customWebService)

// Module registration with web-specific modules
context.registerModules([
  ...appModules,
  ...webSpecificModules
])

Integration with Internationalization

import { makeContext } from '@owlmeans/web-client'
import { addI18nApp } from '@owlmeans/i18n'

// Add web-specific translations
addI18nApp('en', 'web-common', {
  'button.close': 'Close',
  'message.loading': 'Loading...',
  'error.network': 'Network error occurred'
})

const context = makeContext(config)

// Access i18n through context
function I18nComponent() {
  const context = useContext()
  const i18nService = context.service('i18n')
  
  return (
    <div>
      <button>{i18nService.t('button.close')}</button>
    </div>
  )
}

Browser Compatibility

The package is designed for modern web browsers with support for:

• ES2020+: Modern JavaScript features
• IndexedDB: For local database storage
• LocalStorage: For simple key-value storage
• DOM API: Standard DOM manipulation
• Fetch API: For HTTP requests
• WebCrypto: For cryptographic operations (if used)

Performance Optimizations

1. Lazy Loading: Components and services are loaded on demand
2. Efficient Rendering: Optimized ReactDOM integration
3. Database Caching: Intelligent caching of web database operations
4. Bundle Splitting: Designed for code splitting compatibility
5. SSR Ready: Full server-side rendering support

Error Handling

Web-specific error handling and reporting:

import { OwlMeansError } from '@owlmeans/error'

// Web-specific error boundary
class WebErrorBoundary extends React.Component {
  componentDidCatch(error, errorInfo) {
    const context = this.props.context
    const debugService = context.debug()
    
    // Log web-specific error details
    debugService.error('web-error', 'Browser error', {
      error: error.message,
      stack: error.stack,
      userAgent: navigator.userAgent,
      url: window.location.href
    })
  }
}

Security Considerations

1. Trusted Hosts: Configure trusted hosts to prevent CSRF attacks
2. Authentication Storage: Secure token storage in browser
3. XSS Protection: Built-in protection against cross-site scripting
4. Content Security Policy: Compatible with CSP headers
5. HTTPS Only: Designed for secure HTTPS environments

Integration with Other Packages

Client Ecosystem Integration

// Authentication
import { makeAuthService } from '@owlmeans/client-auth'

// Resources
import { makeResourceService } from '@owlmeans/client-resource'

// Internationalization
import { makeI18nService } from '@owlmeans/client-i18n'

// Database
import { WebDbService } from '@owlmeans/web-db'

Build Tool Integration

// Webpack configuration
module.exports = {
  resolve: {
    alias: {
      '@owlmeans/web-client': path.resolve(__dirname, 'node_modules/@owlmeans/web-client')
    }
  }
}

// Vite configuration
export default {
  resolve: {
    alias: {
      '@owlmeans/web-client': path.resolve(__dirname, 'node_modules/@owlmeans/web-client')
    }
  }
}

Best Practices

1. Single Context: Use one web context per application
2. Proper Hydration: Use hydration mode for SSR applications
3. Error Boundaries: Implement web-specific error boundaries
4. Performance Monitoring: Monitor web-specific performance metrics
5. Responsive Design: Ensure proper responsive behavior
6. Accessibility: Follow web accessibility guidelines
7. SEO Optimization: Use SSR for better search engine optimization

Dependencies

This package depends on:

• @owlmeans/client - Base React client library
• @owlmeans/client-context - Client context management
• @owlmeans/client-auth - Client authentication
• @owlmeans/web-db - Web database integration
• @owlmeans/client-i18n - Client internationalization
• react - React library (peer dependency)
• react-dom - ReactDOM library (peer dependency)
• react-router-dom - React Router DOM (peer dependency)

Related Packages

• @owlmeans/client - Base React client library
• @owlmeans/native-client - React Native implementation
• @owlmeans/web-db - Web database implementation
• @owlmeans/client-auth - Client authentication
• @owlmeans/client-i18n - Client internationalization