|
| 1 | +# Project Setup Guide |
| 2 | + |
| 3 | +This guide will help you set up the DQ Website project on Windows. |
| 4 | + |
| 5 | +## Prerequisites |
| 6 | + |
| 7 | +### 1. Install Node.js |
| 8 | + |
| 9 | +The project requires Node.js version 20 or higher (as specified in `package.json`). CI/CD uses Node 20. |
| 10 | + |
| 11 | +**Download and Install:** |
| 12 | +1. Visit [https://nodejs.org/](https://nodejs.org/) |
| 13 | +2. Download the LTS (Long Term Support) version (recommended) |
| 14 | +3. Run the installer and follow the setup wizard |
| 15 | +4. Make sure to check "Add to PATH" during installation |
| 16 | + |
| 17 | +**Verify Installation:** |
| 18 | +Open a new PowerShell window and run: |
| 19 | +```powershell |
| 20 | +node --version |
| 21 | +npm --version |
| 22 | +``` |
| 23 | + |
| 24 | +Both commands should return version numbers. |
| 25 | + |
| 26 | +### 2. Install Yarn (Optional but Recommended) |
| 27 | + |
| 28 | +The project uses Yarn as the package manager (see `README.md`). You can install it globally: |
| 29 | + |
| 30 | +```powershell |
| 31 | +npm install -g yarn |
| 32 | +``` |
| 33 | + |
| 34 | +**Verify Installation:** |
| 35 | +```powershell |
| 36 | +yarn --version |
| 37 | +``` |
| 38 | + |
| 39 | +**Alternative:** You can also use npm instead of yarn. Both `package.json` and `package-lock.json` are present, so npm will work fine. |
| 40 | + |
| 41 | +## Project Setup Steps |
| 42 | + |
| 43 | +### Step 1: Install Dependencies |
| 44 | + |
| 45 | +Navigate to the project directory and install dependencies: |
| 46 | + |
| 47 | +**Using Yarn (recommended):** |
| 48 | +```powershell |
| 49 | +cd c:\Users\cwest\Documents\GitHub\dq-website |
| 50 | +yarn install |
| 51 | +``` |
| 52 | + |
| 53 | +**Or using npm:** |
| 54 | +```powershell |
| 55 | +cd c:\Users\cwest\Documents\GitHub\dq-website |
| 56 | +npm install |
| 57 | +``` |
| 58 | + |
| 59 | +This will create the `node_modules` folder and install all required dependencies. |
| 60 | + |
| 61 | +### Step 2: Start the Development Server |
| 62 | + |
| 63 | +**Using Yarn:** |
| 64 | +```powershell |
| 65 | +yarn start |
| 66 | +``` |
| 67 | + |
| 68 | +**Or using npm:** |
| 69 | +```powershell |
| 70 | +npm run start |
| 71 | +``` |
| 72 | + |
| 73 | +This will: |
| 74 | +- Start the Docusaurus development server |
| 75 | +- Open your browser automatically |
| 76 | +- Watch for file changes and hot-reload |
| 77 | + |
| 78 | +The site will typically be available at `http://localhost:3000` |
| 79 | + |
| 80 | +## Troubleshooting |
| 81 | + |
| 82 | +### Issue: "npm/yarn is not recognized" |
| 83 | +- **Solution:** Node.js is not installed or not in your PATH. Install Node.js and restart your terminal. |
| 84 | + |
| 85 | +### Issue: "npm.ps1 cannot be loaded because running scripts is disabled" |
| 86 | +This is a PowerShell execution policy issue. You have three options: |
| 87 | + |
| 88 | +**Option 1: Bypass execution policy for current session (Quick Fix)** |
| 89 | +```powershell |
| 90 | +Set-ExecutionPolicy -ExecutionPolicy Bypass -Scope Process |
| 91 | +npm install |
| 92 | +``` |
| 93 | + |
| 94 | +**Option 2: Use Command Prompt instead** |
| 95 | +- Open Command Prompt (cmd.exe) instead of PowerShell |
| 96 | +- Navigate to the project directory and run `npm install` |
| 97 | + |
| 98 | +**Option 3: Change execution policy permanently (Requires Admin)** |
| 99 | +1. Open PowerShell as Administrator |
| 100 | +2. Run: `Set-ExecutionPolicy RemoteSigned -Scope CurrentUser` |
| 101 | +3. Close and reopen PowerShell |
| 102 | +4. Run `npm install` |
| 103 | + |
| 104 | +**Recommended:** Use Option 1 for a quick fix, or Option 2 if you prefer not to change PowerShell settings. |
| 105 | + |
| 106 | +### Issue: "node_modules folder doesn't exist" |
| 107 | +- **Solution:** Run `yarn install` or `npm install` to install dependencies. |
| 108 | + |
| 109 | +### Issue: Port 3000 is already in use |
| 110 | +- **Solution:** Either stop the other application using port 3000, or set a different port: |
| 111 | + ```powershell |
| 112 | + yarn start --port 3001 |
| 113 | + ``` |
| 114 | + |
| 115 | +### Issue: Permission errors on Windows |
| 116 | +- **Solution:** Run PowerShell as Administrator, or check that you have write permissions to the project directory. |
| 117 | + |
| 118 | +## Additional Commands |
| 119 | + |
| 120 | +- **Build for production:** `yarn build` or `npm run build` |
| 121 | +- **Clear cache:** `yarn clear` or `npm run clear` |
| 122 | +- **Serve production build:** `yarn serve` or `npm run serve` |
| 123 | + |
| 124 | +## Next Steps |
| 125 | + |
| 126 | +Once the development server is running, you can: |
| 127 | +- Edit files in `src/` for React components |
| 128 | +- Edit files in `docs/` for documentation pages |
| 129 | +- Edit files in `blog/` for blog posts |
| 130 | +- Changes will automatically reload in the browser |
0 commit comments