React Apps

Shuuka supports React apps. The reference pattern is a built static bundle that Shuuka serves as uploaded files.

This rule is specific to React source code. For a simple or smart HTML app entry, Shuuka injects and initializes the SDK automatically, so you do not import the SDK manually in the main HTML page.

When To Use React

Use React when your app needs:

• richer local state and routing
• reusable UI components
• SDK hooks such as useShuuka() and useSettings()
• a larger app flow than one simple HTML file

If the app is small and mostly static, plain HTML and JavaScript are still fine.

Package Shape

Upload the production build output, not the source project.

my-react-app.zip
├── manifest.json
├── index.html
├── icon.svg
├── thumbnail.jpg
├── header.jpg
├── settings.json
├── settings-global.json
├── inputs.json
└── assets/
    ├── main.hash.js
    └── main.hash.css

Manifest Rules

For a React app, the manifest should usually look like this:

{
  "name": "My React App",
  "version": "1.0.0",
  "entry": "index.html",
  "supportedFrameworks": ["react"]
}

entry should point to the built HTML shell that loads your hashed assets.

Vite Build Rule

If you use Vite, generate relative asset paths. Shuuka serves the uploaded files as static assets and does not run your dev server.

Recommended pattern:

• base: ''
• output to dist/
• upload the built dist contents as the app package

Router Pattern

For in-app navigation, use a hash-based router so the app can switch views inside one uploaded entry file.

Import the provider explicitly:

import { HashRouter, Routes } from 'react-router-dom';
import { ShuukaProvider } from '@shuuka/sdk/index.sdk.js';

Common pattern:

<HashRouter>
  <ShuukaProvider autoResize={false}>
    <Routes>{/* ... */}</Routes>
  </ShuukaProvider>
</HashRouter>

SDK Hooks Used In React Apps

Hook	Use
useShuuka()	access sdk, uiState, and runtime context
useSettings()	read resolved values from settings.json
useShuukaFieldValues()	read and persist app field values
useShuukaReady()	wait for runtime readiness and use signed proxy helpers
useTranslations()	read translated app strings

For modals, bottom sheets, height management, and fullsize behavior, read App SDK UI Helpers.

Settings Page Pattern

React apps do not need a custom React App Global Settings page for normal configuration.

Use:

• settings.json for App Global Settings
• settings-global.json for secure App Global Settings
• inputs.json for collected submission fields

Shuuka renders those App Global Settings screens automatically. Your React app reads the saved values through the SDK.

App Instance Settings Note

App Instance Settings is the per-app sidebar configuration surface for one installed app instance.

In Shuuka, that surface is driven by groups and placeholders in simple and smart HTML apps. If you need that per-card sidebar behavior, read App Instance Settings.

Admin Page Pattern

If the owner needs a custom dashboard or workflow:

1. add admin_pages to manifest.json
2. point each page to an HTML entry in the uploaded bundle
3. bootstrap JavaScript or React from that entry
4. use window.__shuukaCtx and shkApi inside the page

Use admin_pages for workflows such as exports, moderation, analytics, or draw tools. Do not use them to replace normal schema-driven settings.

Builder Rule

Build locally, upload the exported bundle, and code against the SDK or shkApi. Do not rely on source-only files, dev-server routes, or raw internal platform endpoints.

When you package the app, ZIP the built output that contains manifest.json, index.html, the required images, schema files, and assets/. Do not ZIP only the source project.

If you build an extra nested HTML page inside the bundle, such as a custom modal frame, you can load the SDK there with the {{shuuka_sdk_src}} placeholder. That is an advanced case, not the default React app pattern.