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
Follow these guidelines for setting up a development environment for freeCodeCamp. This is highly recommended if you want to contribute regularly.
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:
Click the button below to fork the freeCodeCamp repository on GitHub.
Fork freeCodeCamp
On the create new fork page, check the details and click the Create fork button.
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.
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.
Pros:
Cons:
Pros:
Cons:
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:
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
and you should see a workspace created for you. This works for any repository or pull-request on GitHub.
Alternatively install one of the below extensions for your browser.
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.
System Requirements
Here is a minimum system requirement for running freeCodeCamp locally:
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.
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 | - |
Run the following commands to validate the versions:
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.
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.
(Optional but recommended) Set up an SSH Key for GitHub.
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.
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.
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:
Open a terminal in your projects directory, for example:
Clone your fork of freeCodeCamp, replacing YOUR_USER_NAME
with your GitHub Username
This will download the entire freeCodeCamp repository to your projects directory.
(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:
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.
Change the directory to the new freeCodeCamp directory if you aren’t already there:
Add a remote reference to the main freeCodeCamp repository:
Ensure the configuration looks correct:
The output should look something like below (replacing YOUR_USER_NAME
with your GitHub username):
Now that you have a local copy of freeCodeCamp, you can follow these instructions to run it locally. This will allow you to:
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.
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.
Install the dependencies and set up shared configuration for services.
Before you can run the application locally, you will need to start the MongoDB Server.
Start the MongoDB server in a separate terminal:
If you kill this terminal session, the MongoDB server will stop.
Seed the database and setup a new user:
This will set up a new user without any completed certifications among other things. This is usually more than enough to get you started.
(Optional) Setup a user with completed certifications:
This comes handy with advanced debugging or creating tests for the platform.
Notes on the Database
You can now start up the API server and the client applications.
Once ready, open a web browser and visit: http://localhost:8000
http://localhost:8000
Some notes:
http://localhost:3000
.http://localhost:8000
.http://localhost:3000/explorer
.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. |