Setup a dev environment for freeCodeCamp

Warning for Windows Users

This project only supports development on macOS or Linux systems such as Ubuntu.

• On Windows, install Windows Subsystem for Linux (WSL2) to create a Linux environment first and then follow this guide.
• We recommend using Windows Terminal to run your WSL2 environment for the best experience. Avoid using Command Prompt, Git Bash, or PowerShell.

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

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 or want the fastest setup, use GitHub Codespaces which provides a ready-to-code environment in your web browser using devcontainers. For long-term contributions where you prefer local development, you can set up freeCodeCamp on your local machine.

| Feature | GitHub Codespaces | Your own machine | | --------------------------- | ------------------------------------------------------ | ------------------------------------------------ | | Hardware requirements | No minimum hardware requirements | Powerful minimum hardware requirements | | Software installation | No need to install any software | Additional software needed | | Repository status | Always up-to-date repository | Manual updates required | | Setup complexity | Easy setup with devcontainers, works in any browser | Larger download and setup time | | Internet dependency | Requires an internet connection to work | Minimal internet connection required once set up | | Performance | Consistent cloud-based performance | Depends on your machine capabilities | | Usage limits | 60 hours free per month for personal accounts | No usage limits | | Environment consistency | Identical setup for all contributors via devcontainers | May vary between different machines and OS |

Once you have decided, follow the relevant tab below to continue with the setup.

GitHub Codespaces

GitHub Codespaces

We have automated the development environment setup using devcontainers. With GitHub Codespaces, you get a consistent, ready-to-code environment that runs in your browser with all dependencies pre-installed.

Launch a Codespace from your fork:

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

2. Click the green Code button

3. Select the Codespaces tab

4. Click Create codespace on main

   Your codespace will automatically set up the development environment using our devcontainer configuration. This includes:

   • Installing Node.js, pnpm, and all dependencies
   • Setting up MongoDB
   • Configuring VS Code extensions
   • Preparing the environment variables

5. Wait for the setup to complete (usually 2-3 minutes)

Local Machine

Here is a minimum system requirement for running freeCodeCamp locally:

System Requirements

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

Windows users: You will need more resources like memory and CPU than above, to allow running the project on Linux with WSL.

Start by installing the prerequisite software for your operating system.

Prerequisites:

| Prerequisite | Version | Notes | | --------------------------------------------------------------------------------------------- | ------- | ------------------------------------------------------------------------------------------- | | Node.js | 24.x | We use the “Active LTS” version, see LTS Schedule. | | pnpm | 10.x | - | | MongoDB Community Server | 8.0.x | - | | Docker Compose | 2.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

Now that you have a copy of freeCodeCamp, you can follow these instructions to run it. 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.

GitHub Codespaces

Your Codespace comes pre-configured with all dependencies installed and services like the database already running. You can start developing immediately:

1. In the terminal, run:

   pnpm run develop

   This will start both the API server and the client applications.

2. Wait for the process to complete. It can take a few minutes, you will see a notification to for the 8000 port when it’s ready.

3. Click on the notification to open the client application in a new browser tab.

Congratulations - you're all set!

You now have a copy of freeCodeCamp’s entire learning platform running in your Codespace. Go ahead and start making changes to the codebase.

Local Machine

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

Step 3: Start MongoDB and Seed the Database

Before you can run the application locally, you will need to start a MongoDB Server as a replica set.

1. Stop any existing MongoDB server that uses port 27017 (if you already have a replica set running on that port, you can skip this and the next step)

2. Start the MongoDB server as a replica set:

   docker compose -f docker/docker-compose.yml up -d

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

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

If you’re working on curriculum content, we strongly recommend using selective builds to significantly reduce build time. Set one of the following environment variables to build only what you need:

• FCC_SUPERBLOCK — build a single superBlock
• FCC_BLOCK — build a single block
• FCC_CHALLENGE_ID — build a single challenge by its ID

For example, to build only the Responsive Web Design superblock:

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

Or to build only the Basic HTML and HTML5 block:

FCC_BLOCK='basic-html-and-html5' pnpm run develop

To build the entire curriculum (only recommended for thorough testing):

pnpm run develop

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

http://localhost:8000

Congratulations - you're all set!

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/documentation.

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 default users and inserts them into MongoDB. | | FCC_SUPERBLOCK='responsive-web-design' pnpm run develop | Starts the API Server and Client, building only the specified SuperBlock (recommended for curriculum work). | | FCC_BLOCK='basic-html-and-html5' 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. |