controller-react
Integrate Cartridge Controller into React applications using starknet-react. Use when building React/Next.js web apps with Controller, setting up StarknetConfig provider, using hooks like useConnect/useAccount, or implementing wallet connection components. Covers ControllerConnector setup, provider configuration, and transaction execution patterns.
How do I install this agent skill?
npx skills add https://github.com/cartridge-gg/docs --skill controller-reactIs this agent skill safe to install?
- Gen Agent Trust Hubpass
The skill provides standard integration patterns for using the Cartridge Controller within React applications. It demonstrates the use of official libraries and connection to vendor-owned RPC infrastructure for Starknet development.
- Socketpass
No alerts
- Snykwarn
Risk: MEDIUM · 1 issue
- Runlayerpass
1/1 file flagged
What does this agent skill do?
Controller React Integration
Integrate Cartridge Controller with React using starknet-react.
Installation
pnpm add @cartridge/connector @cartridge/controller @starknet-react/core @starknet-react/chains starknet
pnpm add -D vite-plugin-mkcert
Provider Setup
Important: Create connector outside React components.
import { sepolia, mainnet, Chain } from "@starknet-react/chains";
import { StarknetConfig, jsonRpcProvider, cartridge } from "@starknet-react/core";
import { ControllerConnector } from "@cartridge/connector";
import { SessionPolicies } from "@cartridge/controller";
// Define contract addresses
const ETH_TOKEN_ADDRESS =
"0x049d36570d4e46f48e99674bd3fcc84644ddd6b96f7c741b1562b82f9e004dc7";
const policies: SessionPolicies = {
contracts: {
[ETH_TOKEN_ADDRESS]: {
methods: [
{
name: "approve",
entrypoint: "approve",
spender: "0x1234567890abcdef1234567890abcdef12345678",
amount: "0xffffffffffffffffffffffffffffffff",
description: "Approve spending of tokens",
},
{ name: "transfer", entrypoint: "transfer" },
],
},
},
};
// Create OUTSIDE component
const connector = new ControllerConnector({ policies });
// Katana chain definition for local development
// Requires katana.toml with [cartridge] paymaster = true
const KATANA_CHAIN_ID = "0x4b4154414e41"; // "KATANA" hex-encoded ASCII
const KATANA_URL = "http://localhost:5050";
const katana: Chain = {
id: BigInt(KATANA_CHAIN_ID),
name: "Katana",
network: "katana",
testnet: true,
nativeCurrency: {
address: "0x04718f5a0fc34cc1af16a1cdee98ffb20c31f5cd61d6ab07201858f4287c938d",
name: "Stark",
symbol: "STRK",
decimals: 18,
},
rpcUrls: {
default: { http: [KATANA_URL] },
public: { http: [KATANA_URL] },
},
// Required for Controller account auto-deployment on Katana
paymasterRpcUrls: {
avnu: { http: [KATANA_URL] },
},
};
const provider = jsonRpcProvider({
rpc: (chain: Chain) => {
switch (chain) {
case mainnet:
return { nodeUrl: "https://api.cartridge.gg/x/starknet/mainnet" };
case sepolia:
return { nodeUrl: "https://api.cartridge.gg/x/starknet/sepolia" };
default:
return { nodeUrl: KATANA_URL };
}
},
});
export function StarknetProvider({ children }: { children: React.ReactNode }) {
return (
<StarknetConfig
autoConnect
defaultChainId={katana.id}
chains={[katana, mainnet, sepolia]}
provider={provider}
connectors={[connector]}
explorer={cartridge}
>
{children}
</StarknetConfig>
);
}
Connect Wallet Component
import { useAccount, useConnect, useDisconnect } from "@starknet-react/core";
import { ControllerConnector } from "@cartridge/connector";
import { useEffect, useState } from "react";
export function ConnectWallet() {
const { connect, connectors } = useConnect();
const { disconnect } = useDisconnect();
const { address } = useAccount();
const controller = connectors[0] as ControllerConnector;
const [username, setUsername] = useState<string>();
useEffect(() => {
if (!address) return;
controller.username()?.then(setUsername);
}, [address, controller]);
if (address) {
return (
<div>
<p>Account: {address}</p>
{username && <p>Username: {username}</p>}
<button onClick={() => disconnect()}>Disconnect</button>
</div>
);
}
return (
<div>
<button onClick={() => connect({ connector: controller })}>
Connect
</button>
</div>
);
}
Dynamic Auth Buttons
const handleSpecificAuth = async (signupOptions: string[]) => {
try {
// Direct controller connection for specific auth options
await controller.connect({ signupOptions });
// Manually trigger starknet-react state update
connect({ connector: controller });
} catch (error) {
console.error("Connection failed:", error);
}
};
<button onClick={() => handleSpecificAuth(["phantom-evm"])}>
Continue with Phantom
</button>
<button onClick={() => handleSpecificAuth(["google"])}>
Continue with Google
</button>
Execute Transactions
import { useAccount, useExplorer } from "@starknet-react/core";
import { useCallback, useState } from "react";
const ETH = "0x049d36570d4e46f48e99674bd3fcc84644ddd6b96f7c741b1562b82f9e004dc7";
export function TransferEth() {
const [submitted, setSubmitted] = useState<boolean>(false);
const { account } = useAccount();
const explorer = useExplorer();
const [txnHash, setTxnHash] = useState<string>();
const execute = useCallback(
async (amount: string) => {
if (!account) return;
setSubmitted(true);
setTxnHash(undefined);
try {
const result = await account.execute([
{
contractAddress: ETH,
entrypoint: "approve",
calldata: [account.address, amount, "0x0"],
},
{
contractAddress: ETH,
entrypoint: "transfer",
calldata: [account.address, amount, "0x0"],
},
]);
setTxnHash(result.transaction_hash);
} catch (e) {
console.error(e);
} finally {
setSubmitted(false);
}
},
[account]
);
if (!account) return null;
return (
<div>
<button onClick={() => execute("0x1C6BF52634000")} disabled={submitted}>
Transfer 0.005 ETH
</button>
{txnHash && (
<a href={explorer.transaction(txnHash)} target="_blank" rel="noreferrer">
View Transaction
</a>
)}
</div>
);
}
External Wallet Methods
// Wait for transaction confirmation
const response = await controller.externalWaitForTransaction(
"metamask",
txHash,
30000 // timeout ms
);
if (response.success) {
console.log("Receipt:", response.result);
} else {
console.error("Error:", response.error);
}
// Switch chains
const success = await controller.externalSwitchChain("metamask", chainId);
Supported wallet types: metamask, rabby, phantom, argent, walletconnect.
Vite Configuration
Enable HTTPS for local development:
import { defineConfig } from "vite";
import react from "@vitejs/plugin-react";
import mkcert from "vite-plugin-mkcert";
export default defineConfig({
plugins: [react(), mkcert()],
});
Development Modes
# Local development with local APIs
pnpm dev
# Testing with production APIs (hybrid mode)
pnpm dev:live
The dev:live mode runs keychain locally while connecting to production APIs.
App Structure
import { StarknetProvider } from "./StarknetProvider";
import { ConnectWallet } from "./ConnectWallet";
import { TransferEth } from "./TransferEth";
function App() {
return (
<StarknetProvider>
<ConnectWallet />
<TransferEth />
</StarknetProvider>
);
}
How can the creator link this skill?
Add the canonical catalog link to the repository README so users can inspect current installs and available audits. The publishing guide covers the complete discovery path.
<a href="https://skillzs.dev/skills/cartridge-gg/docs/controller-react">View controller-react on skillZs</a>