Setup a dev environment for freeCodeCamp

Follow these guidelines for setting up a development environment for freeCodeCamp. This is highly recommended if you want to contribute regularly.

Warning for Windows Users

• You can’t build and run the codebase on Windows, you will need to use WSL2 and then follow the rest of the instructions for Linux or macOS.
• You can’t use Windows Command Prompt, Git Bash or PowerShell.
• The hardware requirements need to be better than what we recommend to accommodate for a WSL-based setup.

Fork the freeCodeCamp repository on GitHub

You will need to fork the freeCodeCamp repository on GitHub to get your own copy of the codebase. This will allow you to follow a Git-based workflow to contribute to freeCodeCamp.

Follow these steps to fork the repository:

1. Click the button below to fork the freeCodeCamp repository on GitHub.

   Fork freeCodeCamp

2. On the create new fork page, check the details and click the Create fork button.

3. You should automatically be redirected to your fork, the URL should be something like https://github.com/YOUR_USER_NAME/freeCodeCamp.

That’s it! You have successfully forked the freeCodeCamp repository. You can always delete your fork if you want to start fresh.

Did you know?

The main repository at https://github.com/freeCodeCamp/freeCodeCamp is often referred to as the upstream repository. Your fork at https://github.com/YOUR_USER_NAME/freeCodeCamp is often referred to as the origin repository.

Cloud IDE or your own machine?

Next, you need to choose between setting up a cloud IDE or your own machine.

If you’re looking to make a one-time contribution, use Gitpod, GitHub Codespaces, or another cloud-based IDE to make changes. Gitpod sets up a ready-to-code environment in just a few minutes in your web browser. For long-term contributions, we recommend setting up freeCodeCamp on your local machine.

Cloud IDE (Gitpod, CodeSpaces, etc.) Recommended

Pros:

• No minimum hardware requirements.
• No need to install any software.
• Always up-to-date repository.
• Easy to setup, you only need a browser—including mobile browsers.

Cons:

• Requires an internet connection to work.
• Limited free usage—50 hours or so.

Your own machine (local setup)

Pros:

• Quicker to make changes and see them live (depending on machine capabilities).
• Minimal internet connection required once set up.

Cons:

• Powerful minimum hardware requirements.
• Additional software needed.
• Larger download and setup time.

How to prepare a Cloud IDE

Note

Skip to how to prepare your local machine if you are not interested in using a cloud IDE.

Gitpod

We have automated the process of installing all the dependencies & tools you will need. With Gitpod you get a free ready-to-code environment in a few minutes, and is useful if you do not have access to a computer or want to make one-time changes.

There are various ways to launch a Gitpod workspace:

1. Prepend gitpod.io/# in front of any URL from GitHub.

   Visit your fork at https://github.com/YOUR_USER_NAME/freeCodeCamp.git add gitpod.io/# in the front of the URL in the address bar and hit enter.

   In summary, go to

   gitpod.io/#https://github.com/YOUR_USER_NAME/freeCodeCamp.git

   and you should see a workspace created for you. This works for any repository or pull-request on GitHub.

2. Alternatively install one of the below extensions for your browser.

   • Chrome Webstore - works with Chromium-based browsers like Google Chrome, Brave, Edge, etc.
   • Firefox Add-on - Firefox

   Once installed you will see a ‘Gitpod’ button on every repository, pull-request, etc. as a handy shortcut to launch a workspace from there. See the extension page for details, screenshots, etc.

GitPod is ready!

That’s it, you can now skip to the syncing up from parent section after you have launched a Gitpod workspace.

Most parts of this guide applies to Gitpod workspaces, make sure to check the troubleshooting section for any gotchas.

How to prepare your local machine

Note

Skip to how to prepare a cloud IDE if you are not interested in setting up a local machine.

System Requirements

Here is a minimum system requirement for running freeCodeCamp locally:

• A fast CPU (4+ cores)
• At least 8 GB RAM
• macOS, Linux or Windows 10 or 11 (with WSL)
• 8-10 GB of free disk space
• (Optional) 30-50 Mbps internet connection

We primarily support development on Linux and Unix-based systems like Ubuntu and macOS. You can develop on Windows 10 or 11 with WSL2 only. You can follow this guide to set up WSL2. You can’t use Command Prompt, Git Bash or PowerShell to run freeCodeCamp natively within windows.

Start by installing the prerequisite software for your operating system.

Prerequisites:

Prerequisite	Version	Notes
Node.js	20.x	We use the “Active LTS” version, see LTS Schedule.
pnpm	9.x	-
MongoDB Community Server	6.0.x	-

Did you check the version?

If you have a different version of a requisite software, please install the recommended version. See the troubleshooting section for more details.

Run the following commands to validate the versions:

node -v

pnpm -v

Once you have the prerequisites installed, you need to prepare your development environment. This is common for many development workflows, and you will only need to do this once.

Additional Prerequisites:

1. Install Git or your favorite Git client, if you haven’t already. Update to the latest version; the version that came bundled with your OS may be outdated.

2. (Optional but recommended) Set up an SSH Key for GitHub.

