diff --git a/src/content/docs/how-to-add-playwright-tests.mdx b/src/content/docs/how-to-add-playwright-tests.mdx index 23c3d0c5..8dbf3caf 100644 --- a/src/content/docs/how-to-add-playwright-tests.mdx +++ b/src/content/docs/how-to-add-playwright-tests.mdx @@ -288,32 +288,18 @@ npx playwright show-report ### Ensure Development Environment is Running -- Follow the [MongoDB installation guide](https://www.mongodb.com/basics/get-started). +The Codespace devcontainer automatically sets up `.env`, installs dependencies, and seeds the database. Start the development server: -- Create the .env - - ```bash - cp sample.env .env - ``` - -- Seed the database - - ```bash - pnpm run seed:certified-user - ``` - -- Develop the server and client - - ```bash - pnpm run develop - ``` +```bash +pnpm run develop +``` -### Install Playwright Build Tools +### Install Playwright -To install necessary dependencies for running Playwright run the following command: +To install the browser binary needed for running Playwright tests: ```bash -pnpm run playwright:install-build-tools +npx playwright install chromium ``` ### Run the Playwright Tests on GitHub Codespaces diff --git a/src/content/docs/how-to-setup-freecodecamp-locally.mdx b/src/content/docs/how-to-setup-freecodecamp-locally.mdx index e2aeb394..1250be4d 100644 --- a/src/content/docs/how-to-setup-freecodecamp-locally.mdx +++ b/src/content/docs/how-to-setup-freecodecamp-locally.mdx @@ -67,57 +67,43 @@ The main repository at `https://github.com/freeCodeCamp/freeCodeCamp` is often r -## Cloud IDE or your own machine? +## Local machine or devcontainer setup? -Next, you need to choose between setting up a cloud IDE or your own machine. +Next, choose between a machine-native setup (recommended) or a containerized setup using devcontainers. -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. +The **local machine setup** is the recommended approach for regular contributors. You install the prerequisites (Node.js, pnpm, MongoDB) directly on your machine, which gives you the best performance, no usage limits, and no Docker dependency. This requires a macOS or Linux environment (Windows users need [WSL2](/how-to-setup-wsl)). -| 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 | +The **devcontainer setup** uses a pre-configured development container that works identically whether you run it locally (via VS Code + Docker) or in the cloud (via GitHub Codespaces). All dependencies, database services, and tooling are pre-installed inside the container — useful if you want a zero-config environment or you're on Windows without WSL2. -Once you have decided, follow the relevant tab below to continue with the setup. - - - - -#### 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. + - +Once you have decided, follow the relevant tab below to continue with the setup. - + + Here is a minimum system requirement for running freeCodeCamp locally: @@ -139,7 +125,7 @@ Start by installing the prerequisite software for your operating system. | Prerequisite | Version | Notes | | --------------------------------------------------------------------------------------------- | ------- | ------------------------------------------------------------------------------------------- | -| [Node.js](http://nodejs.org) | `22.x` | We use the "Active LTS" version, see [LTS Schedule](https://nodejs.org/en/about/releases/). | +| [Node.js](http://nodejs.org) | `24.x` | We use the "Active LTS" version, see [LTS Schedule](https://nodejs.org/en/about/releases/). | | [pnpm](https://pnpm.io/installation) | `10.x` | - | | [MongoDB Community Server](https://docs.mongodb.com/manual/administration/install-community/) | `8.0.x` | - | | [Docker Compose](https://docs.docker.com/compose/install/) | `2.x` | - | @@ -265,42 +251,70 @@ You need a reference from your local clone to the `upstream` repository in addit - -## Running freeCodeCamp + -Now that you have a copy of freeCodeCamp, you can follow these instructions to run it. This will allow you to: +We have automated the development environment setup using devcontainers. The same container configuration works both locally (via VS Code + Docker) and in the cloud (via GitHub Codespaces), giving you a consistent, ready-to-code environment with all dependencies pre-installed. -- 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. +#### Option A: Run locally with VS Code and Docker - - + -Your Codespace comes pre-configured with all dependencies installed and services like the database already running. You can start developing immediately: +1. Install [Docker Desktop](https://www.docker.com/products/docker-desktop/) and [Visual Studio Code](https://code.visualstudio.com/) if you haven't already. -1. In the terminal, run: +2. Install the [Dev Containers extension](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers) in VS Code. + +3. Clone your fork to your local machine: ```bash - pnpm run develop + git clone --depth=1 https://github.com/YOUR_USER_NAME/freeCodeCamp.git ``` - This will start both the API server and the client applications. +4. Open the cloned folder in VS Code. You should see a prompt to **Reopen in Container** — click it. Alternatively, press `Ctrl+Shift+P` (or `Cmd+Shift+P` on Mac), type "Reopen in Container", and select the option. -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. +5. Wait for the container to build and start. The devcontainer image has pre-cached dependencies, so this should be quick after the initial image pull. This includes: + - Pre-populated pnpm dependency cache and Turbo build cache for fast installs + - Setting up and seeding MongoDB + - Configuring VS Code extensions (ESLint, Prettier) + - Preparing the environment variables -3. Click on the notification to open the client application in a new browser tab. + - + + + + +Your devcontainer comes pre-configured with all dependencies installed and services like the database already running, whether you launched it locally via VS Code + Docker or in GitHub Codespaces. You can start developing immediately: + +#### Option 1: VS Code task + +Press `Ctrl+Shift+P` (or `Cmd+Shift+P` on Mac), type "Run Task", and select **Start Development**. + +#### Option 2: Terminal + +In the terminal, run: + +```bash +pnpm run develop +``` + +Both options will start the API server and the client application. + +Wait for the process to complete. It can take a few minutes, you will see a notification for the `8000` port when it's ready. Click on the notification to open the client application in a new browser tab. + + + diff --git a/src/content/docs/troubleshooting-development-issues.mdx b/src/content/docs/troubleshooting-development-issues.mdx index ead78ba6..55713088 100644 --- a/src/content/docs/troubleshooting-development-issues.mdx +++ b/src/content/docs/troubleshooting-development-issues.mdx @@ -34,13 +34,13 @@ Sometimes the service on port `8000` doesn't go live. This is common when you ar If the service is not coming up on port `8000`, you can troubleshoot using these steps: -- **Start the server**: Run the below command in one terminal window from the root project directory (`/workspace/freeCodeCamp`). +- **Start the server**: Run the below command in one terminal window from the root project directory (`/workspaces/freeCodeCamp`). ```bash pnpm run develop:server ``` -- **Start the client**: In another terminal window, run the below command from the client directory (`/workspace/freeCodeCamp/client`). +- **Start the client**: In another terminal window, run the below command from the client directory (`/workspaces/freeCodeCamp/client`). ```bash pnpm run develop -- -H '0.0.0.0' diff --git a/tests/mdx-tab-sync.test.ts b/tests/mdx-tab-sync.test.ts new file mode 100644 index 00000000..ac52763f --- /dev/null +++ b/tests/mdx-tab-sync.test.ts @@ -0,0 +1,67 @@ +import { describe, it, expect } from 'vitest'; +import { readFileSync } from 'node:fs'; +import { resolve } from 'node:path'; + +type TabGroup = { syncKey: string; labels: string[] }; + +function extractTabGroups(source: string): TabGroup[] { + const groups: TabGroup[] = []; + const tabsRegex = /([\s\S]*?)<\/Tabs>/g; + const labelRegex = /]*label=["']([^"']+)["']/g; + + let tabsMatch: RegExpExecArray | null; + while ((tabsMatch = tabsRegex.exec(source)) !== null) { + const [, syncKey, body] = tabsMatch; + const labels: string[] = []; + let labelMatch: RegExpExecArray | null; + while ((labelMatch = labelRegex.exec(body)) !== null) { + labels.push(labelMatch[1]); + } + groups.push({ syncKey, labels }); + } + return groups; +} + +describe('MDX Tab syncKey contract', () => { + const docs = [ + 'src/content/docs/how-to-setup-freecodecamp-locally.mdx', + 'src/content/docs/how-to-add-playwright-tests.mdx' + ]; + + for (const relPath of docs) { + describe(relPath, () => { + const absPath = resolve(process.cwd(), relPath); + const source = readFileSync(absPath, 'utf8'); + const groups = extractTabGroups(source); + + it('all blocks sharing a syncKey use identical label sets', () => { + const bySyncKey = new Map(); + for (const { syncKey, labels } of groups) { + const list = bySyncKey.get(syncKey) ?? []; + list.push(labels); + bySyncKey.set(syncKey, list); + } + + for (const [syncKey, labelSets] of bySyncKey) { + if (labelSets.length < 2) continue; + const sorted = labelSets.map(l => [...l].sort()); + const first = sorted[0]; + for (const other of sorted.slice(1)) { + expect(other, `syncKey="${syncKey}" label mismatch`).toEqual(first); + } + } + }); + + it('no TabItem header has a trailing empty "Option N:" label', () => { + expect(source).not.toMatch(/^####\s+Option\s+\d+:\s*$/m); + }); + + it('every syncKey="environment" Tabs block lists Local Machine first', () => { + const envGroups = groups.filter(g => g.syncKey === 'environment'); + for (const { labels } of envGroups) { + expect(labels[0]).toBe('Local Machine (Recommended)'); + } + }); + }); + } +});