📦 Modular Structure

OnigiriJS is built as a modular framework, allowing you to load only the features you need for optimal performance and smaller bundle sizes.

Why Modular?

Available Modules

Core Module (Required)

// onigiri-core.js - ~8KB
// - DOM manipulation
// - Element selection
// - Basic utilities
// - Plugin system

<script src="onigiri-core.js"></script>

Events Module

// onigiri-events.js - ~3KB
// - Event emitter
// - Namespaced events
// - Once events
// - Event delegation

<script src="onigiri-core.js"></script>
<script src="onigiri-events.js"></script>

Components Module

// onigiri-components.js - ~5KB
// - Reactive components
// - Lifecycle hooks
// - Computed properties
// - Data watchers

<script src="onigiri-core.js"></script>
<script src="onigiri-events.js"></script>
<script src="onigiri-components.js"></script>

Security Module

// onigiri-security.js - ~4KB
// - CSRF protection
// - CSP support
// - XSS prevention
// - URL validation

<script src="onigiri-core.js"></script>
<script src="onigiri-security.js"></script>

AJAX Module

// onigiri-ajax.js - ~2KB
// - AJAX requests
// - Auto-CSRF
// - Promise-based
// - Convenience methods

<script src="onigiri-core.js"></script>
<script src="onigiri-security.js"></script>
<script src="onigiri-ajax.js"></script>

Storage Module

// onigiri-storage.js - ~3KB
// - Local storage
// - Session storage
// - Expiration support
// - Prefix management

<script src="onigiri-core.js"></script>
<script src="onigiri-storage.js"></script>

PJAX Module

// onigiri-pjax.js - ~4KB
// - PJAX navigation
// - Browser history
// - Response caching
// - Event hooks

<script src="onigiri-core.js"></script>
<script src="onigiri-security.js"></script>
<script src="onigiri-pjax.js"></script>

Validation Module

// onigiri-validation.js - ~3KB
// - Form validation
// - Built-in rules
// - Custom rules
// - Real-time validation

<script src="onigiri-core.js"></script>
<script src="onigiri-validation.js"></script>

Animation Module

// onigiri-animate.js - ~2KB
// - Fade in/out
// - Slide up/down
// - Smooth animations
// - Callback support

<script src="onigiri-core.js"></script>
<script src="onigiri-animate.js"></script>

HumHub Module

// onigiri-humhub.js - ~2KB
// - HumHub integration
// - Auto PJAX remounting
// - Module helper

<script src="onigiri-core.js"></script>
<script src="onigiri-events.js"></script>
<script src="onigiri-components.js"></script>
<script src="onigiri-humhub.js"></script>

Router Module

// onigiri-router.js - ~7KB
// - History API (pushState) routing
// - Optional PJAX-style partial rendering
// - Route middleware
// - Same-origin enforcement on navigation/forms

<script src="onigiri-core.js"></script>
<script src="onigiri-security.js"></script>
<script src="onigiri-router.js"></script>

Translation Module (i18n)

// onigiri-translation.js - ~13KB
// - Locale loading (JSON, or a PHP array export)
// - Pluralization
// - Page-wide data-i18n translation
// - Import/export helpers

<script src="onigiri-core.js"></script>
<script src="onigiri-translation.js"></script>

Mode Module (Theme)

// onigiri-mode.js - ~11KB
// - Light/dark mode with system sync
// - Persistent, transitioned theme switching
// - Nested class/selector config

<script src="onigiri-core.js"></script>
<script src="onigiri-mode.js"></script>

Plugins Module

// onigiri-plugins.js - ~12KB
// - Onigiri.use() plugin registration
// - Bundled storage/router/animation/security/cookies plugins
// - Defers to a dedicated module of the same name if one is already loaded

<script src="onigiri-core.js"></script>
<script src="onigiri-plugins.js"></script>

Portal Module

// onigiri-portal.js - ~13KB
// - Modals, toasts, and tooltips
// - Focus trapping

<script src="onigiri-core.js"></script>
<script src="onigiri-portal.js"></script>

Realtime Module (SSE)

// onigiri-realtime.js - ~10KB
// - Server-Sent Events (EventSource) wrapper
// - Automatic reconnection with heartbeat monitoring
// - liveCounter / liveList / liveBadge UI helpers

<script src="onigiri-core.js"></script>
<script src="onigiri-realtime.js"></script>

Loading Strategies

Minimal Setup (DOM Only)

<!-- Just 8KB for basic DOM manipulation -->
<script src="onigiri-core.js"></script>

<script>
// DOM manipulation only
O('.button').on('click', function() {
    O(this).addClass('active');
});
</script>

Basic Reactive App

<!-- ~16KB for reactive components -->
<script src="onigiri-core.js"></script>
<script src="onigiri-events.js"></script>
<script src="onigiri-components.js"></script>

<script>
const app = new Onigiri.Component({
    data: { count: 0 },
    methods: {
        increment() { this.count++; }
    }
});
</script>

Full-Featured App

<!-- ~30KB for complete feature set -->
<script src="onigiri-core.js"></script>
<script src="onigiri-events.js"></script>
<script src="onigiri-components.js"></script>
<script src="onigiri-security.js"></script>
<script src="onigiri-ajax.js"></script>
<script src="onigiri-storage.js"></script>
<script src="onigiri-pjax.js"></script>
<script src="onigiri-validation.js"></script>
<script src="onigiri-animate.js"></script>

HumHub Module

<!-- Optimized for HumHub -->
<script src="onigiri-core.js"></script>
<script src="onigiri-events.js"></script>
<script src="onigiri-components.js"></script>
<script src="onigiri-security.js"></script>
<script src="onigiri-ajax.js"></script>
<script src="onigiri-storage.js"></script>
<script src="onigiri-humhub.js"></script>

Module Dependencies

// Dependency tree
onigiri-core.js (required, no dependencies)
├── onigiri-events.js (depends on: core)
│   └── onigiri-components.js (depends on: core, events)
│       └── onigiri-humhub.js (depends on: core, events, components)
├── onigiri-security.js (depends on: core)
│   ├── onigiri-ajax.js (depends on: core, security)
│   ├── onigiri-pjax.js (depends on: core, security)
│   └── onigiri-router.js (depends on: core, security)
├── onigiri-storage.js (depends on: core)
├── onigiri-translation.js (depends on: core)
├── onigiri-mode.js (depends on: core)
├── onigiri-portal.js (depends on: core)
├── onigiri-realtime.js (depends on: core; optionally uses security for output escaping)
├── onigiri-plugins.js (depends on: core)
├── onigiri-validation.js (depends on: core)
└── onigiri-animate.js (depends on: core)

Checking Loaded Modules

// Check which modules are loaded
console.log(Onigiri.modules);
// { core: true, events: true, components: true, ... }

// Check specific module
if (Onigiri.modules.security) {
    // Security module is loaded
    Onigiri.security.init();
}

if (Onigiri.modules.pjax) {
    // PJAX module is loaded
    Onigiri.pjax.init();
}

Conditional Loading

Load Modules Based on Features

<!-- Core always loaded -->
<script src="onigiri-core.js"></script>

<?php if ($needsComponents): ?>
    <script src="onigiri-events.js"></script>
    <script src="onigiri-components.js"></script>
<?php endif; ?>

<?php if ($needsAjax): ?>
    <script src="onigiri-security.js"></script>
    <script src="onigiri-ajax.js"></script>
<?php endif; ?>

<?php if ($needsValidation): ?>
    <script src="onigiri-validation.js"></script>
<?php endif; ?>

Dynamic Module Loading

