antonpaisov/calimero-app-prompt.md

## calimero-app-prompt.md

      
    Raw
  

              calimero-app-prompt.md
            
          
    🧠 Calimero AI Prompt Template (for Cursor / AI builders)

This markdown file is meant to be used as a prompt template for AI tools like Cursor, GitHub Copilot, or other LLM-based assistants that can scaffold Calimero applications.
It includes:

The full build & workflow guide for Calimero apps
Commentary on how to use it as an AI prompt
A sample application spec at the end (Battleships game)


💡 Copy this entire markdown into your AI environment (Cursor, Copilot, etc.)

Then replace the app specification section at the end with your own app idea.


🧾 Original Prompt

Let’s build a Calimero application together:
First step for you is to call install:
npm i -g create-mero-app@latest
npx create-mero-app <application_name>
with your <application_name>.
You can familiarize yourself with how to build by reading the README,

but here is a simple overview of how things work.

🗂️ Project Structure (generated)


app/: Frontend (Vite + React)
logic/: Calimero service logic (Rust → WASM)
package.json: Top-level scripts for both logic and app

Key top-level scripts:

pnpm logic:build: builds WASM + ABI
pnpm app:generate-client: generates typed client from ABI
pnpm app:dev: runs frontend dev server
pnpm network:bootstrap: boots Merobox workflow


💡 When you run pnpm logic:build, the app automatically generates the client.

If you change the logic package_name, update the applicationId after running the Merobox workflow.


⚙️ Backend Logic Guidelines (Rust)


Use UnorderedMap<String, T> for keys. Avoid u64 keys (storage requires AsRef<[u8]>).


For timestamps in WASM, use the Calimero env helper (not std::time::SystemTime):
env::time_now() // returns block time in ms
Source: core/env.rs#L114


If you return complex types to the frontend:

Make them Serialize and return directly if ABI supports them, or
Serialize to JSON String in view functions.


Avoid exposing helper methods with conflicting names (e.g., multiple from_string, to_string). Prefer private helpers.


🔨 Build Flow (Authoritative)


Edit Rust logic in logic/src/lib.rs.
Build WASM + ABI:
pnpm logic:build

Generate frontend ABI client (if ABI changed):
pnpm app:generate-client

Run frontend:
pnpm app:dev


🧩 Merobox Workflow (install, context, prefill)

Update workflow to install the built WASM and create a context:

Change path to logic/res/<your_app>.wasm
Add steps to call your logic methods to prefill demo data (e.g. create issues, add comments)

Run:
pnpm network:bootstrap
Grab the captured applicationId and update:
// app/src/App.tsx
const [clientAppId] = useState<string>('REPLACE_WITH_applicationId');

💻 Frontend Integration Notes

After generating app/src/api/AbiClient.ts, use it via an app-aware factory:
const contexts = await app.fetchContexts();
const context = contexts[0];
const api = new AbiClient(app, context);
If ABI return types are JSON strings, parse on the client:
const issuesJson = await api.getAllIssues();
const issues = JSON.parse(issuesJson);
If any named exports are missing (e.g., Modal/Badge), temporarily shim them with simple styled elements, then re-upgrade @calimero-network/mero-ui and clear Vite cache.

🧯 Common Pitfalls + Fixes

Missing export errors:
pnpm --dir app update @calimero-network/mero-ui --latest
rm -rf app/node_modules/.vite
pnpm --dir app dev
Optionally log exports:
import * as UI from '@calimero-network/mero-ui';
console.log(Object.keys(UI));
Other common fixes:

ABI codegen “Duplicate method names” → make helpers private or rename
UnorderedMap iteration → use .entries()?
WASM time panic → use env::time_now()
Key types → use String keys, convert IDs with .to_string()


⚙️ Quality-of-Life Scripts

Add to top-level package.json:
{
  "scripts": {
    "dev": "concurrently -k -n logic,app \"pnpm logic:build --watch\" \"pnpm app:dev\"",
    "rebuild": "pnpm logic:build && pnpm app:generate-client",
    "bootstrap": "pnpm network:bootstrap"
  }
}

🚀 End-to-End Quickstart

# Scaffold
npm i -g create-mero-app@latest
npx create-mero-app shared-todo-backlog
cd shared-todo-backlog

# Dependencies
pnpm install
pnpm add @calimero-network/mero-ui@latest

# Build backend + client
pnpm logic:build
pnpm app:generate-client

# Run Merobox bootstrap (installs wasm, creates context, pre-fills demo data)
pnpm network:bootstrap

# Set applicationId in app/src/App.tsx from bootstrap output
# Then run the frontend
pnpm app:dev

🔗 References


Calimero env time helper: env::time_now()

core/env.rs#L114


⚔️ Example Application Specification

Let’s build a Battleships game as a Calimero application.

Two players each add their ships to the board
Once setup is done, players take turns firing shots
The Calimero logic handles:

State sync between player nodes
Validation of turns
Real-time updates via node callbacks (v0.9.0+)


You can customize this spec to your own app idea — just replace this section with your requirements and share with your AI dev assistant (Cursor, Copilot, etc.)


🧩 Template designed for AI-assisted Calimero app generation.
No results found