How to Add a Feature to PraisonAIUI

How to Add a Feature to PraisonAIUIThis guide explains every way a user can extend PraisonAIUI — and which approach fits your use case.Extension Points at a Glance| I want to add… | Use | Side | Effort ||----------------|-----|------|--------|| A new dashboard page | @aiui.page() | Server | 5 lines || A form that saves data | aiui.form_action() + @aiui.register_page_action() | Both | 15 lines || A brand-new UI component type | window.aiui.registerComponent() + dict type | Both | 20 lines || A page rendered entirely in the browser | window.aiui.registerView() | Client | 10 lines || Ship client-side JS from Python | aiui.set_custom_js(path) | Server | 1 line || A typed contract for a component | aiui.register_component_schema(type, schema) | Server | 5 lines || A custom theme | aiui.register_theme() | Server | 1 line || A new AI backend | Subclass aiui.BaseProvider | Server | ~50 lines || A whole new feature module (routes, state) | Subclass BaseFeatureProtocol + register_feature() | Server | ~100 lines || Persistence backend | Subclass aiui.BaseDataStore | Server | ~50 lines |1. Add a new pageGoal: Show a new page in the sidebar with custom content.What happens:1. The page is registered in the server's page registry.2. It appears in the sidebar at /api/pages.3. When the user clicks it, the frontend fetches /api/pages/analytics/data.4. Your handler returns a dict; aiui.layout() wraps it in {"_components": [...]}.5. dashboard.js loops over _components and calls renderComponent(comp) on each.See Dashboard for the full @aiui.page() signature.---2. Add an interactive formGoal: Let users submit data from the UI back to your Python code.What happens:1. The form renders with all inputs.2. On submit, the frontend POSTs to /api/pages/contact/action.3. The server invokes handle_contact(data) with the form values keyed by label.4. The returned dict is sent back to the browser as JSON.> Note: Input labels become dict keys. Use distinct labels per input.---3. Add a custom component typeGoal: Add a new UI widget that doesn't exist in the 48 built-ins.Step 1 — Python side: return a dict with your new typeIf you stop here, the component renders as formatted JSON (graceful fallback).Step 2 — Client side: register a rendererPut this in a plugin.js file (or paste into DevTools Console):What happens:1. renderComponent(comp) checks COMPONENT_REGISTRY[comp.type] before the built-in switch.2. Your renderer takes priority and returns a DOM element.Auto-load `plugin.js` from PythonUse aiui.set_custom_js(path) to ship client-side extensions directly fromyour app:The script runs after the plugin loader, so window.aiui.registerViewand window.aiui.registerComponent are ready when it executes. No DevToolsworkaround needed.---4. Add a client-only pageGoal: A page rendered entirely in the browser — no server round-trip on navigation.Still register a placeholder page in Python so it appears in the sidebar:What happens:1. registerView takes priority over the built-in + server-side rendering.2. Navigation calls your render(container) function.3. When the user navigates away, your cleanup() function runs.---5. Register a custom themeSee CSS Architecture for all variables.---6. Add a new AI providerSee Providers.---7. Add a feature module (advanced)Features live in praisonaiui/features/*.py and implement BaseFeatureProtocol:See Protocol Architecture.---Is This the Best Approach?Strengths ✅Clean separation — Python returns dicts, client renders DOM. You can mix and match server/client work per-feature.Graceful degradation — Unknown component types render as JSON (no crashes).Zero build step for Python users — No webpack/TS compile required for server-side pages.Single source of truth — Every feature has a protocol ABC.Hot-swap friendly — window.aiui.registerView/Component updates live without server restart.Previously reported gaps — all closed ✅| Gap | Resolution ||-----|------------|| No aiui.set_custom_js(path) | Implemented — serves the file at /custom.js and injects a <script> tag after the plugin loader. Unit tests: tests/unit/test_custom_js.py (10 tests). || form_action uses input labels as keys | Implemented — every form input now accepts an optional name= kwarg that becomes the submit-key. Tests: tests/unit/test_form_input_names.py (18 tests). || No typed Python ⇄ JS contract | Implemented — aiui.register_component_schema(type, schema) + GET /api/components/schemas. Built-in schemas are auto-derived from ui.py signatures. Tests: tests/unit/test_component_schemas.py (9 tests). || /api/features cold-start slow | Mitigated — info() calls are parallelized via asyncio.gather. Warm calls are now instant; cold starts are dominated by LiteLLM import (out of scope). || pygments 2.20 mkdocs build crash on providers.md | Fixed — docs_hooks.py patches pymdownx.BlockHtmlFormatter.__init__ to coerce filename=None → "". |When NOT to use this approachYou need a full SPA with routing: Use the Next.js adapter or scaffold a React project with aiui init --frontend.Your UI needs TypeScript types: Use the TypeScript SDK (@praisonaiui/runtime).You need server-sent events beyond chat: Extend BaseFeatureProtocol with a WebSocket route.---Checklist for a New Feature[ ] Decide: is it a page, a component, or a backend module?[ ] Write the Python side first (returns a dict / routes).[ ] If you added a new component type: implement the JS renderer.[ ] Write a unit test (see tests/unit/test_form_action.py as an example).[ ] Add a runnable example under examples/python/.[ ] Update the docs under docs/features/ or docs/api/.[ ] Run mkdocs build --strict.[ ] Run pytest tests/unit -v.