notifi-network/notifi-sdk-ts/notifi-react-integration

Notifi React Integration

Use this skill for app-side frontend integration of @notifi-network/notifi-react.

This skill is for wiring Notifi into a user's React or Next.js application. It is not for tenant-side publishing, MCP operations, or admin-side notification workflows.

The main job of this skill is to help the agent decide:

• whether the user wants in-place integration or a full-page app generated from the Notifi dapp example baseline
• whether the user should use NotifiCardModal, custom context integration, or NotifiSmartLink
• which auth mode the integration needs
• which params are required before writing code
• how to make the smallest correct change inside the user's existing app structure

Scope Boundary

Use this skill for:

• generating a full-page app from the Notifi dapp example baseline when the user explicitly wants a starter app or standalone example app
• embedding NotifiCardModal
• wiring NotifiContextProvider
• building custom notification settings UI with Notifi React hooks
• handling Notifi React auth setup
• passing topic inputs for dynamic subscriptions
• integrating SmartLink UI
• troubleshooting notifi-react integration issues in frontend apps

Do not use this skill for:

• tenant-side publish workflows
• MCP tool usage
• direct Dataplane or GraphQL notification publishing
• admin portal operations

For those cases, prefer notifi-tenant-operation instead.

Full-Page App From Notifi Dapp Example

Use this path when the user wants a full-page app, starter app, standalone example app, or wants the agent to start from Notifi's example app instead of integrating into an existing codebase.

Required behavior:

• use the GitHub notifi-sdk-ts repo's packages/notifi-dapp-example as the baseline
• prepare or pull a separate working copy of the example app before editing
• modify only the pulled working copy, not the SDK source tree in place
• MUST ask for tenantId and cardId before writing any code. If tenantId or cardId is missing, the agent MUST NOT generate files, install dependencies, or configure providers until the user provides them.
• default env to Production when the user does not specify a different environment
• MUST ask the user to choose a supported chain group from the notifi-wallet-provider support model: evm, solana, cosmos, or cardano. Do not assume or default a chain group.
• after the user selects a chain group, the agent MUST ask which wallets from the supported list to include. The agent MUST NOT ask about wallets before the chain group is confirmed.
• use packages/notifi-wallet-provider/lib/utils/walletConfigs.ts as the canonical source for the chain-group and wallet mapping
• treat this as an app-generation path first, resolve the runtime questions for this path, and only then choose the appropriate integration surface inside that app (NotifiCardModal, custom contexts, or NotifiSmartLink)

Do not treat this path as the default when the user already has an existing app and only needs Notifi integrated into it.

Start With The Smallest Correct Path

If the user wants a full-page app or starter app, use the dedicated dapp-example path first.

Otherwise, default to the smallest correct integration instead of introducing a full custom implementation.

For existing-app integration, use this decision order:

1. If the user wants the fastest usable Notifi UI, prefer NotifiCardModal.
2. If the user wants a custom preferences UI or wants to compose their own notification flows, use custom context integration.
3. If the user is building a SmartLink or action-centric surface, use NotifiSmartLink.

Do not push a custom integration when NotifiCardModal is enough.

Required Inputs

Before implementing, confirm the minimum required integration inputs.

Core params:

• tenantId
• cardId
• env

If any core param is missing, the agent MUST NOT proceed with implementation. Do not silently default any core param except env (which defaults to Production when unspecified).

Auth params depend on mode.

On-chain auth

Required:

• walletBlockchain
• walletPublicKey
• signMessage

Sometimes also needed:

• accountAddress

Be careful: the correct value for walletPublicKey is chain and wallet dependent. Do not assume every wallet uses the same address encoding or key format.

For on-chain auth, the agent MUST confirm walletBlockchain before collecting walletPublicKey and signMessage. Do not assume the blockchain based on the wallet type alone.

Off-chain auth

Required:

• walletBlockchain: 'OFF_CHAIN'
• userAccount
• signIn

userAccount should be a stable user identifier. Do not invent one if the app's auth model is unclear.

For off-chain auth, the agent MUST confirm userAccount with the user. Do not invent a user identifier from incomplete information.

Optional but common

• inputs
• notificationCountPerPage
• toggleTargetAvailability
• isEnabledLoginViaTransaction
• SmartLink authParams

If tenantId, cardId, env, or the auth callback is missing: the agent MUST ask the user before writing any implementation code. The sole exception is when the user explicitly requests a scaffold or placeholder setup. In that case, use explicit TODO markers with instructions for finding the real value. Do not silently hardcode plausible-looking values under any circumstances.

For the full-page dapp-example path, ask for missing tenantId and cardId before implementation. If the user does not specify env, default it to Production. Do not silently hardcode plausible-looking tenant or card values, and do not treat this path as a placeholder-only scaffold unless the user explicitly asks for one.

For the full-page dapp-example path, do not ask the user to choose from every Notifi blockchain enum. Ask them to choose from the chain groups supported by notifi-wallet-provider first.

