NNextsAI Docs

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

NeedPath
Generate a tool with the assistantUse Nexts app-building capabilities, then review the source
Write your own frontendFollow the minimal example below
Database or background tasksUse a managed Python, Node, or native worker
Existing Flask, FastAPI, or Express UIIntegrate 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 typescript

Create this structure:

quick-note/
├─ .nexts-app/app.json
├─ index.html
├─ src/main.ts
├─ vite.config.mjs
└─ package.json

Bundle 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.1

Inspect the layout. A normal browser has no host connection, so this example keeps Save disabled and explains why.

Stop preview and build:

npx vite build

Prepare 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

CapabilityAPIsPermission or condition
LifecycledefineApp(), nexts.ready()Managed mini app window
Private storagenexts.storage.read/write/list/deletestorage.read / storage.write; string values
Modelsnexts.ai.chat/listModels/getQuotaStatusai.chat / ai.models.list
Agent sessionsnexts.agent.createSessionai.agent; shell requires system.shell separately
App backendnexts.backend.invokeDeclared and implemented app backend
Files and networknexts.filesystem, nexts.fetchFile permissions and allowedPaths, or network.fetch and domains
Windows and notificationsnexts.window, nexts.ui.showNotificationCurrent window; notifications need ui.notification
Account identitynexts.identity.getSessionidentity.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

SymptomCheck
SDK never becomes ready in a browserTest host integration inside Nexts; provide a browser fallback
Permission deniedManifest capability and scope; rebuild and reinstall changes
Blank installed pageBuilt entry, relative assets, and inline-script policy
Data missing after updateStable app ID and private storage
Backend fails to startRuntime 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.

On this page