Learn NEAR Protocol smart contract development through interactive, hands-on coding examples.
NEAR by Building is a comprehensive, browser-based learning platform designed to teach developers how to build smart contracts on the NEAR Protocol blockchain. Whether you're a complete beginner or an experienced developer looking to explore NEAR, this platform provides an interactive environment where you can write, compile, deploy, and test smart contracts directly in your browser—no local development environment required.
- Features
- Learning Categories
- Getting Started
- Project Structure
- Development
- Contributing
- Code of Conduct
- License
- Live Code Editor: CodeMirror-based editor with syntax highlighting for Rust and TypeScript/JavaScript
- Instant Compilation: Backend servers compile your code in real-time with detailed error reporting
- TestNet Deployment: Deploy contracts directly to NEAR TestNet using wallet-based or CLI-based deployment
- Interactive Console: Real-time compilation and deployment feedback with transaction links to NEAR Explorer
- AI-Powered Assistance: Integrated AI assistant to explain code concepts (requires
VITE_GEMINI_API_KEY) - Function Testing: Test deployed contract methods directly from the interface
- Onboarding Tour: Guided walkthrough for first-time users
- Responsive Design: Modern UI built with Tailwind CSS
- Dark Mode: Optimized for extended coding sessions
| Category | Examples | Focus |
|---|---|---|
| Basics | 10 | Contract structure, view/change methods, state management |
| Access Control & Security | 5 | Owner patterns, RBAC, pausable contracts, upgrades |
| Collections & Data | 5 | Todo lists, profiles, voting, marketplaces, batch operations |
| NFTs | 7 | NEP-171, metadata, minting, royalties, marketplace |
| Cross-Contract | 5 | Simple calls, callbacks, FT/NFT cross-calls, chained calls |
| Chain Signatures | 6 | MPC signing, verification, multi-chain, callbacks |
| Indexing | 1 | NEP-297 events |
| Advanced Patterns | 1 | Unit testing |
- Node.js 18+
- npm, yarn, or pnpm
- NEAR TestNet wallet
# Clone the repository
git clone https://github.com/Learn-Near-AI/near-by-example.git
cd near-by-example
# Install dependencies
npm install
# Copy environment template (see Environment Variables below)
cp .env.example .env
# Start development server
npm run devOpen http://localhost:5173 and click "Get started" to browse examples.
npm run build
npm run preview # Preview production build- Copy
.env.exampleto.env:cp .env.example .env - Never commit
.env—it is in.gitignore. Never add API keys or secrets to the repo. - Use
.env.exampleas the template; it documents all optional variables without real values.
| Variable | Required | Description |
|---|---|---|
VITE_GEMINI_API_KEY |
No | Gemini API key for AI assistant. Omit to disable AI features. |
VITE_RUST_COMPILE_URL |
No | Override Rust compilation backend URL |
VITE_JS_COMPILE_URL |
No | Override JS/TS compilation backend URL |
VITE_DEPLOY_URL |
No | Override deployment backend URL |
src/
├── components/ # Reusable UI (Nav, Footer, dialogs, etc.)
├── config/ # Centralized configuration (URLs, links)
├── data/ # Static data (examples, constants)
├── features/ # Feature-specific modules
│ ├── examples/ # Examples browser, code editor, deployment
│ └── landing/ # Landing page sections
├── hooks/ # Custom React hooks
├── lib/ # Utilities, API clients, logger
├── near/ # NEAR blockchain integration
├── routes/ # Route definitions
└── test/ # Test setup
See docs/ARCHITECTURE.md for wallet and backend integration details.
| Pattern | Location | Purpose |
|---|---|---|
| Centralized config | src/config/ |
All URLs, env values—single source of truth |
| Feature modules | src/features/ |
Entry points for features (landing, examples) |
| Route definitions | src/routes/ |
All routes in one place for maintainability |
| API layer | src/near/ |
NEAR wallet, contract calls, RPC |
| Logging | src/lib/logger.js |
Use instead of console.* (debug suppressed in prod) |
- components/: Reusable UI (Nav, Footer, dialogs, patterns)
- features/: Composes components into feature entry points
- Single responsibility: each component does one thing
# Lint
npm run lint
# Fix lint issues
npm run lint:fix
# Format code
npm run format
# Check formatting
npm run format:check
# Run tests
npm run testSee CONTRIBUTING.md for the full guide, including the Content Review Checklist (correctness, no duplication, clear learning goal). Quick steps:
- Add example metadata to
src/data/examplesData.js - Add code samples to
src/data/exampleCode/ - Add to
WORKING_EXAMPLESinsrc/data/exampleCode/index.jsif fully implemented - Add explanation to
src/data/contractExplanations.js - Complete the Content Review Checklist in CONTRIBUTING.md before opening a PR
We welcome contributions! Please follow these steps:
- Fork the repository and create a feature branch
- Make changes with clear, focused commits
- Ensure quality:
- Run
npm run lintandnpm run format - Run
npm run test
- Run
- Submit a PR with a descriptive title and summary
For new or changed examples, complete the Content Review Checklist in CONTRIBUTING.md.
- Code follows project style (lint passes)
- Code is formatted (Prettier)
- Tests pass
- Documentation updated if needed
- Content Review Checklist completed (for new/changed examples)
Open an issue for questions or discussions.
We are committed to providing a welcoming and inclusive environment. By participating, you agree to:
- Use welcoming and inclusive language
- Be respectful of differing viewpoints and experiences
- Accept constructive criticism gracefully
- Focus on what is best for the community
- Show empathy towards others
Instances of abusive or harassing behavior may be reported to project maintainers and will be reviewed promptly.
This Code of Conduct is adapted from the Contributor Covenant, version 2.0.
MIT License — feel free to use this project for learning and teaching.
Built with ❤️ for the NEAR developer community