@ramme-io/kernel

The core routing, rendering, and state engine for Ramme applications.

The Kernel is the brain of every Ramme app. It reads your declarative configuration files (app.manifest.ts and sitemap.ts), constructs the routing tree, and dynamically renders the correct components via the component registry — all without you writing a single line of routing code.

Architecture

The Kernel operates on three core inputs:

1. The Manifest (app.manifest.ts)

The global configuration for your application. Defines the app title, description, default theme, and high-level settings.

// src/config/app.manifest.ts
export const appManifest = {
  name: 'My Ramme App',
  description: 'A hardware-accelerated dashboard.',
  theme: 'midnight',
  version: '1.0.0',
};

2. The Sitemap (sitemap.ts)

The declarative routing and navigation structure. Each entry defines a page, its path, the component to render, and its position in the navigation hierarchy.

// src/config/sitemap.ts
export const sitemap = [
  {
    path: '/',
    label: 'Dashboard',
    icon: 'layout-dashboard',
    component: 'DashboardPage',
  },
  {
    path: '/settings',
    label: 'Settings',
    icon: 'settings',
    component: 'SettingsPage',
  },
];

3. The Component Registry (component-registry.tsx)

Maps the string-based component names from the sitemap to actual React components. This is what allows the Kernel to dynamically render your pages without hardcoded imports in the router.

// src/core/component-registry.tsx
import { lazy } from 'react';

export const componentRegistry: Record<string, React.LazyExoticComponent<any>> = {
  DashboardPage: lazy(() => import('../pages/DashboardPage')),
  SettingsPage: lazy(() => import('../pages/SettingsPage')),
};

How It Works

1. Boot — The Kernel reads app.manifest.ts and applies global settings (theme, metadata).
2. Parse — It ingests sitemap.ts and constructs a routing tree from the declarative page definitions.
3. Resolve — For each route, the Kernel looks up the component key in the component registry.
4. Render — The resolved React component is lazy-loaded and rendered inside the application shell.

The developer never writes <Route> elements manually. The Kernel handles all routing, code-splitting, and navigation generation from the sitemap alone.

Integration

In a standard Ramme app (generated by @ramme-io/create-app), the Kernel is pre-wired. If integrating manually:

import { ManifestProvider } from '@ramme-io/kernel';
import { appManifest } from './config/app.manifest';
import { sitemap } from './config/sitemap';
import { componentRegistry } from './core/component-registry';

export default function App() {
  return (
    <ManifestProvider
      manifest={appManifest}
      sitemap={sitemap}
      registry={componentRegistry}
    >
      {/* The Kernel renders your app here */}
    </ManifestProvider>
  );
}

Key Exports

• ManifestProvider — The root context provider that hydrates the app with manifest and sitemap data.
• useManifest() — Hook to access the current app manifest from any component.
• useDevice() — Hook for consuming normalized telemetry data from connected hardware.
• MqttProvider — Context provider for real-time MQTT/Ably device communication.

Documentation

For full documentation, visit https://ramme.io/docs.

License

MIT License — Copyright © 2026 Ramme Framework.

See LICENSE for details.