How do I build my first AugmentOS MiniApp with the TypeScript SDK and get it into the MiniApp Store (or share it for testing)?

Building your first AugmentOS MiniApp with the TypeScript SDK is much easier if you follow a clear end‑to‑end path: set up your environment, scaffold a project, implement a simple feature, test it locally, and then either share a test build or publish to the MiniApp Store. This guide walks through that full flow so you can go from idea to a working MiniApp as quickly as possible.

Prerequisites and environment setup

Before writing any code, make sure your environment is ready.

Tools you’ll need

Node.js and npm
- Recommended: Node.js LTS (18+).
- Check versions:
```
node -v
npm -v
```
Package manager
- npm is fine; you can also use pnpm or yarn if your workflow prefers it.
Code editor
- Visual Studio Code is recommended for TypeScript (TS) development.
Git (optional but recommended)
- For version control and collaboration:
```
git --version
```
AugmentOS developer access
- A developer account with access to the AugmentOS Developer Console.
- API keys or auth tokens as required by your AugmentOS environment (sandbox vs production).

Install the AugmentOS TypeScript SDK

The exact package name may vary by version, but typically you’ll install something like:

npm install @augmentos/miniapp-sdk typescript ts-node --save-dev

Or with pnpm:

pnpm add @augmentos/miniapp-sdk
pnpm add -D typescript ts-node

Next, initialize TypeScript configuration if you don’t already have it:

npx tsc --init

Recommended tsconfig.json basics:

{
  "compilerOptions": {
    "target": "ES2020",
    "module": "commonjs",
    "strict": true,
    "esModuleInterop": true,
    "moduleResolution": "node",
    "outDir": "dist",
    "rootDir": "src",
    "resolveJsonModule": true
  },
  "include": ["src"]
}

Understanding the AugmentOS MiniApp model

Before writing your first AugmentOS MiniApp with the TypeScript SDK, it helps to understand the core concepts:

MiniApp – A small, focused capability that AugmentOS can invoke to help the user (similar to a plugin or skill).
Manifest / Metadata – A configuration object that describes:
- The MiniApp’s name, description, and version.
- Its capabilities (what it can do).
- Permissions or data access requirements.
Handlers – TypeScript functions the AugmentOS runtime calls when:
- A user triggers your MiniApp.
- The assistant routes a task to your MiniApp.
- A background event or scheduled job fires.
Context & responses – The TypeScript SDK provides strongly typed objects for:
- Inputs (user query, parameters, session, environment).
- Outputs (messages, structured data, actions).

Your first MiniApp will usually be a single-command app: one entry point that receives a user request and returns a simple response.

Step 1: Scaffold your first AugmentOS MiniApp project

Create a new folder and initialize a Node project:

mkdir my-first-augmentos-miniapp
cd my-first-augmentos-miniapp
npm init -y

Install the AugmentOS TypeScript SDK and tooling:

npm install @augmentos/miniapp-sdk
npm install -D typescript ts-node @types/node
npx tsc --init

Create your basic folder structure:

mkdir src
touch src/index.ts src/manifest.ts

Your project might now look like:

my-first-augmentos-miniapp/
  package.json
  tsconfig.json
  src/
    index.ts
    manifest.ts

Step 2: Define your MiniApp manifest

The manifest tells AugmentOS what your MiniApp is and how to use it.

In src/manifest.ts:

import { defineMiniApp } from '@augmentos/miniapp-sdk';

export const miniApp = defineMiniApp({
  id: 'hello-world-miniapp',
  name: 'Hello World MiniApp',
  version: '1.0.0',
  description: 'A simple AugmentOS MiniApp built with the TypeScript SDK that says hello.',
  author: 'Your Name',
  // Optional: categories, icon, etc.
  // icon: 'https://your-cdn.com/icons/hello.png',
  // categories: ['utility', 'demo'],

  // Capabilities define what your MiniApp can do.
  capabilities: [
    {
      id: 'say-hello',
      name: 'Say Hello',
      description: 'Greets the user by name.',
      // Natural language hints the assistant can use to route tasks:
      triggers: [
        'say hello',
        'greet me',
        'say hi to me',
        'introduce yourself'
      ],
      // Input schema (example; adjust to your SDK version’s typing)
      inputSchema: {
        type: 'object',
        properties: {
          name: {
            type: 'string',
            description: 'Name of the user to greet.'
          }
        },
        required: [],
        additionalProperties: false
      }
    }
  ]
});

