Your First Web3 App

Quick guide to create a Web3 frontend application with NEAR integration - build a React/Next.js app where users can login with wallets and interact with smart contracts.

In this guide we will show you how to build a React app connected to NEAR, where users can login using their wallets and interact with a contract.

[!TIP]

Searching to integrate NEAR in your App?

If you already have an application and want to integrate NEAR into it, we recommend you to first go through this guide and then check our documentation on integrating NEAR to a frontend

---

Template Setup

If you already have Node.js installed, you can use create-near-app to quickly setup a template:

  npx create-near-app@latest

  # ✔ What do you want to build? › Web Application
  # ✔ Select a framework for your frontend › Next.js (Classic)
  # ✔ Name your project (we will create a directory with that name) … near-template
  # ✔ Run 'npm install' now? … yes

Once the folder is ready - and all dependencies installed - you can start the development server using pnpm.

cd near-template # go to your project folder
npm run dev

Visit http://localhost:3000 in your browser to view the dApp. Note that since the dApp uses NextJS the app might take longer to load the pages on first visit.

[accordion] The app is not starting?

Make sure you are using Node.js 22.22.2 or newer. You can install and select Node.js 24 with nvm install 24 and nvm use 24.

[!TIP]

Framework In this tutorial we are using the Next.js framework with the "classic" page-based routing, but you can select other frameworks such as Vite when creating the app

---

Landing Page

Once the app starts you will see the landing page, rendering a navigation bar that allows users to login using their NEAR wallet. You can then navigate to the docs or the Near Integration page (which we will do).

Landing page of Hello NEAR Gateway

Go ahead and sign in with your NEAR account. If you don't have one, you can create one on the fly.

---

Context Provider

Next.js uses a template system, where each page is a React component. Our main logic is defined at ./src/pages/_app.tsx, which:

1. Creates a NearProvider that wraps the entire application to provide NEAR functionality
2. Renders the navigation menu and the page's content

import "@/styles/globals.css";

import type { AppProps } from "next/app";
import { Navigation } from "@/components/navigation";
import { NearProvider } from "@/providers/near-provider";

export default function App({ Component, pageProps }: AppProps) {
  return (
    <NearProvider>
      <Navigation />
      <Component {...pageProps} />
    </NearProvider>
  );
}

See code on GitHub

[accordion] How does the NEAR provider work?

The app defines its own NearProvider and useNearWallet hook in src/providers/near-provider.tsx. The provider uses @hot-labs/near-connect to manage wallet connections and sign transactions, and near-api-js to query the blockchain.

---

Navigation Bar

The navigation bar implements a button to allow users to login and logout with their NEAR wallet. It uses the local useNearWallet hook from @/providers/near-provider, which exposes the provider's wallet state and sign-in and sign-out functions.

import Image from 'next/image';
import Link from 'next/link';
import { useNearWallet } from '@/providers/near-provider';

import NearLogo from '../../public/near-logo.svg';

export const Navigation = () => {
   const { signedAccountId, loading, signIn, signOut } = useNearWallet();

  const handleAction = () => {
    if (signedAccountId) {
      signOut();
    } else {
      void signIn();
    }
  };

  const label = loading
    ? "Loading..."
    : signedAccountId
    ? `Logout ${signedAccountId}`
    : "Login";

  return (
    <nav className="navbar navbar-expand-lg">
      <div className="container-fluid">
        <Link href="/">
          <Image
            priority
            src={NearLogo}
            alt="NEAR"
            width={30}
            height={24}
            className="d-inline-block align-text-top"
          />
        </Link>
        <div className="navbar-nav pt-1">
          <button className="btn btn-secondary" onClick={handleAction}>
            {label}
          </button>
        </div>
      </div>
    </nav>
  );
};

See code on GitHub

---

How Do I Call Smart Contract Functions?

Now that you understand how the landing page works, we can move to the Near Integration page, which retrieves a greeting from the hello.near-examples.testnet contract.

Read vs. Write Operations

Operation Type	Method	Cost	Requires Signature
Read (view)	viewFunction()	Free	No
Write (call)	callFunction()	Gas fees (~0.0001 Ⓝ)	Yes

View methods query contract state without modifying it. Call methods change state and require the user to sign a transaction.

View of the Near Integration page

Login if you haven't done it yet and you will see a simple form that allows you to store a greeting in the smart contract.

---

Contract Functions

Just like the navigation bar, we use the app's local useNearWallet hook to get functions that allow us to call methods on the contract:

• viewFunction calls read-only methods through the near-api-js RPC provider
• callFunction calls methods that modify contract state through the connected wallet's signAndSendTransaction method

const { signedAccountId, viewFunction, callFunction } = useNearWallet();

See code on GitHub

Calling Read-Only Methods

For example, when we want to fetch the current greeting stored in the contract, we use viewFunction inside a useEffect hook:

useEffect(() => {
  viewFunction({ contractId: HelloNearContract, method: 'get_greeting' }).then((greeting) => setGreeting(greeting as string));
}, [viewFunction]);

See code on GitHub

Calling Change Methods

On the other hand, when the user submits a new greeting, we use callFunction to send a transaction to the contract:

const saveGreeting = () => {
  // Try to store greeting, revert if it fails
  callFunction({ contractId: HelloNearContract, method: 'set_greeting', args: { greeting: newGreeting } })
    .then(async () => {
      const greeting = (await viewFunction({ contractId: HelloNearContract, method: 'get_greeting' })) as string;
      setGreeting(greeting);
      setShowSpinner(false);
    });

  // Assume the transaction will be successful and update the UI optimistically
  setShowSpinner(true);
  setGreeting(newGreeting);
};

See code on GitHub

---

Common Questions

Do users need NEAR tokens to login?

No. Wallet login is free. Users only pay gas fees when they call contract functions that modify state.

What wallets can users connect with?

Users can choose from the NEAR wallets available in the NEAR Connect wallet selection modal.

How do I avoid users signing every transaction?

The template's local provider registers function-call-key-plugin with NEAR Connect to create a function-call access key scoped to the contract's set_greeting method. This allows the app to sign permitted non-payable calls automatically. See function-call keys at login for the setup.

Can I use this with an existing React app?

Yes. Install @hot-labs/near-connect and near-api-js and follow our integration guide.

Why Next.js instead of plain React?

Next.js is recommended but not required. You can use Vite/React, Vue, Svelte, or any framework. Check create-near-app templates for options.

---

Moving Forward

That's it for our quickstart tutorial. You have now seen a fully functional frontend that can talk with NEAR contracts and render Web3 components.