Frontend & Website Development Setup

Get started with frontend and docs development—much simpler than backend setup!

This guide covers setting up development environments for:

The explorer frontend (TypeScript/React) — the UI served at xdcscan.io
The documentation website (Astro/MDX) — the site you’re reading now

Prerequisites

Node.js 18+ (22 LTS recommended)
A package manager: npm, pnpm, or yarn
Git

No database, no chain node, no Elixir toolchain required.

Explorer frontend setup

git clone https://github.com/OpenScanAI/frontend.git
cd frontend
cp .env.example .env.local
npm install
npm run dev

Point the frontend at any API instance in .env.local:

NEXT_PUBLIC_API_HOST=xdcscan.io
NEXT_PUBLIC_API_BASE_PATH=/api/v2

The dev server runs at http://localhost:3000 with hot reload. Using the public xdcscan.io API as the data source lets you develop UI features without running a backend.

Frontend scripts

npm run dev        # dev server with hot reload
npm run build      # production build
npm run lint       # ESLint
npm run typecheck  # TypeScript checks
npm run test       # unit tests

Documentation website setup

These docs live in an Astro site with content collections in src/content:

git clone https://github.com/OpenScanAI/OSWeb.git
cd OSWeb
npm install
npm run dev

The dev server runs at http://localhost:4321. Docs pages are Markdown/MDX files under src/content/Docs — edit a file, save, and the page reloads.

Docs scripts

npm run dev              # dev server
npm run build            # production build (catches broken content)
npm run astro -- check   # type and accessibility checks
npx prettier . --write   # format before opening a PR

Typical frontend contribution workflow

Find or file an issue describing the UI change.
Reproduce against the public API — use xdcscan.io/api-docs to inspect real response shapes.
Build the change behind the existing design system: reuse components and Tailwind tokens rather than introducing new ones.
Add tests for new logic (rendering counts, formatting, pagination state).
Screenshot the change for the PR description — UI PRs without screenshots get bounced.

Typical docs contribution workflow

Edit the .md/.mdx file for the page.
Keep frontmatter intact (title, description, weight).
Verify code examples actually run against the public API.
Run npx prettier . --write and npm run astro -- check.
Open the PR — see the Documentation Guide for style rules.

Troubleshooting

API calls fail in the frontend dev server — check NEXT_PUBLIC_API_HOST and CORS; the public API allows browser requests from localhost.
Astro build fails on a docs page — usually an MDX syntax issue (unescaped < or { outside code blocks) or a frontmatter YAML error; the error message names the file.
Port already in use — npm run dev -- --port 3001 (frontend) or -- --port 4322 (docs).