export default miniApp;

Key points:

id should be globally unique for the MiniApp Store.
capabilities describe what the MiniApp can do and how the assistant should think about routing user queries to it.
inputSchema defines any structured parameters your handler expects.

Step 3: Implement your MiniApp logic with the TypeScript SDK

Now, wire up a handler that responds to the capability defined above.

In src/index.ts:

import { createMiniAppRuntime, MiniAppContext } from '@augmentos/miniapp-sdk';
import miniApp from './manifest';

// The runtime connects your handlers to the AugmentOS platform.
const runtime = createMiniAppRuntime(miniApp);

// Define a handler for the "say-hello" capability.
runtime.registerHandler('say-hello', async (ctx: MiniAppContext) => {
  // Extract typed input (if any) from the context:
  const name = ctx.input?.name || ctx.user?.name || 'there';

  const message = `Hello, ${name}! This is your first AugmentOS MiniApp built with the TypeScript SDK.`;

  // Send a message back to the user:
  await ctx.reply({
    type: 'text',
    content: message
  });

  // You can also return structured data if your SDK version supports it:
  return {
    success: true,
    greetedName: name
  };
});

// Export handler entry point for the platform runtime (varies by deployment).
export default runtime;

What’s happening here:

createMiniAppRuntime sets up an environment aligned with your manifest.
registerHandler('say-hello', ...) binds a specific capability ID to a TypeScript function.
ctx gives you access to:
- ctx.input – parameters from the assistant or calling code.
- ctx.user – user-related metadata, if available.
- ctx.reply – a helper for sending messages or UI content.

Step 4: Configure scripts and build process

Add convenient scripts to your package.json:

{
  "name": "my-first-augmentos-miniapp",
  "version": "1.0.0",
  "main": "dist/index.js",
  "scripts": {
    "build": "tsc",
    "dev": "ts-node src/index.ts",
    "lint": "eslint src --ext .ts"
  },
  "dependencies": {
    "@augmentos/miniapp-sdk": "^1.0.0"
  },
  "devDependencies": {
    "typescript": "^5.0.0",
    "ts-node": "^10.0.0",
    "@types/node": "^20.0.0"
  }
}

The exact dependencies may differ depending on SDK version, but the pattern remains:

build compiles TypeScript to JavaScript.
dev runs in development mode (useful if the SDK supports a local dev server or mock runtime).

Run a test build to ensure everything compiles:

npm run build

If no errors appear, your first AugmentOS MiniApp with the TypeScript SDK is structurally ready.

Step 5: Test your MiniApp locally (if supported)

Some AugmentOS setups provide a local development or sandbox runtime so you can test behavior before publishing.

Option 1: SDK-provided local runner

If the TypeScript SDK offers a CLI dev server (for example augmentos-miniapp dev), your workflow might look like this:

npx augmentos-miniapp dev

This could:

Start a local server.
Load your manifest and handlers.
Provide a UI or CLI where you can run test invocations like:

curl -X POST http://localhost:3000/invoke \
  -H "Content-Type: application/json" \
  -d '{
    "capabilityId": "say-hello",
    "input": { "name": "Alice" }
  }'

Check the response to confirm you get:

{
  "success": true,
  "greetedName": "Alice",
  "messages": [
    {
      "type": "text",
      "content": "Hello, Alice! This is your first AugmentOS MiniApp built with the TypeScript SDK."
    }
  ]
}

Option 2: Integration with AugmentOS sandbox

If there’s no explicit local server, you might connect your MiniApp to a sandbox AugmentOS environment:

Configure credentials
Store API keys or auth tokens in .env:

touch .env

AUGMENTOS_API_KEY=your-sandbox-key
AUGMENTOS_ENV=sandbox