3. Install a code editor of your choice. If you aren’t sure which one to use, we recommend Visual Studio Code — it’s free and open source.

4. Set up linting for your code editor.

   You should have ESLint running in your editor, and it will highlight anything that doesn’t conform to freeCodeCamp’s JavaScript Style Guide.

   Pay Attention to errors

   Please do not ignore any linting errors. They are meant to help you and to ensure a clean and simple codebase.

Clone your Fork from GitHub

You should already have a fork of freeCodeCamp on GitHub. If not, follow these instructions to fork the repository. Next, you will need to clone your fork to your local machine.

Run these commands on your local machine:

1. Open a terminal in your projects directory, for example:

   /home/username/projects/

2. Clone your fork of freeCodeCamp, replacing YOUR_USER_NAME with your GitHub Username

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

   This will download the entire freeCodeCamp repository to your projects directory.

   Note

   --depth=1 creates a shallow clone of your fork, with files from the most recent history/commit.

3. (Optional) The localized versions of our curriculum are stored in the i18n-curriculum repo. If you intend to run a localized version of the curriculum follow the next steps, or skip to the next section.

   Clone the i18n-curriculum submodule:

   cd freeCodeCamp

   git submodule update --init

Set up Syncing from Parent

Now that you have downloaded a copy of your fork, you will need to set up an upstream remote to the parent repository.

As mentioned earlier, the main repository is referred to as the upstream repository. Your fork is referred to as the origin repository.

You need a reference from your local clone to the upstream repository in addition to the origin repository. This is so that you can sync changes from the main repository without the requirement of forking and cloning repeatedly.

1. Change the directory to the new freeCodeCamp directory if you aren’t already there:

   cd freeCodeCamp

2. Add a remote reference to the main freeCodeCamp repository:

   git remote add upstream https://github.com/freeCodeCamp/freeCodeCamp.git

3. Ensure the configuration looks correct:

   git remote -v

   The output should look something like below (replacing YOUR_USER_NAME with your GitHub username):

   origin    https://github.com/YOUR_USER_NAME/freeCodeCamp.git (fetch)
   origin    https://github.com/YOUR_USER_NAME/freeCodeCamp.git (push)
   upstream    https://github.com/freeCodeCamp/freeCodeCamp.git (fetch)
   upstream    https://github.com/freeCodeCamp/freeCodeCamp.git (push)

Running freeCodeCamp Locally

Now that you have a local copy of freeCodeCamp, you can follow these instructions to run it locally. This will allow you to:

• Preview edits to pages as they would appear on the learning platform.
• Work on UI related issues and enhancements.
• Debug and fix issues with the application servers and client apps.

Step 1: Set up the Environment Variable File

The default API keys and environment variables are stored in the file sample.env. This file needs to be copied to a new file named .env that is accessed dynamically during the installation step.

cp sample.env .env

The keys in the .env file are not required to be changed to run the app locally. You can leave the default values copied over from sample.env as-is.

Note

Keep in mind if you want to use services like Auth0 or Algolia, you’ll have to acquire your own API keys for those services and edit the entries accordingly in the .env file.

Step 2: Install Dependencies & Shared Config

Install the dependencies and set up shared configuration for services.

pnpm install

pnpm run create:shared

Step 3: Start MongoDB and Seed the Database

Before you can run the application locally, you will need to start the MongoDB Server.

1. Start the MongoDB server in a separate terminal:

   mongod

   If you kill this terminal session, the MongoDB server will stop.

2. Seed the database and setup a new user:

   MongoDB URI

   The default should be fine for most users. If you are using a custom config, modify the MONGOHQ_URL in the .env file as needed.

   pnpm run seed

   This will set up a new user without any completed certifications among other things. This is usually more than enough to get you started.

3. (Optional) Setup a user with completed certifications:

   pnpm run seed:certified-user

   This comes handy with advanced debugging or creating tests for the platform.

   Clear the cookies

   You will have to clear your browser cookies and sign in again after seeding the certified user.

Notes on the Database

Install MongoDB as a background service

You can avoid having to start MongoDB every time by installing it as a background service. You can learn more about it in their documentation for your OS.

Step 4: Start the Client App and API Server

You can now start up the API server and the client applications.

pnpm run develop

Once ready, open a web browser and visit: http://localhost:8000

http://localhost:8000

Congratulations - you're all set!

If the app loads, sign in. You now have a copy of freeCodeCamp’s entire learning platform running on your local machine. Go ahead and start making changes to the codebase.

Some notes:

• The API server serves endpoints at http://localhost:3000.
• The Gatsby app serves the client application at http://localhost:8000.
• All the APIs are available at http://localhost:3000/explorer.

Note

If you have issues with the setup, check out the troubleshooting section.

Quick Commands Reference

Handy Scripts to use locally

Command	Description
pnpm install	Installs / re-installs all dependencies and bootstraps the different services.
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 defaults users and inserts them into MongoDB.
pnpm run develop	Starts the freeCodeCamp API Server and Client Applications.
pnpm run clean	Uninstalls all dependencies and cleans up caches.