DEV Community

Cover image for Getting Started with Genji: A Web3 App Starter with Passkey Authentication
Julien Béranger
Julien Béranger

Posted on

Getting Started with Genji: A Web3 App Starter with Passkey Authentication

#w3pk #web3 #passkey #ethereum

Hello Anon!

Genji is a Next.js starter template that makes it easy to build Web3 apps with passkey authentication. This template gives you a production-ready foundation that handles security and accessibility while keeping user privacy front and center.

What's in it?

Genji integrates the following technologies:

  • w3pk — Passkey authentication framework
  • Next.js — React framework for production apps
  • Ethers — Web3 library for blockchain interaction
  • Chakra UI — Component library for user interface
  • WCAG 2.1 AA compliance — Ensures accessibility for everyone

Check out the live demo at https://genji.w3hc.org.

Privacy-Friendly Architecture

Genji takes a privacy-first approach to authentication:

  • No password storage: Passkeys eliminate the need for password databases, removing a common attack vector
  • Device-bound credentials: Authentication credentials stay on the user's device and are never sent to servers
  • No tracking: No need for email addresses, phone numbers, or other personally identifiable information
  • User control: Users stay in full control of their credentials and can revoke access anytime
  • Minimal data collection: The app only stores the public key for each account, keeping things private while staying secure

Installation and Setup

Step 1: Create Your Repository

To create your own instance of the Genji template:

  1. Head to the Genji GitHub repository
  2. Click "Use this template" to create a new repository
  3. Give your repository a name

Step 2: Customize the Template

After cloning your repository, run the customization script:

pnpm customize
Enter fullscreen mode Exit fullscreen mode

This script will:

  • Remove default Genji branding
  • Set up project-specific configurations
  • Self-destruct when it's done

Step 3: Install Dependencies

Install the required packages:

pnpm i
Enter fullscreen mode Exit fullscreen mode

Step 4: Start the Development Server

Fire up the dev server:

pnpm dev
Enter fullscreen mode Exit fullscreen mode

Your app will be running at http://localhost:3000.

Now log in and try signing a message on the homepage. Once you're logged in, you don't need to confirm anything to sign the message: w3pk handles it seamlessly using your passkey-derived wallet.

Step 5: Configure Security Level

w3pk offers four security levels for passkey authentication. We recommend STANDARD, which balances security and user experience:

  • PRIMARY: Requires authentication for every single action, including transaction confirmations. Maximum security but requires the most user interaction.
  • STRICT: Requires authentication for most operations. Good for high-security apps where user inconvenience is acceptable.
  • STANDARD (recommended): Requires authentication for login but keeps the session active for what comes next. Users don't need to re-authenticate for each transaction. This gives you the best balance between security and usability for most apps.
  • YOLO: Minimal authentication requirements. Only for development or low-stakes apps where security isn't a primary concern.

STANDARD is recommended because it cuts out repeated authentication while keeping solid security controls. Users can interact with your app smoothly without compromising account security.

There are a few app examples here if you need some inspiration. Genji can be used for all kinds of apps.

Understanding Passkey Authentication

Passkeys are a modern authentication standard that use device-level security like biometric sensors (Face ID, fingerprint) or device PINs. This approach gets rid of traditional password management and seed phrase storage. The authentication process relies on public-key cryptography, where the private key stays securely on the user's device and is never transmitted.

Best Practices

  • Documentation: Check out the /docs folder for implementation context and design guidelines
  • Build Verification: Set up w3pk build verification to ensure code integrity
  • Security Inspection: Enable security inspection so your users can verify what's happening in your app
  • Accessibility: Keep WCAG 2.1 AA compliance throughout development

Support and Resources

Need help?

Conclusion

You now have everything you need to build Web3 apps using the Genji template with passkey authentication. The template gives you a privacy-focused, accessible, and secure foundation for building modern decentralized apps.

Top comments (0)