|
1 | | -# Deploying to GitHub Pages |
| 1 | +# GitHub Pages Deployment Guide |
2 | 2 |
|
3 | | -This document explains how to deploy the GitHub Copilot Usage Analyzer to GitHub Pages. |
| 3 | +This document provides detailed instructions for deploying the GitHub Copilot Usage Analyzer to GitHub Pages. |
4 | 4 |
|
5 | | -## Automated Deployment with GitHub Actions |
| 5 | +## Understanding the Deployment Process |
6 | 6 |
|
7 | | -This project includes a GitHub Actions workflow that automatically builds and deploys the application to GitHub Pages without requiring the Spark dependencies. |
| 7 | +When deploying to GitHub Pages, we need to address the fact that GitHub Spark dependencies are not available in the standard GitHub Pages environment. The deployment process includes: |
8 | 8 |
|
9 | | -### How It Works |
| 9 | +1. Using a simplified version of the application's main entry point |
| 10 | +2. Building with a custom Vite configuration that excludes Spark dependencies |
| 11 | +3. Deploying the built assets to GitHub Pages |
10 | 12 |
|
11 | | -1. The workflow `.github/workflows/deploy-to-pages.yml` is triggered on pushes to the `main` branch or manually from the Actions tab. |
12 | | -2. It creates a simplified build configuration that: |
13 | | - - Removes dependencies on the GitHub Spark modules |
14 | | - - Creates shims for necessary functionality |
15 | | - - Sets the correct base path for GitHub Pages |
16 | | -3. The built application is deployed to GitHub Pages automatically. |
| 13 | +## Prerequisites |
17 | 14 |
|
18 | | -### Setting Up GitHub Pages |
| 15 | +- A GitHub repository containing your Copilot Usage Analyzer code |
| 16 | +- GitHub Pages enabled for your repository |
19 | 17 |
|
20 | | -To set up GitHub Pages deployment for this repository: |
| 18 | +## Step-by-Step Deployment |
| 19 | + |
| 20 | +### 1. Enabling GitHub Pages for Your Repository |
21 | 21 |
|
22 | 22 | 1. Go to your repository on GitHub |
23 | 23 | 2. Click on "Settings" |
24 | 24 | 3. Navigate to "Pages" in the left sidebar |
25 | 25 | 4. Under "Build and deployment" > "Source", select "GitHub Actions" |
26 | | -5. The workflow will now be able to deploy to GitHub Pages |
27 | 26 |
|
28 | | -### Running the Workflow Manually |
| 27 | +### 2. Automatic Deployment with GitHub Actions |
| 28 | + |
| 29 | +The included GitHub Actions workflow will automatically deploy your application when changes are pushed to the main branch: |
| 30 | + |
| 31 | +1. Push your changes to the `main` branch |
| 32 | +2. Go to the "Actions" tab to monitor the deployment progress |
| 33 | +3. Once complete, your application will be available at: `https://[your-github-username].github.io/[repo-name]/` |
| 34 | + |
| 35 | +### 3. Manual Deployment |
29 | 36 |
|
30 | | -You can trigger the deployment workflow manually: |
| 37 | +If you prefer to trigger the deployment manually: |
31 | 38 |
|
32 | 39 | 1. Go to the "Actions" tab in your repository |
33 | | -2. Select the "Deploy to GitHub Pages" workflow |
34 | | -3. Click "Run workflow" button (branch: main) |
35 | | -4. Wait for the workflow to complete |
36 | | - |
37 | | -## Manual Deployment |
38 | | - |
39 | | -For manual deployment, follow these steps: |
40 | | - |
41 | | -### Step 1: Create a Simplified Build |
42 | | - |
43 | | -Since the Spark dependencies are not available outside the GitHub environment, we need to create a simplified version of the app for GitHub Pages: |
44 | | - |
45 | | -1. Create a new temporary directory: |
46 | | - ```bash |
47 | | - mkdir -p temp_build |
48 | | - cd temp_build |
49 | | - ``` |
50 | | - |
51 | | -2. Copy source files: |
52 | | - ```bash |
53 | | - cp -r ../src . |
54 | | - cp ../index.html . |
55 | | - cp ../tailwind.config.js . |
56 | | - ``` |
57 | | - |
58 | | -3. Create a simplified vite.config.js: |
59 | | - ```javascript |
60 | | - import { defineConfig } from "vite"; |
61 | | - import react from "@vitejs/plugin-react"; |
62 | | - import { resolve } from 'path'; |
63 | | - |
64 | | - export default defineConfig({ |
65 | | - plugins: [react()], |
66 | | - build: { |
67 | | - base: "/your-repo-name/", // Change to your repository name |
68 | | - outDir: 'dist' |
69 | | - }, |
70 | | - resolve: { |
71 | | - alias: { |
72 | | - '@': resolve(__dirname, 'src') |
73 | | - } |
74 | | - } |
75 | | - }); |
76 | | - ``` |
77 | | - |
78 | | -4. Create a simplified package.json with only the necessary dependencies: |
79 | | - ```json |
80 | | - { |
81 | | - "name": "github-copilot-usage-analyzer", |
82 | | - "private": true, |
83 | | - "version": "1.0.0", |
84 | | - "type": "module", |
85 | | - "scripts": { |
86 | | - "build": "vite build", |
87 | | - "preview": "vite preview" |
88 | | - }, |
89 | | - "dependencies": { |
90 | | - "@phosphor-icons/react": "^2.0.15", |
91 | | - "clsx": "^2.1.0", |
92 | | - "react": "^18.2.0", |
93 | | - "react-dom": "^18.2.0", |
94 | | - "recharts": "^2.10.3", |
95 | | - "sonner": "^1.2.4", |
96 | | - "tailwind-merge": "^2.2.0" |
97 | | - }, |
98 | | - "devDependencies": { |
99 | | - "@types/react": "^18.2.46", |
100 | | - "@types/react-dom": "^18.2.18", |
101 | | - "@vitejs/plugin-react": "^4.2.1", |
102 | | - "autoprefixer": "^10.4.16", |
103 | | - "postcss": "^8.4.32", |
104 | | - "tailwindcss": "^3.4.0", |
105 | | - "typescript": "^5.3.3", |
106 | | - "vite": "^5.0.10" |
107 | | - } |
108 | | - } |
109 | | - ``` |
110 | | - |
111 | | -5. Create a shim for Spark hooks: |
112 | | - ```javascript |
113 | | - // src/spark-shims/hooks.js |
114 | | - import { useState } from 'react'; |
115 | | - |
116 | | - // Simple localStorage-based shim for useKV hook |
117 | | - export function useKV(key, initialValue) { |
118 | | - const storageKey = `kv-${key}`; |
119 | | - |
120 | | - // Get from localStorage |
121 | | - const stored = localStorage.getItem(storageKey); |
122 | | - const initial = stored !== null ? JSON.parse(stored) : initialValue; |
123 | | - |
124 | | - const [value, setValue] = useState(initial); |
125 | | - |
126 | | - const setValueAndStore = (newValue) => { |
127 | | - const valueToStore = newValue instanceof Function ? newValue(value) : newValue; |
128 | | - setValue(valueToStore); |
129 | | - localStorage.setItem(storageKey, JSON.stringify(valueToStore)); |
130 | | - }; |
131 | | - |
132 | | - const deleteValue = () => { |
133 | | - setValue(null); |
134 | | - localStorage.removeItem(storageKey); |
135 | | - }; |
136 | | - |
137 | | - return [value, setValueAndStore, deleteValue]; |
138 | | - } |
139 | | - ``` |
140 | | - |
141 | | -6. Update imports in your code: |
142 | | - ```bash |
143 | | - # Replace imports from @github/spark/hooks with our shim |
144 | | - find src -type f -name "*.ts" -o -name "*.tsx" | xargs sed -i 's/import {.*} from "@github\/spark\/hooks"/import { useKV } from "..\/spark-shims\/hooks"/g' |
145 | | - ``` |
146 | | - |
147 | | -7. Install dependencies and build: |
148 | | - ```bash |
149 | | - npm install |
150 | | - npm run build |
151 | | - ``` |
152 | | - |
153 | | -### Step 2: Deploy to GitHub Pages |
154 | | - |
155 | | -1. Create a gh-pages branch (if it doesn't exist): |
156 | | - ```bash |
157 | | - git checkout --orphan gh-pages |
158 | | - ``` |
159 | | - |
160 | | -2. Remove existing files: |
161 | | - ```bash |
162 | | - git rm -rf . |
163 | | - ``` |
164 | | - |
165 | | -3. Copy build files: |
166 | | - ```bash |
167 | | - cp -r temp_build/dist/* . |
168 | | - ``` |
169 | | - |
170 | | -4. Create a .nojekyll file (important for proper GitHub Pages rendering): |
171 | | - ```bash |
172 | | - touch .nojekyll |
173 | | - ``` |
174 | | - |
175 | | -5. Commit and push: |
176 | | - ```bash |
177 | | - git add . |
178 | | - git commit -m "Deploy to GitHub Pages" |
179 | | - git push -u origin gh-pages |
180 | | - ``` |
181 | | - |
182 | | -6. Return to main branch: |
183 | | - ```bash |
184 | | - git checkout main |
185 | | - ``` |
186 | | - |
187 | | -## Accessing Your Deployed Application |
188 | | - |
189 | | -Once deployed, your application will be available at: |
190 | | -`https://[your-github-username].github.io/your-repo-name/` |
191 | | - |
192 | | -Replace `your-repo-name` with the actual name of your repository. |
| 40 | +2. Select "Deploy to GitHub Pages" workflow |
| 41 | +3. Click "Run workflow" dropdown and select the main branch |
| 42 | +4. Click the green "Run workflow" button |
| 43 | + |
| 44 | +### 4. Local Build for GitHub Pages |
| 45 | + |
| 46 | +You can also build the GitHub Pages version locally to test before deploying: |
| 47 | + |
| 48 | +```bash |
| 49 | +# Copy the GitHub Pages specific main file |
| 50 | +cp src/main-github-pages.tsx src/main.tsx |
| 51 | + |
| 52 | +# Build using the custom config |
| 53 | +npm run build |
| 54 | + |
| 55 | +# Restore the original main file if needed |
| 56 | +git checkout src/main.tsx |
| 57 | +``` |
193 | 58 |
|
194 | 59 | ## Troubleshooting |
195 | 60 |
|
196 | | -If you encounter any issues with the deployment: |
| 61 | +### Common Issues |
| 62 | + |
| 63 | +#### 1. Build Failure Due to Missing Dependencies |
| 64 | + |
| 65 | +If your build fails with errors about missing `@github/spark` dependencies: |
| 66 | + |
| 67 | +- Make sure you're using the GitHub Pages specific main file (`main-github-pages.tsx`) |
| 68 | +- Check that your application doesn't reference Spark-specific functionality in components |
| 69 | + |
| 70 | +#### 2. Blank Page After Deployment |
| 71 | + |
| 72 | +If your deployed page is blank: |
| 73 | + |
| 74 | +- Check the browser console for errors |
| 75 | +- Ensure your `index.html` file correctly references the built JavaScript and CSS files |
| 76 | +- Verify that your repository name is correctly set in the `base` path in your Vite config |
| 77 | + |
| 78 | +#### 3. Styling Issues |
197 | 79 |
|
198 | | -1. Check the GitHub Actions logs for any error messages |
199 | | -2. Ensure GitHub Pages is properly configured in your repository settings |
200 | | -3. Verify that the base path in the Vite configuration matches your repository name |
201 | | -4. Check that the repository has proper permissions set for GitHub Pages deployment |
202 | | -5. If using manual deployment, make sure you have a .nojekyll file in the gh-pages branch |
203 | | -6. Verify that all paths in the application are relative, not absolute |
| 80 | +If your application loses styling after deployment: |
204 | 81 |
|
205 | | -## Note About App Functionality |
| 82 | +- Make sure all CSS imports are properly included |
| 83 | +- Verify that Tailwind is properly configured in your build |
206 | 84 |
|
207 | | -When deployed to GitHub Pages, be aware that: |
| 85 | +## Additional Resources |
208 | 86 |
|
209 | | -1. The application is entirely client-side - all data processing happens in the browser |
210 | | -2. No data is sent to any server when using the CSV upload feature |
211 | | -3. If your CSV files are large, performance will depend on the user's device capabilities |
212 | | -4. The localStorage-based KV store implementation means data will be persisted only in the user's browser |
| 87 | +- [GitHub Pages Documentation](https://docs.github.com/en/pages) |
| 88 | +- [Vite Deployment Guide](https://vitejs.dev/guide/static-deploy.html#github-pages) |
| 89 | +- [GitHub Actions Documentation](https://docs.github.com/en/actions) |
0 commit comments