Current supported chain groups for this path:

• evm
• solana
• cosmos
• cardano

Wallet follow-up rules:

• after the user chooses evm, ask which of these wallets to support: metamask, coinbase, rabby, walletconnect, okx, rainbow, zerion, binance
• after the user chooses solana, ask whether to support phantom
• after the user chooses cosmos, ask whether to support keplr
• after the user chooses cardano, ask which of these wallets to support: lace, eternl, nufi, okx-cardano, yoroi, ctrl
• the agent MUST NOT ask about wallets before the chain group is selected by the user. This is a hard ordering constraint. Violating this order must be treated as a blocking error.
• do not invent unsupported chain-group or wallet pairings
• if the user asks for a chain outside this support model, explain that the dapp-example baseline does not provide a ready-made wallet-provider flow for it and ask whether they want to switch to a supported chain group or pursue a custom adapter path

Clarification Gate

Before writing any code, installing any dependency, or creating any file, the agent MUST ensure all required inputs for the chosen path are confirmed with the user.

Hard-stop conditions (MUST NOT proceed):

• tenantId not confirmed
• cardId not confirmed
• auth mode not determined
• for on-chain: walletBlockchain not confirmed
• for off-chain: userAccount not confirmed
• for full-page path: chain group not chosen before wallets
• integration path not confirmed

Exception:

If the user explicitly requests a scaffold (e.g., "just write the provider wiring, I'll add values later"), use TODO placeholders and skip the hard-stop.

Auth Branching

Pick the auth path early because it changes the provider contract.

Use on-chain auth when

• the app already has a connected wallet
• the user wants wallet-based login
• the project already has wallet adapters or wallet providers in place

Implementation guidance:

• adapt the existing wallet library's signing API to Notifi's signMessage shape
• reuse the app's current wallet connection state instead of introducing a new wallet stack
• map the correct wallet key or address format for that blockchain

Use off-chain auth when

• the app authenticates users through OIDC, JWT, email login, or another non-wallet identity
• the user explicitly says the app is not using wallet login

Implementation guidance:

• provide walletBlockchain='OFF_CHAIN'
• derive userAccount from an existing stable user identifier
• implement signIn using the app's current auth token flow

Special auth cases

Only introduce these when the user's app actually needs them:

• transaction login
• Solana hardware wallet login
• wallet target plugin

Do not surface these as standard setup unless the app context makes them relevant.

Minimal Integration Path

When the user wants a quick embed, prefer this path.

1. Add NotifiContextProvider near the existing wallet or auth boundary.
2. Pass the minimum required provider props.
3. Render NotifiCardModal in the relevant page or modal surface.
4. Import the package CSS when using packaged components.

Use this path for requests like:

• "add Notifi to my app"
• "I just need the card working"
• "help me mount the subscription modal"

Implementation guidance:

• fit the provider into the user's current app tree instead of creating an isolated demo wrapper unless necessary
• keep the initial version small and working
• use the existing router, layout, modal, and wallet hooks already present in the project

NotifiCardModal Entry Placement

When the user wants NotifiCardModal, do not only think about provider wiring. Also choose a natural entry surface.

Preferred heuristic:

1. If the app already has a top nav or header utility area, prefer using that area for the modal entry.
2. Prefer a small icon CTA over adding a large new section or standalone demo block.
3. Keep the entry close to existing wallet, account, settings, or other utility actions when possible.
4. Preserve the app's current header structure, spacing, and interaction style.

If there is no clear top nav or header utility surface, fall back to the nearest existing action area instead of inventing a new layout pattern.

CTA Placement Ambiguity Handling

If the app structure suggests more than one reasonable entry location, do not guess too aggressively.

Guidance:

• if the current UI clearly implies a best placement, proceed with the smallest natural integration
• if there are multiple plausible locations, ask the user which entry surface they prefer
• offer a few concrete options instead of asking an open-ended design question
• if the user has no preference, state the default choice and proceed with the smallest reasonable option

Good question pattern:

• "I found an existing header/top nav. Do you want the Notifi entry as a header utility icon, an icon near wallet/account actions, a profile menu item, or a temporary minimal button while placement is still undecided?"

Do not invent a brand new navigation pattern when existing app structure already provides a natural entry surface.

Modal Reopen And Readiness

If the host app mounts NotifiCardModal inside its own dialog, popover, drawer, or other CTA-triggered shell, do not assume reopen behavior will work automatically.

Guidance:

• reuse the app's existing modal shell when it is already the natural integration surface
• prefer remounting the Notifi subtree on each open instead of keeping it mounted forever behind an open flag
• if reopen shows an empty modal or inconsistent state, gate the inner NotifiCardModal render on Notifi context readiness rather than immediately rendering it
• use useNotifiFrontendClientContext and useNotifiUserSettingContext to wait for initialization and authenticated user-setting loading when needed
• keep this workaround in the host app wrapper layer; do not rewrite the packaged card UI unless there is a stronger product reason

Common failure mode: