Mini App SDK Development
Build a mini app with Nexts App SDK, declare permissions, test storage, and prepare a release.
The official package, @nextsai/app-sdk, connects a mini app to host storage, models, windows, and app-owned backends.
Choose a development path
| Need | Path |
|---|---|
| Generate a tool with the assistant | Use Nexts app-building capabilities, then review the source |
| Write your own frontend | Follow the minimal example below |
| Database or background tasks | Use a managed Python, Node, or native worker |
| Existing Flask, FastAPI, or Express UI | Integrate it as a managed Web service |
Keep source in an independent project. Change source, rebuild, and install a new version when updating features.
1. Create a project
With Node.js and npm installed, run in a new empty directory:
npm init -y
npm install @nextsai/app-sdk@1.0.0
npm install --save-dev vite typescriptCreate this structure:
quick-note/
├─ .nexts-app/app.json
├─ index.html
├─ src/main.ts
├─ vite.config.mjs
└─ package.jsonBundle the SDK into production assets. Browser preview tests the UI; installation in Nexts tests host capabilities.
2. Declare identity and permissions
Write .nexts-app/app.json:
{
"schemaVersion": 2,
"id": "ai.nexts.quick-note",
"name": "Quick Note",
"version": "0.1.0",
"description": "Save a private note in Nexts.",
"author": { "name": "Your Name" },
"engine": { "nexts": ">=0.2.7", "appSdk": "^1.0.0" },
"kind": "app",
"views": [{
"id": "main",
"title": "Quick Note",
"surface": "window",
"entry": { "type": "web", "path": "dist/index.html" }
}],
"permissions": [
{ "key": "storage.read", "reason": "Load the saved note", "optional": false },
{ "key": "storage.write", "reason": "Save the edited note", "optional": false }
]
}Keep the permanent id across releases and increment version. The entry must exist in the build. A static UI needs no backend runtime declaration.
Permissions are objects, not strings. Installation grants declared SDK capabilities, and the host enforces that list. Declare only capabilities you use; newer APIs also require a compatible host.
3. Implement a saved note
index.html:
<!doctype html>
<html lang="en">
<head>
<meta charset="UTF-8" />
<meta name="viewport" content="width=device-width, initial-scale=1" />
<title>Quick Note</title>
</head>
<body>
<main>
<h1>Quick Note</h1>
<label for="note">Content</label>
<textarea id="note" rows="8"></textarea>
<button id="save" disabled>Save</button>
<p id="status" role="status">Open in Nexts to use storage.</p>
</main>
<script type="module" src="./src/main.ts"></script>
</body>
</html>src/main.ts:
import { defineApp, nexts } from '@nextsai/app-sdk';
const note = document.querySelector<HTMLTextAreaElement>('#note')!;
const save = document.querySelector<HTMLButtonElement>('#save')!;
const status = document.querySelector<HTMLParagraphElement>('#status')!;
defineApp({ activate() {}, deactivate() {} });
void nexts.ready().then(async () => {
note.value = (await nexts.storage.read('note')) ?? '';
save.disabled = false;
status.textContent = 'Connected to Nexts';
}).catch((error: unknown) => {
status.textContent = String(error);
});
save.addEventListener('click', async () => {
save.disabled = true;
try {
await nexts.storage.write('note', note.value);
status.textContent = 'Saved';
} catch (error) {
status.textContent = String(error);
} finally {
save.disabled = false;
}
});vite.config.mjs:
import { defineConfig } from 'vite';
export default defineConfig({ base: './' });Keep executable scripts in external files. Relative asset paths support the managed application window.
4. Preview, build, and install
npx vite --host 127.0.0.1Inspect the layout. A normal browser has no host connection, so this example keeps Save disabled and explains why.
Stop preview and build:
npx vite buildPrepare an installation directory containing only:
release/
├─ .nexts-app/app.json
└─ dist/
├─ index.html
└─ assets/...Choose release under Apps → Add → Install from local directory. Open, enter a note, save, close, and reopen to verify persistence. Exclude node_modules, secrets, and development data.
SDK capabilities
| Capability | APIs | Permission or condition |
|---|---|---|
| Lifecycle | defineApp(), nexts.ready() | Managed mini app window |
| Private storage | nexts.storage.read/write/list/delete | storage.read / storage.write; string values |
| Models | nexts.ai.chat/listModels/getQuotaStatus | ai.chat / ai.models.list |
| Agent sessions | nexts.agent.createSession | ai.agent; shell requires system.shell separately |
| App backend | nexts.backend.invoke | Declared and implemented app backend |
| Files and network | nexts.filesystem, nexts.fetch | File permissions and allowedPaths, or network.fetch and domains |
| Windows and notifications | nexts.window, nexts.ui.showNotification | Current window; notifications need ui.notification |
| Account identity | nexts.identity.getSession | identity.basic |
Put network domains in permission meta.domains and file scopes in meta.allowedPaths. Use SDK methods for host capabilities, not direct Tauri calls, private host ports, or host databases.
Backend and Agent integration
Continue with supported runtime forms, backend and Agent integration, and native backend development. Rust/Go/C++ backends use the native engine of managed-worker and require a host build containing that feature.
Use managed-worker for SQLite, background work, full Python/Node dependencies, or a compiled native business core. Existing local Web servers can use managed-web, bind to loopback, and read the host-assigned NEXTS_APP_PORT.
Call your implemented methods with APIs such as nexts.backend.invoke('notes.list', {}). Keep records in the app-private data volume. To expose business actions to the main assistant, declare agent.integration and agentIntegration.actions, including names, input schemas, and read/write impact; validate them in the same backend business layer.
nexts.agent.createSession() creates an app-private Agent session. It does not inherit main-chat connected apps, global MCP, skills, or memory. A compatible host also supports nexts.ui.openConversation() for handing a task to the main chat.
Package, update, and submit
In Nexts, ask the assistant to use validate_nexts_app, build_nexts_app, and package_nexts_app. These are Nexts tool names, not terminal commands.
Packaging produces a .zip, SHA-256 checksum, and .zip.sbom.json dependency inventory. Verify permissions, storage, and upgrade persistence locally. Then use Apps → My submissions → Submit to marketplace, select the package and SBOM, and submit for review. Packaging does not publish the app.
Standalone templates may provide npm run package; follow their instructions. Use a new version for every resubmission.
Troubleshooting
| Symptom | Check |
|---|---|
| SDK never becomes ready in a browser | Test host integration inside Nexts; provide a browser fallback |
| Permission denied | Manifest capability and scope; rebuild and reinstall changes |
| Blank installed page | Built entry, relative assets, and inline-script policy |
| Data missing after update | Stable app ID and private storage |
| Backend fails to start | Runtime type, entry, and bundled production dependencies |
Package: Nexts App SDK. Adapt your UI to desktop, phone, and tablet sizes; ordinary H5 pages do not automatically receive desktop SDK or local-backend capabilities.