// Load module dynamically
async function loadModule(moduleName) {
    return new Promise((resolve, reject) => {
        const script = document.createElement('script');
        script.src = \`onigiri-\${moduleName}.js\`;
        script.onload = resolve;
        script.onerror = reject;
        document.head.appendChild(script);
    });
}

// Usage
async function enableValidation() {
    if (!Onigiri.modules.validation) {
        await loadModule('validation');
        console.log('🍙 Validation module loaded!');
    }
    
    // Now use validation
    const result = O('#form').validate(rules);
}

Build Your Own Bundle

Custom Build Script

// build-custom.js
const fs = require('fs');

const modules = [
    'onigiri-core.js',
    'onigiri-events.js',
    'onigiri-components.js',
    'onigiri-security.js',
    'onigiri-ajax.js'
];

let combined = '';

modules.forEach(module => {
    combined += fs.readFileSync(module, 'utf8');
    combined += '\n\n';
});

fs.writeFileSync('onigiri.custom.js', combined);
console.log('🍙 Custom bundle created!');

Concatenate Modules

#!/bin/bash
# build.sh

# Create custom bundle
cat onigiri-core.js \
    onigiri-events.js \
    onigiri-components.js \
    onigiri-security.js \
    onigiri-ajax.js \
    onigiri-storage.js \
    > onigiri.bundle.js

echo "🍙 Bundle created: onigiri.bundle.js"

Module Size Comparison

// Approximate sizes (minified)
onigiri-core.js        ~8KB  ████████
onigiri-events.js      ~3KB  ███
onigiri-components.js  ~5KB  █████
onigiri-security.js    ~4KB  ████
onigiri-ajax.js        ~2KB  ██
onigiri-storage.js     ~3KB  ███
onigiri-pjax.js        ~4KB  ████
onigiri-router.js      ~7KB  ███████
onigiri-translation.js ~13KB █████████████
onigiri-mode.js        ~11KB ███████████
onigiri-portal.js      ~13KB █████████████
onigiri-plugins.js     ~12KB ████████████
onigiri-realtime.js    ~10KB ██████████
onigiri-validation.js  ~3KB  ███
onigiri-animate.js     ~2KB  ██
onigiri-humhub.js      ~2KB  ██

Total (all modules):   ~102KB ████████████████████████████████████

Compare to:
jQuery:                ~30KB
Vue.js:                ~33KB
React + ReactDOM:      ~42KB

OnigiriJS is still lighter than most single-purpose frameworks when you load only what you need - a landing page using just core + animate is ~10KB, well under any of the comparisons above.

Use Case Examples

Simple Landing Page

<!-- Only need DOM + Animations (10KB) -->
<script src="onigiri-core.js"></script>
<script src="onigiri-animate.js"></script>

<script>
O('.hero').fadeIn(500);
O('.cta-button').on('click', () => {
    O('.signup-form').slideDown(300);
});
</script>

Contact Form

<!-- DOM + Security + AJAX + Validation (17KB) -->
<script src="onigiri-core.js"></script>
<script src="onigiri-security.js"></script>
<script src="onigiri-ajax.js"></script>
<script src="onigiri-validation.js"></script>

<script>
Onigiri.security.init();

O('#contact-form').on('submit', async (e) => {
    e.preventDefault();
    
    const result = O(e.target).validate(rules);
    if (result.isValid) {
        await Onigiri.post('/api/contact', formData);
    }
});
</script>

Full SPA

<!-- Everything except HumHub (32KB) -->
<script src="onigiri-core.js"></script>
<script src="onigiri-events.js"></script>
<script src="onigiri-components.js"></script>
<script src="onigiri-security.js"></script>
<script src="onigiri-ajax.js"></script>
<script src="onigiri-storage.js"></script>
<script src="onigiri-pjax.js"></script>
<script src="onigiri-validation.js"></script>
<script src="onigiri-animate.js"></script>

HumHub Widget

<!-- HumHub-optimized (24KB) -->
<script src="onigiri-core.js"></script>
<script src="onigiri-events.js"></script>
<script src="onigiri-components.js"></script>
<script src="onigiri-security.js"></script>
<script src="onigiri-ajax.js"></script>
<script src="onigiri-storage.js"></script>
<script src="onigiri-humhub.js"></script>

Module Best Practices

• Always load core.js first
• Respect module dependencies
• Only load modules you actually use
• Check Onigiri.modules before using features
• Consider creating custom bundles for production
• Test with only required modules loaded
• Document which modules your code needs
• Use conditional loading for optional features

Future Modules

Modules planned for future releases:

• onigiri-state.js - Shared global & scoped state management
• onigiri-directives.js - Declarative DOM bindings (o-show, o-model, etc.)
• onigiri-resource.js - REST-style data models over AJAX
• onigiri-observe.js - Intersection & Mutation observer helpers
• onigiri-websocket.js - Full bidirectional WebSocket support (see Realtime for one-way, SSE-based live updates in the meantime)
• onigiri-charts.js - Data visualization
• onigiri-drag.js - Drag and drop

Creating Custom Modules

// onigiri.custom.js - Custom module template
(function(Onigiri) {
    'use strict';

    if (!Onigiri) {
        throw new Error('OnigiriJS core not found');
    }

    // Your custom functionality
    Onigiri.customFeature = {
        init: function() {
            console.log('🍙 Custom feature initialized');
        },
        
        doSomething: function() {
            // Your code here
        }
    };

    // Register module
    Onigiri.modules.custom = true;

})(typeof Onigiri !== 'undefined' ? Onigiri : null);