From b33174b8ef5fb6f180abf32a9090b3495b54e9ea Mon Sep 17 00:00:00 2001 From: Paul Cramer Date: Fri, 10 Jan 2025 10:21:48 -0800 Subject: [PATCH 1/2] docs: Add troubleshooting --- .changeset/tiny-jobs-knock.md | 5 + site/docs/pages/guides/troubleshooting.mdx | 112 +++++++++++++++++++++ site/sidebar.ts | 4 + 3 files changed, 121 insertions(+) create mode 100644 .changeset/tiny-jobs-knock.md create mode 100644 site/docs/pages/guides/troubleshooting.mdx diff --git a/.changeset/tiny-jobs-knock.md b/.changeset/tiny-jobs-knock.md new file mode 100644 index 0000000000..476e689f95 --- /dev/null +++ b/.changeset/tiny-jobs-knock.md @@ -0,0 +1,5 @@ +--- +'@coinbase/onchainkit': patch +--- + +- **docs**: Add Troubleshooting section. By @cpcramer #1803 diff --git a/site/docs/pages/guides/troubleshooting.mdx b/site/docs/pages/guides/troubleshooting.mdx new file mode 100644 index 0000000000..1d5350e8be --- /dev/null +++ b/site/docs/pages/guides/troubleshooting.mdx @@ -0,0 +1,112 @@ +# Troubleshooting + +This guide covers common issues you may encounter while using OnchainKit. If you don't find your issue here, try searching our [GitHub Issues](https://github.com/coinbase/onchainkit/issues) or joining our [Discord Community](https://discord.gg/vbpeXpkPkw). + +## Common Issues + +### Environment Setup +- **Missing API Key** + - Error: "Project ID is required for this component" + - Solution: Add your Client API Key to `.env`: + ```dotenv + NEXT_PUBLIC_CDP_API_KEY=YOUR_PUBLIC_API_KEY + ``` + +- **Invalid Environment Variables** + - Error: "Cannot find environment variable" + - Solution: Use the correct variable name for your framework: + - Next.js: `NEXT_PUBLIC_CDP_API_KEY` + - Vite: `VITE_PUBLIC_ONCHAINKIT_API_KEY` + - Astro: `PUBLIC_ONCHAINKIT_API_KEY` + +- **Contracts Not Available** + - Error: "Contracts are not available" or "Contracts not available for LifecycleStatus" + - Solutions: + - Verify `NEXT_PUBLIC_ONCHAINKIT_API_KEY` is set correctly + - For Checkout component with chargeHandler, also set: + ```dotenv + NEXT_PUBLIC_COINBASE_COMMERCE_API_KEY=YOUR_COMMERCE_API_KEY + ``` + - Ensure API keys are properly exposed in your environment + +### Dependencies +- **Version Compatibility** + - Issue: Unexpected behavior or type errors + - Solution: Ensure compatible versions: + ```json + { + "dependencies": { + "@coinbase/onchainkit": "latest", + "viem": "^2.0.0", + "@wagmi/core": "^2.0.0" + } + } + ``` + +### Provider Configuration +- **Missing OnchainKitProvider** + - Error: "OnchainKit context not found" + - Solution: Wrap your app with OnchainKitProvider and [configure](/getting-started) properly: + ```tsx + import { OnchainKitProvider } from '@coinbase/onchainkit'; + import { base } from 'viem/chains'; + + export default function App({ children }) { + return ( + + {children} + + ); + } + ``` + +### Wallet Connection +- **Connection Failed** + - Error: "Unable to connect wallet" + - Solutions: + - Verify wallet extension is installed and unlocked + - Check [supported chains configuration](/wallet/wallet) + - Ensure proper network selection in wallet + - Verify RPC endpoints are accessible + +- **Chain Switching Issues** + - Error: "Failed to switch chain" + - Solutions: + - Verify chain ID is supported by OnchainKit + - Check wallet has required permissions + - Ensure RPC endpoints are configured correctly + - Add chain to wallet if not already added + +### Transaction Issues +- **Gas Estimation Failed** + - Error: "Gas estimation failed" + - Solutions: + - Verify sufficient balance for gas + - Check transaction parameters are valid + - Ensure proper network [configuration](/transaction/transaction) + +### Identity Components + +### Theme Issues +- **Dark Mode Not Working** + - Error: "Dark mode styles not applying" + - Solution: Configure Tailwind and OnchainKit properly: + ```js + // tailwind.config.js + module.exports = { + darkMode: ['class'], + safelist: ['dark'], + // ... rest of config + } + ``` + +## Getting Help + +Need more help? + +- [Discord Community](https://discord.gg/vbpeXpkPkw) +- [X/Twitter Support](https://x.com/onchainkit) +- [GitHub Issues](https://github.com/coinbase/onchainkit/issues) \ No newline at end of file diff --git a/site/sidebar.ts b/site/sidebar.ts index c22c7b1ec1..856dd1ed74 100644 --- a/site/sidebar.ts +++ b/site/sidebar.ts @@ -51,6 +51,10 @@ export const sidebar = [ text: 'Theme Customization', link: '/guides/themes', }, + { + text: 'Troubleshooting', + link: '/guides/troubleshooting', + }, { text: 'Use Basename', link: '/guides/use-basename-in-onchain-app', From a1495c7e9cb80c58fa50c0115dce9d7b1d892338 Mon Sep 17 00:00:00 2001 From: Paul Cramer Date: Mon, 13 Jan 2025 08:52:25 -0800 Subject: [PATCH 2/2] style --- site/docs/pages/guides/troubleshooting.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/site/docs/pages/guides/troubleshooting.mdx b/site/docs/pages/guides/troubleshooting.mdx index 1d5350e8be..7937e61fc0 100644 --- a/site/docs/pages/guides/troubleshooting.mdx +++ b/site/docs/pages/guides/troubleshooting.mdx @@ -23,7 +23,7 @@ This guide covers common issues you may encounter while using OnchainKit. If you - Error: "Contracts are not available" or "Contracts not available for LifecycleStatus" - Solutions: - Verify `NEXT_PUBLIC_ONCHAINKIT_API_KEY` is set correctly - - For Checkout component with chargeHandler, also set: + - For Checkout component with `chargeHandler`, also set: ```dotenv NEXT_PUBLIC_COINBASE_COMMERCE_API_KEY=YOUR_COMMERCE_API_KEY ```