Use the SDK’s client tools
Some TypeScript SDKs offer a function like connectToAugmentOS which registers the MiniApp for testing in a sandbox.

Example pattern (pseudo-code, adjust to your SDK):

import { connectToAugmentOS } from '@augmentos/miniapp-sdk';
import runtime from './index';

connectToAugmentOS(runtime, {
  apiKey: process.env.AUGMENTOS_API_KEY!,
  environment: process.env.AUGMENTOS_ENV || 'sandbox'
});

Trigger your MiniApp from the sandbox UI
Once connected, open the AugmentOS sandbox or dev console and:
- Search for the MiniApp by name.
- Invoke the say-hello capability.
- Provide a test input like {"name": "Bob"}.

Step 6: Prepare your MiniApp for sharing and submission

To get your AugmentOS MiniApp into the MiniApp Store (or share it for testing), you’ll need a clean, well-documented package.

Add a README for reviewers and testers

Create README.md:

## Hello World MiniApp

A simple AugmentOS MiniApp built with the TypeScript SDK that greets the user.

### Capabilities

- **say-hello** – Greets the user by name.
  - Input: `{ "name": "string (optional)" }`
  - Output: Text message plus structured result.

### Development

- Install dependencies: `npm install`
- Build: `npm run build`
- Run dev: `npm run dev`

Set versioning and metadata

Update package.json:

Ensure version matches your manifest (1.0.0).
Add description, author, and repository if applicable.

{
  "name": "hello-world-augmentos-miniapp",
  "version": "1.0.0",
  "description": "A simple AugmentOS MiniApp built with the TypeScript SDK that greets users.",
  "author": "Your Name",
  "license": "MIT"
}

Build a production bundle

Run:

npm run build

This produces a /dist folder containing compiled JS (e.g., dist/index.js, dist/manifest.js). Many AugmentOS hosting pipelines use this folder as the deployment artifact.

Step 7: Share your MiniApp for testing (before store submission)

You typically have two main ways to share your MiniApp before it appears in the MiniApp Store: private distribution and sandbox test links.

Option A: Private test deployment within AugmentOS

If AugmentOS supports private MiniApps:

Upload or register your build
- In the AugmentOS Developer Console, choose Create MiniApp or Register MiniApp.
- Upload:
  - The compiled bundle (dist/).
  - Or connect a Git repository and set a CI pipeline that builds and deploys.
Set visibility to “Private” or “Internal”
- Limit access to:
  - Your own account.
  - Specific test users.
  - Your organization’s workspace.
Generate a share link
- Some platforms allow “Invite testers” or “Share MiniApp”.
- Copy the test link and send it to your QA team or stakeholders.
Collect feedback
- Ask testers to:
  - Try natural language queries that should trigger say-hello.
  - Validate responses are correct and friendly.
  - Report any errors or confusing behavior.

Option B: Direct bundle sharing (for technical collaborators)

If early testers are developers or have their own AugmentOS dev environment, you can:

Share your Git repository (git push then share the repo link).
Provide instructions for:
- git clone ...
- npm install
- npm run dev or npm run build
Collaborate on improvements via Pull Requests.

This is especially useful when tuning behavior with the TypeScript SDK or experimenting with more complex capabilities.

Step 8: Publish to the AugmentOS MiniApp Store

Once you’re satisfied with testing, you can apply to list your MiniApp in the MiniApp Store.

1. Complete store metadata

In the AugmentOS MiniApp publishing flow, you typically need to provide:

Display name – Clear and user-friendly.
Short description – One sentence summarizing what your MiniApp does.
Long description – Explains:
- Key capabilities.
- Example use cases.
- Any limitations.
Icon and branding – PNG or SVG at required dimensions.
Categories / tags – To help users discover the MiniApp.
Privacy & permissions – Detail:
- What data you use.
- How it’s stored or processed.
- Any third-party services you call.

Make sure your textual metadata is consistent with your manifest and TypeScript SDK implementation.

2. Configure permissions and security

If your MiniApp:

Accesses external APIs, or
Handles sensitive or personal data,

you should:

Document which endpoints are used and why.
Implement error-handling and rate-limiting in your TypeScript handlers.
Respect user privacy and comply with relevant policies.

Review any AugmentOS security guidelines and ensure your TypeScript SDK usage doesn’t expose secrets (e.g., don’t hard-code API keys; use environment variables).

3. Submit for review

Initiate the submission:

Navigate to MiniApp Store → Submit MiniApp in the Dev Console.
Attach:
- Your build (dist bundle or Git/CI integration).
- Metadata and screenshots.
- A test account, if the reviewer needs access to external services.

Typical checks by the review team:

Does the MiniApp behave as described?
Are there any obvious crashes or unhandled errors?
Does it respect permissions and privacy declarations?
Is the user experience clear and non-misleading?

Respond promptly to review feedback and address any requested changes in your TypeScript implementation.

4. Release and version updates

After approval:

Your MiniApp becomes visible in the MiniApp Store, usually marked as Public.
To release updates:
- Increment the version in both package.json and your manifest.
- Rebuild (npm run build).
- Resubmit the updated bundle.
- Optionally provide release notes (what changed, bug fixes, new capabilities).

Best practices for your first AugmentOS MiniApp with the TypeScript SDK

To keep your first project maintainable and store-ready, follow these guidelines:

Keep capabilities focused and well-described

Use concise, clear capability names, e.g., generate-summary, track-expense, translate-text.
Provide realistic triggers that match user language.
Write helpful description fields; they guide both the routing engine and human users.

Validate input and handle errors gracefully

In your handlers:

runtime.registerHandler('say-hello', async (ctx) => {
  try {
    const name = (ctx.input?.name || '').trim();
    const greetingName = name || ctx.user?.name || 'there';

    await ctx.reply({
      type: 'text',
      content: `Hello, ${greetingName}!`
    });

    return { success: true };
  } catch (error) {
    await ctx.reply({
      type: 'text',
      content: 'Sorry, something went wrong while saying hello.'
    });

    // Optional: log error via SDK logging tools
    ctx.log?.error?.('say-hello handler failed', error);

    return { success: false };
  }
});

Make testing easy

Include example inputs/outputs in your README.
Provide scripts for running unit tests or integration tests if the SDK supports them.
Test unexpected inputs (missing fields, wrong types, empty queries).

Think about future growth

Even for your first MiniApp:

Structure your code so you can add more capabilities later:
- For example, separate handlers/sayHello.ts, handlers/index.ts, etc.
Build with TypeScript types fully enabled ("strict": true in tsconfig).
Use consistent naming and file layout.

Troubleshooting common issues

When building your first AugmentOS MiniApp with the TypeScript SDK and trying to get it into the MiniApp Store (or share it for testing), these issues often show up:

TypeScript compilation errors

Ensure rootDir includes your src folder.
Check that your SDK types match the version installed.
If you see missing types, install @types/node or update the SDK.

Capability not being triggered

Verify the capability id in registerHandler exactly matches the id in the manifest.
Check the triggers list includes phrases similar to what you’re testing.
Confirm the MiniApp is enabled and visible to your account or workspace.

MiniApp not visible in the store

Confirm you completed all required metadata fields in the Dev Console.
Ensure your visibility is set to Public and not still Private.
Check email or console notifications for review rejections or required changes.

Summary

To build your first AugmentOS MiniApp with the TypeScript SDK and get it into the MiniApp Store (or share it for testing), you’ll:

Set up Node.js, TypeScript, and the AugmentOS TypeScript SDK.
Define a manifest describing your MiniApp and its capabilities.
Implement handlers with the SDK’s runtime and context APIs.
Build and test locally or in an AugmentOS sandbox.
Share privately via internal deployment or dev links.
Submit to the MiniApp Store, complete metadata, and pass review.
Iterate and update based on real user feedback.

Once you’ve shipped this first MiniApp, you can reuse the same structure and TypeScript patterns to create more advanced experiences—multi-step workflows, integrations with external APIs, and richer interaction models—all discoverable through the AugmentOS MiniApp Store.