Skip to content

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.

Fork the freeCodeCamp repository on GitHub

Section titled “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.

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.

FeatureGitHub Codespaces RecommendedYour own machine
Hardware requirementsNo minimum hardware requirementsPowerful minimum hardware requirements
Software installationNo need to install any softwareAdditional software needed
Repository statusAlways up-to-date repositoryManual updates required
Setup complexityEasy setup with devcontainers, works in any browserLarger download and setup time
Internet dependencyRequires an internet connection to workMinimal internet connection required once set up
PerformanceConsistent cloud-based performanceDepends on your machine capabilities
Usage limits60 hours free per month for personal accountsNo usage limits
Environment consistencyIdentical setup for all contributors via devcontainersMay vary between different machines and OS

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

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)

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.

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:

    Terminal window
    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.

Handy Scripts to use locally

CommandDescription
pnpm installInstalls / re-installs all dependencies and bootstraps the different services.
pnpm run seedCreates authorized test users and inserts them into MongoDB. Also runs seed:exams and seed:surveys below.
pnpm run seed:certified-userCreates authorized test users with certifications fully completed, and inserts them into MongoDB.
pnpm run seed:examsCreates exams and inserts them into MongoDB.
pnpm run seed:surveysCreates surveys for default users and inserts them into MongoDB.
pnpm run developStarts the freeCodeCamp API Server and Client Applications.
pnpm run cleanUninstalls all dependencies and cleans up caches.