freeCodeCamp.org is a friendly community where you can learn to code for free. It is run by a donor-supported 501(c)(3) nonprofit to help millions of busy adults transition into tech. Our community has already helped more than 40,000 people get their first developer job. Our full-stack web development and machine learning curriculum is completely free and self-paced. We have thousands of interactive coding challenges to help you expand your skills.

A self-hosted solution to help teachers plan and manage classroom-based learning, on top of freeCodeCamp's learning platform.

For a while now teachers have been asking for a way to get a birds eye view of multiple students who are progressing through the course. This is why we set out to make freeCodeCamp classroom mode, an interactive dashboard for teachers to view multiple freeCodeCamp users’ progress on their courses.

If you have used GitHub Codespaces in other projects, doing the same in freeCodeCamp Classroom should be straightforward.

• https://docs.github.com/en/codespaces/overview

• https://docs.github.com/en/codespaces/getting-started

• If you want a ready-made dev environment in your browser, make a fork of this repository.

• Afterward, set up your NextAuth-related environment variables in the .env file.

• Please follow the "Setup Instructions" in the terminal for more information.

Within freeCodeCamp Classroom, GitHub Codespaces is on par with Gitpod so that you can use either.

This video walks through the setup process on Github Codespaces. Note that this video was recorded on Feb 10, 2025. It is not guaranteed to be up to date with any new setup instructions added after that date.

If you want a ready-made dev environment in your browser, make a fork of this repository and then prefix your fork with "gitpod.io/#". For example,

gitpod.io/#https://github.com/{your-github-user-name}/classroom

You will still need to setup your NextAuth-related environment variables in the .env file. For more information, please follow the "Setup Instructions" in the terminal. For setting up locally, follow the instructions below.

We recommend styling components using our design style guide.

We are strongly opinionated about adding new variables/tokens to the colors. After careful research, the colors have been chosen to respect the freeCodeCamp brand identity, developer experience, and accessibility.

We recommend going through our system design diagram.

This project uses a PostgreSQL database. You should follow the instructions in the linked documentation to set it up for your system. Alternatively, you can use the below commands for a docker-based setup on likes of Linux or macOS, if you have docker installed.

# create a directory for the data
mkdir -p $HOME/docker/volumes/postgres

# start a container (this will use the "latest" tag. Use the version as needed)
docker run -it --name pgsql-classroom -e POSTGRES_PASSWORD=password -d --restart unless-stopped -p 5432:5432 -v $HOME/docker/volumes/postgres:/var/lib/postgresql/data postgres:latest

# change DATABASE_URL in your .env to
postgresql://postgres:password@localhost:5432/classroom

1. Clone the project repository.

   git clone https://github.com/freeCodeCamp/classroom.git
   cd classroom

2. We use npm (specifically npm workspaces) to manage our dependencies.

   npm ci

3. Create .env file based on the .env.sample file. Theses are the environment variables that are used by the application.
4. Run npx prisma generate.
5. Run npx prisma db push.
6. Run npx prisma db seed.
7. Run npm run develop.
8. Run npm run mock-fcc-data
9. Run npx prisma studio

Note: The classroom app runs on port 3001 and mock data on port 3002 to avoid conflicts with freeCodeCamp's main platform (ports 3000/8000).

Need more help? Ran into issues? Check out this guide that walks you through all the steps of setting up the repository locally, without Docker.

The Classroom application supports two authentication providers: GitHub OAuth (recommended for contributors) and Auth0 (required for production). You must configure at least one provider to use the application.

For FCC Proper integration, install the application locally and use Auth0 for authentication.

1. Go to GitHub Settings → Developer Settings → OAuth Apps
2. Click "New OAuth App" and fill in:
   • Application name: FreeCodeCamp Classroom (or your preferred name)
   • Homepage URL: http://localhost:3001 (or the URL shown in your terminal)
   • Authorization callback URL: http://localhost:3001/api/auth/callback/github
