Set up a dev environment for freeCodeCamp | Contribute

This guide sets up a development environment for freeCodeCamp. Work through it once, in order.

Fork the freeCodeCamp repository on GitHub

A fork is your own copy of the codebase. You need one to contribute.

Open the fork page:

Fork freeCodeCamp
(opens in a new tab)
Check the details, then click Create fork.
GitHub redirects you to your fork at https://github.com/YOUR_USER_NAME/freeCodeCamp.

In this guide, origin means your fork and upstream means the main repository. You can delete your fork at any time and start again.

Choose where to run freeCodeCamp

There are three ways to run the project. All three work. Compare them, pick one, then follow that tab below.

Feature	Local Machine	Dev Container	GitHub Codespaces
Where it runs	Directly on your machine	In Docker, on your machine	On a GitHub server
You install	Node.js, pnpm, Docker Compose, Git	Docker Desktop, VS Code, Dev Containers extension, Git	Nothing
You manage tool versions	Yes	No. The image carries them	No. The image carries them
Machine needed	4 CPUs, 8 GB of RAM, 10 GB of disk	4 CPUs and 16 GB of RAM given to Docker, plus your own operating system on top	A 4-core, 16 GB, 32 GB disk machine. The project sets this minimum
Speed	Fastest	Slower file access on macOS and Windows	Depends on your connection
Works offline	Yes, after setup	Yes, after the first start	No
Cost	Free	Free	A free monthly quota, then paid

Each option gives you the same running application, so pick the one that fits your machine.

Clone your fork

Skip this section if you picked GitHub Codespaces — it clones your fork for you. You need Git installed first.

Clone your fork, replacing YOUR_USER_NAME with your GitHub username:

git clone --depth=1 https://github.com/YOUR_USER_NAME/freeCodeCamp.git
cd freeCodeCamp

Add a remote that points at the main repository, so you can sync later:
```
git remote add upstream https://github.com/freeCodeCamp/freeCodeCamp.git
```
Run git remote -v to confirm. You should see origin on your fork and upstream on freeCodeCamp/freeCodeCamp.
(Optional) To work on a localized curriculum, fetch the i18n-curriculum submodule:
```
git submodule update --init
```

Set up and run freeCodeCamp

Local machine prerequisites

Your machine needs 4 CPU cores, 8 GB of RAM and 10 GB of free disk space, on macOS or Linux.

Prerequisite	Version	Notes
Git	latest	The version bundled with your operating system is often outdated.
Node.js	`24.x`	The “Active LTS” version. See the LTS schedule.
pnpm	`12.x`	-
Docker Compose	`2.x`	Starts MongoDB for you below.
MongoDB Community Server	`8.x`	Optional. Only if you prefer to run MongoDB without Docker.

Check what you have:

node -v && pnpm -v

Recommended, but not required:

Set up an SSH key for GitHub.
Use a code editor. Visual Studio Code is free and open source.
Run ESLint in your editor. It flags anything that breaks freeCodeCamp’s JavaScript Style Guide.

Start the app

Create your environment file:
```
cp sample.env .env
```
The defaults run the app as it is. Change them only if you want your own Auth0, Algolia or Stripe keys.
Install dependencies:
```
pnpm install
```
WSL users: run pnpm run playwright:install-build-tools first. It installs system packages that Playwright and Puppeteer need.
Stop any MongoDB server already using port 27017, then start MongoDB as a replica set:
```
docker compose -f docker/docker-compose.yml -f docker/docker-compose.ports.yml up -d
```
This also starts Mailpit, which catches outgoing email at http://localhost:8025.
Seed the database:
```
pnpm run seed
```
This creates a test user with no completed certifications. For a user with certifications, run pnpm run seed:certified-user instead, then clear your browser cookies and sign in again.
Start the client and the API:
```
pnpm run develop
```
A full curriculum build takes several minutes. Open http://localhost:8000 when it finishes.

A dev container runs the same image as GitHub Codespaces, on your own machine. The image includes Node.js, pnpm and dependency caches. Container setup installs the project dependencies and starts MongoDB and Mailpit as separate services.

Dev container prerequisites

Prerequisite	Notes
Git	-
Docker Desktop	Any Docker Engine with Compose v2 works.
Visual Studio Code	-
Dev Containers extension	-

In Docker’s resource settings, give it at least 4 CPUs and 16 GB of memory. The client build needs a 7 GB heap, and Docker treats its memory setting as a hard limit.

Open and run the project

Open the folder in VS Code:
```
code .
```
Open the Command Palette (Ctrl+Shift+P / Cmd+Shift+P), then select Dev Containers: Reopen in Container.
Wait for the setup to finish. The terminal shows Done. Press any key to close the terminal. The container installs the dependencies, writes .env, starts MongoDB and Mailpit, and seeds the database for you.
Open the Command Palette again, type Run Task, then select Start freeCodeCamp. Or open a terminal and run:
```
pnpm run develop
```
Wait for the build. It takes several minutes the first time. Then open http://localhost:8000.

A codespace runs the project on a GitHub server. You install nothing, and you work in your browser or in VS Code.

Go to your fork at https://github.com/YOUR_USER_NAME/freeCodeCamp.
Click the green Code button, select the Codespaces tab, then click Create codespace on main.

Pick the 4-core, 16 GB RAM machine, or a larger one. The codespace then installs every dependency, starts MongoDB and Mailpit, seeds a test user, writes .env, and installs the ESLint and Prettier extensions.
Wait for the setup to finish, then open a terminal and run:
```
pnpm run develop
```
Wait for the build. It takes several minutes the first time. VS Code shows a notification for port 8000 when the client is ready — open it to view the client in a new browser tab.

After it starts

The API serves endpoints at http://localhost:3000, with docs at /documentation. In Codespaces, open these from the Ports panel.
Mailpit catches outgoing email at http://localhost:8025 (or the Ports panel in Codespaces).

Working on curriculum content? Build only the part you need. It is far faster:

FCC_SUPERBLOCK='responsive-web-design-v9' pnpm run develop

See Quick Commands Reference for FCC_BLOCK and FCC_CHALLENGE_ID.

Quick Commands Reference

Command	Description
`pnpm install`	Installs / re-installs all dependencies.
`pnpm run seed`	Creates authorized test users and inserts them into MongoDB. Also runs `seed:exams` and `seed:surveys` below.
`pnpm run seed:certified-user`	Creates authorized test users with certifications fully completed, and inserts them into MongoDB.
`pnpm run seed:exams`	Creates exams and inserts them into MongoDB.
`pnpm run seed:surveys`	Creates surveys for default users and inserts them into MongoDB.
`FCC_SUPERBLOCK='responsive-web-design-v9' pnpm run develop`	Starts the API Server and Client, building only the specified SuperBlock (recommended for curriculum work).
`FCC_BLOCK='workshop-curriculum-outline' pnpm run develop`	Starts the API Server and Client, building only the specified Block (recommended for curriculum work).
`FCC_CHALLENGE_ID=646cf6cbca98e258da65c979 pnpm run develop`	Starts the API Server and Client, building only the specified Challenge (recommended for curriculum work).
`pnpm run develop`	Starts the freeCodeCamp API Server and Client Applications with full curriculum build (for thorough testing).
`pnpm run clean`	Uninstalls all dependencies and cleans up caches.