Local Setup
Local setup (frontend)
This page tells a developer how to run the CROForge frontend on their own computer. Local setup means installing the tools, copying config, and starting a development server so you can click through the product at http://localhost:3000 without deploying anything.
Doc ID: dev.local-setup. Audience: developer.
Words used on this page
| Word | Everyday meaning | Meaning in CROForge |
|---|---|---|
| Node.js | A program that runs JavaScript on your computer, not only in a browser. | Runtime for the Next.js frontend. Required version: ≥ 20. |
| npm | The package installer that downloads libraries listed in package.json. | Required version: ≥ 10. Used for npm install and scripts like npm run dev. |
| Environment variable | A named setting kept outside the source code (like a sticky note: “API lives here”). | Values in .env.local such as API base URL and auth secrets. Never commit secrets. |
| Frontend | The screens people use. | This Next.js repo. Needs a running backend API for login and experiment APIs, and ideally init.js. |
| Backend | The server that stores data. | Must be running locally or remotely so auth, experiment APIs, and Smart Code compile/serve work. |
| API | The waiter between UI and database. | Base URL configured in .env.local. |
| Next.js | React framework with a built-in dev server. | npm run dev starts it; production uses build then start. |
| localhost | “This computer.” The browser talks to software on the same machine. | Open http://localhost:3000 after npm run dev. |
| PM2 | A process manager: it keeps a Node app running and restarts it if it crashes. | Optional for production-like runs. See root README.md and ecosystem.config.js. |
| ESLint | A spell-checker for code style and common bugs. | npm run lint runs the project’s Next.js ESLint config. |
Screenshot filename
Suggested screenshot filename: local-setup.png. Capture the terminal after a successful npm run dev plus the browser on http://localhost:3000. Insert the real image from the WordPress Media Library in place of this note.
Requirements
- Node.js ≥ 20 (the JavaScript runtime; check with
node -v) - npm ≥ 10 (the package manager; check with
npm -v) - Backend API running (auth + experiment APIs + ideally
init.js)
Steps
From a terminal, install dependencies, create a local env file, then start the dev server.
cd frontend
npm install
cp .env.local.example .env.local # if example exists
# edit .env.local with API base URL and secrets
npm run devOpen http://localhost:3000.
Scripts
A script is a named shortcut in package.json. You run it with npm run <name>.
| Script | Purpose |
|---|---|
npm run dev | Next.js development server (hot reload while you edit) |
npm run build | Production build (optimized files for real users) |
npm run start | Serve the production build (after build) |
npm run lint | ESLint (code-quality checks) |
PM2 (optional)
PM2 is not required for day-to-day coding. Use it when you want the Node process to stay up like a small production service. See the repo root README.md and ecosystem.config.js for process manager commands.
Environment
Configure the API base URL and auth-related variables in .env.local. That file is for your machine only—never commit secrets (passwords, tokens, private keys) to git.
Verify
If these four checks pass, local setup is working end to end.
- Register / login works.
- Create a workspace.
- Open the A/B list.
- Point a test HTML page at local/prod
init.jswith the workspace id.
