# Contribute Mini Apps {% embed url="" %} {% hint style="info" %} This contribution guide is only relevant to Embedded Mini Apps for getting listed in [Mini Apps Store](https://circles.gnosis.io/miniapps) . Standalone Mini Apps are not required to be submitted and can be deployed independently. {% endhint %} This submission path is for apps that should ship from this repository and appear in the `/miniapps` marketplace. Deploying your miniapps elsewhere and only adding a hosted URL to the json directory is not allowed. ### What an embedded submission means Your PR must include the full application code that will run inside Circles MiniApps. At minimum, the PR should include: * The miniapp source code in this repository * Any local assets required by the app * A logo committed to this repository * A new entry in `static/miniapps.json` * Any setup notes or app-specific dependencies needed to build the repo If the implementation lives elsewhere and the PR only adds an external URL, that will not be considered. ### How the host works The marketplace reads app metadata from `static/miniapps.json`. When a user opens `/miniapps/`, the host page at `src/routes/miniapps/[slug]/+page.svelte` looks up the matching entry in `static/miniapps.json` and loads its `url` inside an iframe. For an embedded miniapp, the `url` should point to a route served by this same repository, not to an external deployment. Recommended pattern: * Host wrapper route: `/miniapps/` * Embedded app route in this repo: `/apps/` * `static/miniapps.json` entry: `"url": "/apps/"` ### Required file layout Create the app under `src/routes/apps//`. Typical structure: ``` src/routes/apps//+page.svelte src/routes/apps//+page.ts src/routes/apps//components/... static/app-logos/.png static/apps//... ``` Only add the files you actually need. A simple app may only require `+page.svelte` and a logo. ### Submission steps #### 1. Pick a stable slug Choose a URL-safe slug. This becomes: * The marketplace path: `/miniapps/` * The internal app path: `/apps/` * Usually the filename for the logo asset Use lowercase letters, numbers, and hyphens. Do not reuse an existing slug from `static/miniapps.json`. #### 2. Add the app code to this repo Create a new route at: ``` src/routes/apps//+page.svelte ``` Add any supporting files next to it. The app should be self-contained enough for reviewers to inspect its full behavior directly in the PR. Avoid designs where critical UI or business logic still lives in another repository. #### 3. Keep app assets local Commit the app logo and any static assets to this repo instead of depending on remote assets whenever possible. Recommended locations: * Logo: `static/app-logos/.png` * App assets: `static/apps//...` Use local paths in the app metadata, for example: ```json "logo": "/app-logos/.png" ``` #### 4. Register the app in `static/miniapps.json` Add a new entry like this: ```json { "slug": "my-app", "name": "My App", "logo": "/app-logos/my-app.png", "url": "/apps/my-app", "description": "Short description of what the app does.", "tags": ["payments", "tools"], "category": "miniapp" } ``` Requirements: * `slug` must be unique * `url` must point to the in-repo route for your app * `logo` should be a local asset committed in the PR * `description` should be short and specific * `tags` should reflect how users would discover the app * `category` should normally be `"miniapp"` Do not submit an embedded miniapp PR with an external `https://...` URL unless there is a very specific reason and the maintainers have explicitly asked for it. #### 5. Implement the host integration Embedded miniapps still run inside the miniapp host iframe, so they must work correctly within that environment. If your app needs wallet information, transaction approval, or signing, implement the existing `postMessage` contract used by the host page: * Miniapp to host: `request_address`, `send_transactions`, `sign_message` * Host to miniapp: `wallet_connected`, `wallet_disconnected`, `app_data`, `tx_success`, `tx_rejected`, `sign_success`, `sign_rejected` The current host implementation lives in: * `src/routes/miniapps/[slug]/+page.svelte` * `src/routes/playground/+page.svelte` Build against the actual behavior in code, not assumptions. #### 6. Verify locally before opening the PR Run: ```sh npm install npm run check npm run build ``` Then verify manually: 1. Open `/miniapps` 2. Confirm your app appears in the marketplace 3. Open `/miniapps/` 4. Confirm the wrapper loads `/apps/` correctly 5. Test the main user flow 6. If applicable, test wallet connection, signing, and transaction requests If your app requires extra environment variables or setup, document that in the PR description. ### PR expectations Your Pull Request should contain the full change needed to merge and ship the app from this repository. Include: * The full app implementation * A metadata entry in `static/miniapps.json` * Local logo/assets * Any required dependency changes in `package.json` * A clear PR description covering: * What the app does * Which route was added * How it was tested * Any follow-up work or known limitations Recommended PR title format: ``` feat: add embedded miniapp ``` ### Review criteria maintainers will care about Expect review on: * Whether the PR contains the full app, not just a pointer to another deployment * Whether the app is understandable and maintainable in this repo * Whether the app works inside the iframe host * Whether the app uses the wallet/signing flow safely * Whether assets and branding are committed locally * Whether the app builds cleanly with the rest of the project ### What will usually be rejected These submissions are likely to be sent back: * PRs that only add an external URL to `static/miniapps.json` * PRs where the main app logic still lives outside this repository * PRs that rely on remote logos or assets without a strong reason * PRs with missing slug registration or broken local routes * PRs that were not validated with `npm run check` and `npm run build` * PRs that do not work inside the miniapp iframe environment ### Minimal checklist * [ ] App source code added under `src/routes/apps//` * [ ] Logo committed under `static/app-logos/` * [ ] App metadata added to `static/miniapps.json` * [ ] `url` points to a local in-repo route * [ ] `npm run check` passes * [ ] `npm run build` passes * [ ] `/miniapps` shows the app * [ ] `/miniapps/` loads and works If you want maintainers to merge and host your app as part of this project, submit the full app in the PR. --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.aboutcircles.com/miniapps/contribute-mini-apps.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.