Setup a dev environment for freeCodeCamp

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

Windows users: read this first

This project supports macOS and Linux only. Set up WSL2 first, then follow this guide inside it. Use Windows Terminal — not Command Prompt, Git Bash, or PowerShell.

Fork the freeCodeCamp repository on GitHub

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

1. Open the fork page:

   Fork freeCodeCamp

2. Check the details, then click Create fork.

3. 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.

	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.

1. 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

2. 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.

3. (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	10.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

Versions matter

A version other than the one listed is the most common cause of a failed setup. See troubleshooting.

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

1. 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.

2. Install dependencies:

   pnpm install

   WSL users: run pnpm run playwright:install-build-tools first. It installs system packages that Playwright and Puppeteer need.

3. 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.

4. 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.

5. Start the client and the API:

   pnpm run develop

   A full curriculum build takes several minutes. Open http://localhost:8000 when it finishes.

Using your own MongoDB

If you run MongoDB outside Docker, point MONGOHQ_URL in .env at it. It must be a replica set.

Dev Container

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.

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

1. Open the folder in VS Code:

   code .

2. Open the Command Palette (Ctrl+Shift+P / Cmd+Shift+P), then select Dev Containers: Reopen in Container.

3. 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.

4. Open the Command Palette again, type Run Task, then select Start freeCodeCamp. Or open a terminal and run:

   pnpm run develop

5. Wait for the build. It takes several minutes the first time. Then open http://localhost:8000.

The first start is slow

The first start downloads a prebuilt image of several gigabytes. Later starts are fast.

GitHub Codespaces

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

1. Go to your fork at https://github.com/YOUR_USER_NAME/freeCodeCamp.

2. 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.

3. Wait for the setup to finish, then open a terminal and run:

   pnpm run develop

4. 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.

Keep port 3000 public

The client calls the API across two forwarded origins, so port 3000 must stay public or the browser reports a CORS error. The container sets this on every start, but if it still looks private, open the Ports panel, right-click port 3000, then choose Port Visibility > Public. Leave port 8000 private.

A public port is reachable by anybody who has the URL. Stop the codespace when you finish working.

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.

Congratulations — you're all set!

freeCodeCamp’s learning platform is now running. If anything failed, see troubleshooting.

Quick Commands Reference

Handy Scripts to use locally

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.