3. After creating the app, copy the Client ID and Client Secret to your .env file:

   GITHUB_ID=your_client_id_here
   GITHUB_SECRET=your_client_secret_here
   GITHUB_OAUTH_PROVIDER_ENABLED=true
   

Important: Auth0 callback URLs must exactly match your application URL including the port number. After changing ports, you must update your Auth0 application settings.

1. Go to auth0.com and create an account (or sign in)
2. Click "Create Application" and select "Regular Web Applications"
3. Select "Next.js" as your technology
4. Navigate to the "Settings" tab (do NOT follow the "integrate with my app" tutorial)

Copy the following values from your Auth0 Application Settings to your .env file:

Note: Do NOT include a trailing slash in AUTH0_ISSUER.

In your Auth0 Application Settings, configure these URLs based on your environment:

For Local Development (localhost:3001):

For GitHub Codespaces:

Note: Auth0 allows multiple callback URLs separated by commas. You can add all your development environments to support seamless switching.

If you need to run Classroom alongside freeCodeCamp's main platform (fCC Proper) on the same machine:

Prerequisites:

• Both applications MUST run on the same domain (localhost) for authentication to work correctly
• Both applications MUST be installed locally (Codespaces/Gitpod won't work for this setup)
• Port separation is required to avoid conflicts

Port Configuration:

• fCC Proper: localhost:8000 (frontend) + localhost:3000 (backend)
• Classroom: localhost:3001 (app) + localhost:3002 (mock data)

Auth0 Configuration for local FCC Proper integration with local FCC Classroom - Dual Setup:

Add BOTH callback URLs to your Auth0 Application Settings:

Why This Matters:

• Authentication tokens/sessions are domain-scoped
• localhost:3000 and localhost:3001 share the same domain (localhost)
• This allows both apps to access the same Auth0 session
• Different domains (e.g., Codespaces URLs) would NOT share authentication state

If authentication fails:

1. Check Auth0 logs in the dashboard for detailed error messages
2. Verify your .env file URLs match your current environment
3. Inspect browser network tab for failed authorize requests:
   • Press Ctrl+Shift+I (or Cmd+Option+I on Mac)
   • Go to Network tab
   • Look for failed (red) authorize requests
   • Click on it and check "Preview" to see the expected callback URL
4. Ensure all Auth0 Application Settings are saved (scroll to bottom of settings page)
5. Verify the email used for Auth0 matches your GitHub account email

Common Issues:

• "Callback URL mismatch": Your Auth0 Allowed Callback URLs don't include the exact URL being used
• "Invalid state": Session/cookie issue, try clearing cookies for localhost
• 401 Unauthorized: Check that NEXTAUTH_SECRET is set in your .env file

In production environments with separate domains (e.g., classroom.freecodecamp.org and freecodecamp.org):

• Port numbers are handled by reverse proxies (external port 80/443)
• Auth0 callback URLs use domain names, not ports: https://classroom.freecodecamp.org/api/auth/callback/auth0
• No port conflicts occur because domains are different
• The port changes in this repository are primarily for local development

freeCodeCamp uses the following terms:

Certification = 'superblock'

Course(s) = 'blocks'

Everything under a course/block is a 'challenge'

Testing with jest https://jestjs.io/docs/snapshot-testing

Next.js fullstack framework https://nextjs.org/docs/pages/building-your-application/optimizing/testing#jest-and-react-testing-library https://dillionmegida.com/p/nextjs-main-concepts/ https://blog.devgenius.io/advanced-next-js-concepts-8439a8752597

Next.js terminology:

SSR - Server Side Rendering

SSG - Static Site Generation

ISR - Incremental Static Regeneration

CSR - Client Side Rendering

SSR is probably the focus point.

https://dev.to/mbaljeetsingh/what-is-csr-ssr-ssg-isr-different-rendering-strategies-and-which-framework-does-it-better-angular-react-vue-4lkp

Copyright © 2021 freeCodeCamp.org

The content of this repository is bound by the following licenses:

• The computer software is licensed under the BSD-3-Clause license.