LUKSO UP!Store

LUKSO UP!Store is a community-maintained directory for LUKSO Universal Profile Mini-Apps. Users can browse apps, open them directly, or add them to a Universal Profile Grid.

This is the JordyDutch version of the project. It started from the LUKSO hackathon work by Heisenburgirs, but the app now works differently: the catalog is maintained through GitHub pull requests, the storefront exposes machine-readable data, and Add to Grid works through the Universal Everything add-widget flow outside the Grid as well.

What This App Does

• Lists LUKSO Mini-Apps from src/data/apps.json.
• Builds app detail pages at /store/<appId>.
• Supports category browsing, search, featured apps, screenshots and source-code links.
• Adds apps to a Universal Profile Grid with prebuilt universaleverything.io/add-widget deep links.
• Still supports direct LSP28 The Grid writes when running inside a connected Universal Profile Grid context.
• Tracks app opens with optional Upstash Redis storage and ranks Trending from those counts.
• Exposes agent-friendly app data through /api/apps and /llms.txt.

How The Catalog Works

The catalog is data-driven. Adding or updating apps should usually require no TypeScript changes.

• App data lives in src/data/apps.json.
• App images live in public/apps/<slug>/.
• src/data/appCatalog.ts loads the JSON, derives image paths, builds featured apps, categories and extra widgets, and collapses related product-family entries into one store listing.

To update the catalog:

1. Fork this repository.
2. Edit src/data/apps.json.
3. Add or update images in public/apps/<slug>/.
4. Run the verification commands.
5. Open a pull request.

See docs/adding-apps.md for the exact JSON fields, image naming rules and category list.

Important Routes

Route	Purpose
/	Main discovery experience
/store	Full searchable app directory
/store/<appId>	Shareable app detail page with structured data
/search?q=<term>&category=<Category>	Search and category deep links
/api/apps	Machine-readable catalog JSON with absolute URLs and Add to Grid links
/api/track-open	Best-effort open tracking endpoint
/api/trending	Open-count data used by Trending
/llms.txt	LLM-friendly catalog overview

Add To Grid

The current default Add to Grid action uses Universal Everything's add-widget route:

https://universaleverything.io/add-widget?data=<URL-encoded widget JSON>

The widget JSON shape is:

{
  "properties": {
    "src": "https://example-mini-app.xyz"
  },
  "type": "IFRAME",
  "width": 1,
  "height": 1
}

The app builds these links in src/lib/addToGrid.ts. Each serialized app in /api/apps includes a ready-to-use addToGridUrl.

When the store is running inside a Universal Profile Grid and the wallet context is connected, useInstallApp can write updated LSP28 The Grid metadata directly: it updates the local grid sections, uploads the new metadata to IPFS through Pinata, encodes the VerifiableURI with ERC725.js, and calls setData on the Universal Profile.

Trending And Open Tracking

App opens are recorded through useAppLaunch.openApp, which calls trackOpen(app.id) before opening the app in a new tab.

Tracking is optional:

• Without Redis env vars, tracking no-ops and the store still works.
• With Upstash Redis configured, /api/track-open stores counts in the app:opens hash.
• Client session storage deduplicates one open per app per browser session.
• The server adds a 10-minute per-IP/app cooldown.
• /api/trending returns the counts used by the Trending section.

See docs/trending.md for setup details.

Environment Variables

Create .env with the services you need.

# Required for direct in-Grid install metadata uploads through Pinata.
PINATA_JWT=
NEXT_PUBLIC_GATEWAY_URL=

# Used for absolute URLs in metadata, sitemap, /api/apps and /llms.txt.
NEXT_PUBLIC_SITE_URL=http://localhost:3000

# Used by Apollo Client to fetch Universal Profile publisher metadata.
NEXT_PUBLIC_UNIVERSAL_GRAPH_URL=

# Optional: Upstash Redis for open tracking and Trending.
KV_REST_API_URL=
KV_REST_API_TOKEN=

# Also accepted for manual Upstash setups:
# UPSTASH_REDIS_REST_URL=
# UPSTASH_REDIS_REST_TOKEN=

For LUKSO mainnet profile data, NEXT_PUBLIC_UNIVERSAL_GRAPH_URL is normally:

https://envio.lukso-mainnet.universal.tech/v1/graphql

Local Development

git clone https://github.com/JordyDutch/mini-store.git
cd mini-store
npm install
npm run dev

The app runs on the Next.js dev server, usually http://localhost:3000.

Verification

Before opening a pull request, run:

npx tsc --noEmit
npm run build

For code changes, also run:

npm run lint

Tech Stack

• Next.js
• React
• TypeScript
• Tailwind CSS
• LUKSO UP Provider
• viem
• ERC725.js
• Apollo Client
• Pinata
• Upstash Redis

Project Status

This repository is focused on the live JordyDutch UP!Store flow:

• community catalog updates through pull requests;
• app discovery and Add to Grid links for users;
• machine-readable catalog data for agents and integrations;
• optional analytics-backed Trending without making tracking a hard dependency.