From 07fbbf50c0c2e2c738deb3263c823532c2212544 Mon Sep 17 00:00:00 2001
From: draycolix <draycolix@gmail.com>
Date: Tue, 23 Jun 2026 14:20:04 +0700
Subject: [PATCH] docs: add version constraint files (.nvmrc, .tool-versions) +
 env setup guide

Closes #579

Adds the following to address inconsistent environment setup:
- .nvmrc pinning Node 20 (matches @types/node ^20.9.0 devDependency)
- .tool-versions for asdf users pinning Node 20.18.0 + pnpm 10.33.0
- New 'Environment Setup' section in CONTRIBUTING.md explaining how to
  use these files with nvm/fnm/asdf and corepack for pnpm

Solana/Anchor versions intentionally not pinned here as they vary per
example. Users should check each example's Cargo.toml.

Refs the recurring Node 23 issues reported in #579 thread.

No code or test changes.
---
 .nvmrc          |  1 +
 .tool-versions  |  2 ++
 CONTRIBUTING.md | 36 ++++++++++++++++++++++++++++++++++++
 3 files changed, 39 insertions(+)
 create mode 100644 .nvmrc
 create mode 100644 .tool-versions

diff --git a/.nvmrc b/.nvmrc
new file mode 100644
index 000000000..2edeafb09
--- /dev/null
+++ b/.nvmrc
@@ -0,0 +1 @@
+20
\ No newline at end of file
diff --git a/.tool-versions b/.tool-versions
new file mode 100644
index 000000000..39a5985a1
--- /dev/null
+++ b/.tool-versions
@@ -0,0 +1,2 @@
+nodejs 20.18.0
+pnpm 10.33.0
\ No newline at end of file
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 7c401b4ba..76b767b6a 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -6,6 +6,42 @@ We believe that a welcoming and inclusive environment fosters collaboration and
 
 To ensure a smooth and effective contribution process, please take a moment to review and follow the guidelines outlined below.
 
+
+## Environment Setup
+
+To run the examples in this repository consistently across machines, use the version files at the repo root:
+
+| File | Purpose | Tool |
+|------|---------|------|
+| `.nvmrc` | Node.js version (20) | nvm / fnm / volta |
+| `.tool-versions` | Node.js + pnpm versions | asdf |
+
+**Quick setup:**
+
+```bash
+# Using nvm (Node Version Manager)
+nvm install    # reads .nvmrc
+nvm use
+
+# Or using fnm
+fnm install
+fnm use
+
+# Or using asdf
+asdf install
+
+# Install pnpm (required version pinned in package.json)
+corepack enable
+corepack prepare pnpm@10.33.0 --activate
+pnpm install
+```
+
+**Why these versions?**
+
+- **Node 20** — matches `@types/node: ^20.9.0` devDependency and avoids Node 23 issues reported in #579
+- **pnpm 10.33.0** — pinned via `packageManager` field in root `package.json`; consistent installs across machines
+
+**Solana / Anchor versions** vary per example. Check each example's `Cargo.toml` for the exact `anchor-lang` version required. Common versions in this repo: Anchor 0.30+, Solana 1.18+.
 ## How to Contribute
 
 We welcome contributions in the form of code, documentation, bug reports, feature requests, and other forms of feedback. Here are some ways you can contribute: