> ## Documentation Index
> Fetch the complete documentation index at: https://docs.near.org/llms.txt
> Use this file to discover all available pages before exploring further.

# 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.

export const Github = ({url, start, end, fname, language, withSourceLink = true}) => {
  const [code, setCode] = useState(null);
  function toRaw(ref) {
    const fullUrl = ref.slice(ref.indexOf('https'));
    const [url] = fullUrl.split('#');
    const [org, repo, , branch, ...pathSeg] = new URL(url).pathname.split('/').slice(1);
    return `https://raw.githubusercontent.com/${org}/${repo}/${branch}/${pathSeg.join('/')}`;
  }
  async function fetchCode(url, fromLine, toLine) {
    let res;
    if (typeof window !== 'undefined') {
      const validUntil = localStorage.getItem(`${url}-until`);
      if (validUntil && Number(validUntil) > Date.now()) {
        res = localStorage.getItem(url);
      }
    }
    if (!res) {
      try {
        res = await (await fetch(url)).text();
        if (typeof window !== 'undefined') {
          localStorage.setItem(url, res);
          localStorage.setItem(`${url}-until`, String(Date.now() + 60000));
        }
      } catch {
        return 'Error fetching code, please try reloading';
      }
    }
    let body = res.split('\n');
    const from = fromLine ? Number(fromLine) - 1 : 0;
    const to = toLine ? Number(toLine) : body.length;
    body = body.slice(from, to);
    const precedingSpace = body.reduce((prev, line) => {
      if (line.length === 0) return prev;
      const spaces = line.match(/^\s+/);
      if (spaces) return Math.min(prev, spaces[0].length);
      return 0;
    }, Infinity);
    return body.map(line => line.slice(precedingSpace === Infinity ? 0 : precedingSpace)).join('\n');
  }
  function buildSourceUrl(url, start, end) {
    const base = url.split('#')[0];
    if (start && end) return `${base}#L${start}-L${end}`;
    if (start) return `${base}#L${start}`;
    return base;
  }
  useEffect(() => {
    const rawUrl = toRaw(url);
    fetchCode(rawUrl, start, end).then(res => setCode(res));
  }, [url, start, end]);
  const sourceUrl = buildSourceUrl(url, start, end);
  const fileName = fname ?? sourceUrl.split('/').pop();
  return <div className="my-5">
      {code === null ? <div>Loading...</div> : <CodeBlock language={language} filename={fileName} lines>
          {code}
        </CodeBlock>}
      {withSourceLink && <div className="flex justify-end" style={{
    marginTop: "-1rem"
  }}>
          <a href={sourceUrl} target="_blank" rel="noreferrer noopener" className="text-[0.6875rem] font-medium text-[#656d76] no-underline hover:text-[#1f2328] dark:text-[#8b949e] dark:hover:text-[#e6edf3]">
            See code on GitHub
          </a>
        </div>}
    </div>;
};

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](./tutorials/wallet-login)
</Tip>

***

## Template Setup

If you already have [Node.js](https://nodejs.org/en/download) installed, you can use `create-near-app` to quickly setup a template:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
  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`.

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
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 title="The app is not starting?">
  Make sure you are using **node >= v22**, you can easily switch versions using `nvm use 22`
</Accordion>

<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
</Tip>

***

## 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).

<img src="https://mintcdn.com/neardocs/qO2GD-gji1aakHqN/assets/docs/smart-contracts/tutorials/examples/hello-near-landing-page.png?fit=max&auto=format&n=qO2GD-gji1aakHqN&q=85&s=957eef6d01b0d644c07877537068ab6e" alt="img" width="1889" height="850" data-path="assets/docs/smart-contracts/tutorials/examples/hello-near-landing-page.png" />

*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.

<hr className="subsection" />

### Context Provider

[Next.js](https://nextjs.org/) uses a template system, where each page is a React component. Our main logic is defined at `./src/pages/_app.js`, which:

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

<Github url="https://github.com/near-examples/hello-near-examples/blob/main/frontend/src/pages/_app.tsx" language="jsx" />

<Accordion title="What is NEAR Connect Hooks?">
  NEAR Connect is a library that allows users to select their preferred NEAR wallet to login, our application uses **hooks** that wrap its functionality to make it easier to use
</Accordion>

<hr className="subsection" />

### Navigation Bar

The navigation bar implements a button to allow users to `login` and `logout` with their NEAR wallet. The main logic comes from the `useNearWallet` hook, which exposes all wallet related functionality.

<Github url="https://github.com/near-examples/hello-near-examples/blob/main/frontend/src/components/navigation.tsx" language="jsx" />

***

## 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](https://testnet.nearblocks.io/address/hello.near-examples.testnet) contract.

### Read vs. Write Operations

| Operation Type   | Method         | Cost                  | Requires Signature |
| ---------------- | -------------- | --------------------- | ------------------ |
| **Read (view)**  | `viewMethod()` | Free                  | No                 |
| **Write (call)** | `callMethod()` | 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.

<img src="https://mintcdn.com/neardocs/qO2GD-gji1aakHqN/assets/docs/smart-contracts/tutorials/examples/hello-near-gateway.png?fit=max&auto=format&n=qO2GD-gji1aakHqN&q=85&s=04194370abe18860993bc7f0e35cd368" alt="img" width="1910" height="912" data-path="assets/docs/smart-contracts/tutorials/examples/hello-near-gateway.png" />

*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.

<hr className="subsection" />

### Function Call Hooks

Just like the [navigation bar](#navigation-bar), we use the `useNearWallet` hook to get functions that allow us to call methods on the contract:

* `viewFunction` is used to call functions that are read-only
* `callFunction` is used to call functions that modify the state of the contract

<Github url="https://github.com/near-examples/hello-near-examples/blob/main/frontend/src/pages/hello-near/index.tsx" language="jsx" start="11" end="11" />

#### 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:

<Github url="https://github.com/near-examples/hello-near-examples/blob/main/frontend/src/pages/hello-near/index.tsx" language="jsx" start="17" end="19" />

#### Calling Change Methods

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

<Github url="https://github.com/near-examples/hello-near-examples/blob/main/frontend/src/pages/hello-near/index.tsx" language="jsx" start="25" end="37" />

***

## 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?

NEAR wallets (MyNearWallet, Meteor, HERE Wallet) and Ethereum wallets (Metamask, WalletConnect, Coinbase Wallet via EVM support).

### How do I avoid users signing every transaction?

Create a **function-call access key** by setting `createAccessKeyFor: <contract-name>` in the wallet selector config. This allows the app to sign non-payable methods automatically.

### Can I use this with an existing React app?

Yes. Install `near-connect-hooks` and follow our [integration guide](./tutorials/wallet-login).

### 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.