Chapter 2: Setting Up the Development Environment for Thegraph

Installing Node.js, Yarn, Graph CLI

Here’s a friendly, step-by-step guide to setting up Node.js, Yarn, and the Graph Command Line Interface (CLI) on your computer.

1. Install Node.js

Node.js is a JavaScript runtime required for Yarn and the Graph CLI to function. Here’s how to install it:

Steps:

• Download Node.js:
  • Visit the official Node.js website: nodejs.org.
  • Download the “LTS” (Long-Term Support) version for stability (as of April 6, 2025, this is likely v20.x or higher).
  • Choose the installer for your operating system (Windows, macOS, or Linux).
• Install Node.js:
  • Windows/macOS: Run the downloaded .msi (Windows) or .pkg (macOS) file and follow the installation wizard.
  • Linux: Use a package manager like apt (Ubuntu/Debian) or yum (CentOS/RHEL): bash sudo apt update sudo apt install nodejs npm
  • Alternatively, use the Node Version Manager (nvm) for more flexibility: bash curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash nvm install --lts
• Verify Installation:
  • Open a terminal and run: bash
• node --version npm --version
  • You should see version numbers (e.g., v20.x.x for Node.js and 10.x.x for npm). If not, troubleshoot your installation.

2. Install Yarn

Yarn is a package manager that works with Node.js. It’s faster and more reliable than npm in many cases.

Steps:

• Install Yarn Globally:
  • Using npm (which comes with Node.js): bash npm install -g yarn
  • This installs Yarn globally so you can use it from any directory.
• Verify Installation:
  • Run: bash yarn --version
  • You should see a version number (e.g., 1.22.x for Yarn Classic or 3.x.x for Yarn Berry). If you get “command not found,” ensure your PATH includes the npm global binaries:
    • Windows: Add C:\Users\YourUsername\AppData\Roaming\npm to your PATH.
    • macOS/Linux: Add export PATH=”$HOME/.npm-global/bin:$PATH” to your shell profile (e.g., .bashrc, .zshrc).
• Optional: Use Yarn Berry (Modern Version):
  • If you want the latest Yarn version (Berry), enable it with: bash corepack enable yarn set version berry
  • Corepack comes with Node.js (v16.9.0+) and manages Yarn versions.

3. Install Graph CLI

The Graph CLI (@graphprotocol/graph-cli) is a tool for building and deploying subgraphs to The Graph, a decentralized protocol for indexing blockchain data.

Steps:

• Install Graph CLI Globally:
  • Using npm: bash npm install -g @graphprotocol/graph-cli
  • Or using Yarn: bash yarn global add @graphprotocol/graph-cli
• Verify Installation:
  • Run:
• bash

graph --version

• You should see a version number (e.g., 0.96.x as of early 2025). If not, ensure the global binaries are in your PATH (same as above).
• Optional: Install Locally in a Project:
  • If you prefer to manage Graph CLI per project:

mkdir my-graph-project
...

Creating and deploying a sample Hardhat smart contract (e.g., ERC-20)

Installing Graph CLI tools

It feels like you’re digging into tools for The Graph, especially the Graph CLI, which is perfect for crafting and launching subgraphs to pull in blockchain data. Given your earlier questions, I’m betting you’ve already got Node.js and npm ready to roll from that Node.js/Yarn/Graph CLI setup. Now, it seems you want to double-check that the Graph CLI and maybe some extra tools are all set up nicely. Sound about right?

Here’s a detailed guide to installing the Graph CLI and ensuring it’s ready for use, including optional related tools.

Step 1: Install Graph CLI

The Graph CLI (@graphprotocol/graph-cli) is the primary tool for creating, building, and deploying subgraphs.

Steps:

1. Install Globally with npm:
   • Run: bash npm install -g @graphprotocol/graph-cli
   • This installs the Graph CLI globally so you can use it from any directory.
2. Alternative: Install with Yarn (if you prefer Yarn):
   • Run: bash yarn global add @graphprotocol/graph-cli
3. Verify Installation:
   • Check the version: bash graph --version
   • As of April 6, 2025, you should see something like 0.96.x or higher. If you get “command not found,” ensure your PATH includes the global npm/Yarn binaries:
     • Windows: Add C:\Users\YourUsername\AppData\Roaming\npm to your PATH.
     • macOS/Linux: Add export PATH=”$HOME/.npm-global/bin:$PATH” to your shell profile (e.g., .bashrc, .zshrc), then restart your terminal.

Step 2: Optional – Install Locally in a Project

If you prefer managing the Graph CLI per project (e.g., for version control), you can install it locally:

1. Initialize a Project: bash mkdir my-subgraph cd my-subgraph npm init -y
2. Install Graph CLI Locally: bash npm install --save-dev @graphprotocol/graph-cli
3. Run Locally:
   • Use npx to run it: bash npx graph --version

Step 3: Additional Graph-Related Tools

The Graph ecosystem sometimes involves other tools for development, testing, or hosting. Here are some optional installations:

1. Graph Node (Local Development)

• Purpose: Run a local Graph Node to test subgraphs without deploying to the hosted service or decentralized network.
• Steps:
  • Requires Docker (install from docker.com).
  • Clone the Graph Node repo: bash git clone https://github.com/graphprotocol/graph-node.git cd graph-node/docker
  • Start the node with Docker Compose: bash docker-compose up
  • This sets up a local Graph Node with an Ethereum endpoint (e.g., a local Hardhat node or testnet).

2. Hardhat or Foundry (Blockchain Development)

