diff --git a/docs/fuse-box/tutorials/partner/README.mdx b/docs/fuse-box/tutorials/partner/README.mdx index 39e3960a..9ccc1969 100644 --- a/docs/fuse-box/tutorials/partner/README.mdx +++ b/docs/fuse-box/tutorials/partner/README.mdx @@ -7,3 +7,4 @@ sidebar_position: 3 | :------------------------------------------------------------ | :---- | | [FuseBox Login using MetaMask](metamask-login) | Web | | [FuseBox Social Login using Web3Auth](web3auth-login) | Web | +| [Social Logins and Account Abstraction with Particle Connect](particle-connect) | Web | diff --git a/docs/fuse-box/tutorials/partner/particle-connect.mdx b/docs/fuse-box/tutorials/partner/particle-connect.mdx new file mode 100644 index 00000000..61b4f290 --- /dev/null +++ b/docs/fuse-box/tutorials/partner/particle-connect.mdx @@ -0,0 +1,261 @@ +--- +title: Social Logins and Account Abstraction with Particle Connect +sidebar_position: 8 +--- + +Particle Connect combines Social and Web3 logins with built-in Account Abstraction support, all within a single SDK. This approach allows you to simplify user onboarding while directly incorporating AA features into your **Fuse dApp**. + +Integrating **Particle Connect** into your **Fuse** web application can be done in **under five minutes**. + +This guide provides a concise overview of how to install, configure, and enable social logins in a Next.js application using `create @particle-network/connectkit` as your starting point. + +:::note +For a detailed explanation of each feature and more advanced configurations, refer to the [Particle Connect SDK reference](/api-reference/connect/desktop/web). +::: + +--- + +### Boilerplate: Initializing Particle Connect + +The easiest way to get started with **Particle Connect** is through its built-in starter/boilerplate; this includes the core file setup and code structure needed to configure Particle Connect. + +To initialize this boilerplate, copy and execute one of the following commands. + +```sh Terminal +npm init @particle-network/connectkit@latest +# or +pnpm create @particle-network/connectkit@latest +# or +yarn create @particle-network/connectkit +``` + +After running one of the aforementioned commands, the CLI will guide you through a setup process; it will prompt you to enter a project name, choose your preferred framework (Next.js or React), and select additional options. + +```shell Terminal +🤩 Welcome to Particle Network! + +✔ What is the name of your project? … connectkit-aa-usage + +✔ What is the template of your project? › create-next-app +✔ Which chains does your app support?​ › EVM +✔ Which ERC-4337 Contract does your app support?​ › SIMPLE-2.0.0 +✔ Does it support an embedded wallet?​ … yes +``` + +:::note +This guide will proceed with a **Next.js** project setup, although **React (create-react-app)** is also supported. + +Additionally, Account Abstraction on Fuse is only supported through the `SIMPLE` instance of Smart Account. +::: + +### Configuring Particle Connect + +With a starter project initialized, you're ready to configure Particle Connect through its core component, `ConnectKitProvider`. + +Before diving deeper, you'll need some keys from the [Particle dashboard](https://dashboard.particle.network). + +**Particle Connect** requires three key values from the dashboard to be initiated: `projectId`, `clientKey`, and `appId`. + +### Access the Particle Dashboard + +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + +:::note +To get started, sign up or log in to the [Particle dashboard](https://dashboard.particle.network). +::: + +### Create a New Project or Use an Existing One + + + + +You can create a new project by clicking the **Add New Project** button on the dashboard. + + + + +Already have a project? Simply choose your existing project from the list on the dashboard. + + + + +### Create a New Web Application + +Create a new **Web** application from the **Your Apps** section in the Particle dashboard. + +### Retrieve the Project ID, Client Key, and Application ID + +Follow these steps to retrieve your credentials: + +1. Navigate to the **Project Information** section in your dashboard. + - Here, you'll find both your `projectId` and `clientKey`. +2. Go to the **Your Apps** section. + - Locate the web application you just created (or an existing one), and find the `appId` listed under the app's details. + +:::note +For a quick overview of the Particle dashboard, watch [this video](https://www.youtube.com/watch?v=d7DYCMNDmjo&ab_channel=ParticleNetwork) or check out the [Dashboard Quickstart Guide](/guides/dashboard). +::: + +After obtaining your `projectId`, `clientKey`, and `appId`, you'll need to use these to configure the `ConnectKitProvider` component from `@particle-network/connectkit`. + +The boilerplate already includes the basic variable setup—just add your API keys to the `.env.sample` file and rename it to `.env`. + +:::tip +At this point, you're ready to either run and test the application or begin development through `app/page.tsx`. + +We’ll also go over some of the granular controls available through `ConnectKitProvider`. +::: + +### Configuring ConnectKitProvider + +When working with `ConnectKitProvider`, it's recommended to use a dedicated `Connectkit.tsx` file in the `src` directory where you can configure and export the component. Then, you'll use this export to wrap your main App component (the location of your Particle Connect implementation through `ConnectButton`). + +Here’s how you can configure `ConnectKitProvider`: + +**Required Configurations:** +- `projectId`, `clientKey`, and `appId` — Get these from the [Particle dashboard](https://dashboard.particle.network). +- `chains` — Specify the supported chains for your dApp (this is an array of Viem-originating chain objects imported from `@particle-network/connectkit/chains`). +- `walletConnectors` — Define the wallets you want to support. + +**Optional Configurations:** +- `theme` and `language` for basic customization of the connection modal UI. +- Additional appearance customizations. + +:::note +In the boilerplate application, you'll find a pre-configured `Connectkit.tsx` file located in the `src` directory. +::: + +Below is an example of a **configured** instance of `ConnectKitProvider`. For more details around each available property, head over to the [Particle Connect Web SDK reference](/api-reference/connect/desktop/web). + +In this example, we import the `fuse` and `fuseSparknet` networks from `"@particle-network/connectkit/chains"`, and then add them to the `chains` array inside the `plugins` object. + +```tsx + +"use client"; + +// Particle imports +import { ConnectKitProvider, createConfig } from '@particle-network/connectkit'; +import { authWalletConnectors } from '@particle-network/connectkit/auth'; +import { evmWalletConnectors } from '@particle-network/connectkit/evm'; +import { solanaWalletConnectors } from '@particle-network/connectkit/solana'; +import { EntryPosition, wallet } from '@particle-network/connectkit/wallet'; + +import { fuse, fuseSparknet } from "@particle-network/connectkit/chains"; // Chains are imported here +import { aa } from "@particle-network/connectkit/aa"; // Account Abstraction packages +import React from 'react'; + +const config = createConfig({ + projectId: process.env.NEXT_PUBLIC_PROJECT_ID!, + clientKey: process.env.NEXT_PUBLIC_CLIENT_KEY!, + appId: process.env.NEXT_PUBLIC_APP_ID!, + + appearance: { + recommendedWallets: [ + { walletId: 'metaMask', label: 'Recommended' }, + { walletId: 'coinbaseWallet', label: 'popular' }, + ], + language: 'en-US', + mode: "auto", // dark or auto. + }, + + walletConnectors: [ + evmWalletConnectors({ + // Replace this with your app metadata. + metadata: { + name: 'Connectkit Demo', + icon: typeof window !== 'undefined' ? `${window.location.origin}/favicon.ico` : '', + description: 'Particle Connectkit Next.js Scaffold.', + url: typeof window !== 'undefined' ? window.location.origin : '', + }, + walletConnectProjectId: process.env.NEXT_PUBLIC_WALLETCONNECT_PROJECT_ID as string, + }), + + authWalletConnectors({ + authTypes: ['email', 'google', 'twitter', 'github'], // Optional, restricts the types of social logins supported + }), + ], + + plugins: [ + wallet({ + visible: true, + entryPosition: EntryPosition.BR, // Use BR (bottom right), BL (bottom left), TR (top right), TL (top left) to move the wallet entry position + }), + + // aa config start + aa({ + name: "SIMPLE", + version: "2.0.0", + }), + // aa config end + ], + + // List the chains you want to include + chains: [fuse, fuseSparknet], +}); + +// Wrap your application with this exported component, or ConnectKitProvider directly. +export const ParticleConnectkit = ({ children }: React.PropsWithChildren) => { + return {children}; +}; +``` + +:::tip +For more detailed information, visit the full [**Particle Connect** SDK documentation](/api-reference/connect/desktop/web). +::: + +### Wrapping Your Application with ConnectKitProvider + +Wrap your primary application component (wherever you place and use `ConnectButton` alongside the various hooks from Particle Connect) with the `ParticleConnectKit` component (exported from `ConnectKitProvider`). + +:::note +In the boilerplate application, you'll find a pre-configured `layout.tsx` file located in the `app` directory. +::: + +Here’s an example of what this looks like for a `layout.tsx` file: + +```tsx layout.tsx +import { ParticleConnectkit } from '@/connectkit'; // Export of a configured ConnectKitProvider instance +import type { Metadata } from 'next'; +import { Inter } from 'next/font/google'; +import './globals.css'; + +const inter = Inter({ subsets: ['latin'] }); + +export const metadata: Metadata = { + title: 'Particle Connectkit App', + description: 'Generated by create next app', +}; + +export default function RootLayout({ + children, +}: Readonly<{ + children: React.ReactNode; +}>) { + return ( + + + {children} + + + ); +} +``` + +### Facilitating Logins and Chain Interactions + +With **Particle Connect** now configured, you can proceed to enable social logins within your application through the aforementioned `ConnectButton` component. + +Additionally, for driving application-level interaction (after initial onboarding), `@particle-network/connectkit` provides a variety of hooks. You can explore all available hooks in the [Particle Connect SDK documentation](/api-reference/connect/desktop/web#key-react-hooks-for-particle-connect). + +:::note +The boilerplate application includes a basic example featuring only a **Connect** button (`ConnectButton`). +::: + +After logging in (connecting), users can access the embedded wallet modal provided by **Particle Connect** via the button in the bottom right corner, unless customized through the `wallet` configuration within `ConnectKitProvider`. + +Find an example of additional features like fetching and displaying user information, balances, on-ramp services, and sending transactions using either the native Particle Provider (Viem-based WalletClient) or ethers.js through an EIP-1193 provider from the [page.tsx](https://github.com/Particle-Network/particle-connectkit2.0-quickstart/blob/main/particle-connect/src/app/page.tsx) file in the demo repository. + +:::tip + A Next.js demo repository can be found on [GitHub](https://github.com/Particle-Network/particle-connectkit2.0-quickstart). +:::