• Since you’ve worked with Hardhat (from your ERC-20 question), it’s already useful for deploying contracts that your subgraph will index. No additional install is needed unless you want Foundry:
  • Foundry Install: bash curl -L https://foundry.paradigm.xyz | bash foundryup

3. Graph TS (TypeScript Support)

• Purpose: Adds TypeScript utilities for subgraph development.
• Install: bash npm install --save-dev @graphprotocol/graph-ts
• This is typically added to a subgraph project after initialization.

Step 4: Verify Setup with a Sample Subgraph

To ensure everything works, initialize a sample subgraph:

1. Initialize a Subgraph:
   • Run: bash graph init
   • Follow the prompts:
     • Choose a protocol (e.g., Ethereum).
     • Select a network (e.g., Sepolia or localhost).
     • Provide a contract address (e.g., your ERC-20 from earlier).
     • Name your subgraph (e.g., my-erc20-subgraph).
2. Build the Subgraph:
   • Inside the generated folder: bash graph codegen graph build
3. Deploy Locally (Optional):
   • With a local Graph Node running: bash graph deploy --node http://localhost:8020/ --ipfs http://localhost:5001 my-erc20-subgraph

Troubleshooting

• Command Not Found: Check your PATH or reinstall with –global.
• Permission Errors: Use sudo (Linux/macOS) or run your terminal as an administrator (Windows).
• Version Issues: Update with npm update -g @graphprotocol/graph-cli.

Authenticating with The Graph

Authenticating with The Graph depends on the context in which you’re interacting with it—whether you’re deploying a subgraph to the hosted service, querying a subgraph, or working with the decentralized network (mainnet). Below, I’ll cover the primary authentication methods as of April, 2025, focusing on the most common use case: deploying a subgraph using the Graph CLI to the hosted service. If you meant a different type of authentication (e.g., querying subgraphs or using the decentralized network), let me know, and I’ll adjust accordingly!

Authenticating with The Graph Hosted Service

The Graph Hosted Service (e.g., https://api.thegraph.com) requires an access token to deploy subgraphs via the Graph CLI. Here’s how to authenticate:

Step 1: Get an Access Token

1. Sign Up/Log In:
   • Go to thegraph.com/studio or thegraph.com/hosted-service.
   • Sign up or log in with your GitHub account (the hosted service uses GitHub for authentication).
2. Create an Access Token:
   • Navigate to the Dashboard.
   • Under your profile or settings, find the Access Token section (this might be labeled as “API Keys” or “Access Tokens”).
   • Generate a new token and copy it. It’ll look something like your-access-token-here (a long alphanumeric string).
   • Note: Keep this token secure; don’t share it publicly.

Step 2: Configure the Graph CLI

1. Set the Access Token:
   • Run the following command in your terminal, replacing your-access-token-here with the token you copied: bash graph auth --product hosted-service your-access-token-here
   • This command authenticates your CLI with the hosted service and stores the token locally (typically in ~/.graph/graphrc).
2. Verify Authentication:
   • There’s no direct “verify” command, but you can test it by deploying a subgraph (see Step 3). If the token is invalid, you’ll get an authentication error.

Step 3: Deploy a Subgraph

• Assuming you have a subgraph project set up (e.g., from your ERC-20 contract):
  • Navigate to your subgraph directory: bash cd my-erc20-subgraph
  • Deploy to the hosted service: bash graph deploy --product hosted-service your-github-username/my-subgraph-name
    • Replace your-github-username/my-subgraph-name with your GitHub username and desired subgraph name (e.g., johndoe/my-erc20-subgraph).
  • If authenticated correctly, the CLI will upload your subgraph, and you’ll get a success message with a URL (e.g., https://api.thegraph.com/subgraphs/name/your-github-username/my-subgraph-name).

Alternative: Authenticating with The Graph Studio (Decentralized Network)

If you’re deploying to The Graph’s decentralized network (mainnet) via Graph Studio instead of the hosted service, the process differs slightly:

Step 1: Set Up Graph Studio

1. Access Graph Studio:
   • Go to thegraph.com/studio.
   • Connect your Ethereum wallet (e.g., MetaMask) with some ETH and GRT (Graph Token) on mainnet.
2. Get an API Key:
   • In Graph Studio, create a new subgraph or manage an existing one.
   • Generate an API Key for querying or deploying (this is separate from the hosted service token).
   • Copy the API key.

Step 2: Authenticate CLI

• Use the Studio-specific authentication: bash graph auth --studio your-api-key
  • Replace your-api-key with the key from Graph Studio.

Step 3: Deploy to Decentralized Network

• Deploy your subgraph: bash graph deploy --studio my-subgraph-name
  • You’ll need GRT to pay for indexing and querying on the decentralized network. Ensure your wallet has sufficient funds.

Querying Subgraphs (No CLI Authentication Needed)

If you’re only querying a subgraph (not deploying), authentication isn’t always required:

• Hosted Service: Public subgraphs can be queried without authentication using the subgraph’s endpoint (e.g., via GraphQL in a tool like Postman or code).
• Studio: Queries may require an API key in the HTTP headers:httpAuthorization: Bearer your-api-key

Troubleshooting

• “Authentication Failed”: Double-check your access token or API key. Regenerate it if necessary.
• “Permission Denied”: Ensure your GitHub username matches the account tied to the token.
• Token Not Found: If graph auth didn’t save properly, manually edit ~/.graph/graphrc to include: yaml access_token: your-access-token-here

That’s how you authenticate with The Graph using the Graph CLI.