Skip to content

Commit c753b8c

Browse files
rezwana-karimrezwana-karim
authored
Implement complete GitHub Pages deployment configuration (#18)
2 parents d546e6a + 2804263 commit c753b8c

7 files changed

Lines changed: 322 additions & 4 deletions

File tree

‎.github/workflows/deploy-github-pages.yml‎

Lines changed: 55 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,55 @@
1+
name: Deploy to GitHub Pages
2+
3+
on:
4+
push:
5+
branches: [ main ]
6+
workflow_dispatch:
7+
8+
permissions:
9+
contents: read
10+
pages: write
11+
id-token: write
12+
13+
concurrency:
14+
group: "pages"
15+
cancel-in-progress: false
16+
17+
jobs:
18+
build:
19+
runs-on: ubuntu-latest
20+
steps:
21+
- name: Checkout
22+
uses: actions/checkout@v4
23+
24+
- name: Setup Node.js
25+
uses: actions/setup-node@v4
26+
with:
27+
node-version: '20'
28+
cache: 'npm'
29+
30+
- name: Setup Pages
31+
uses: actions/configure-pages@v4
32+
with:
33+
static_site_generator: next
34+
35+
- name: Install dependencies
36+
run: npm ci
37+
38+
- name: Build with Next.js
39+
run: npm run build:github-pages
40+
41+
- name: Upload artifact
42+
uses: actions/upload-pages-artifact@v3
43+
with:
44+
path: ./out
45+
46+
deploy:
47+
environment:
48+
name: github-pages
49+
url: ${{ steps.deployment.outputs.page_url }}
50+
runs-on: ubuntu-latest
51+
needs: build
52+
steps:
53+
- name: Deploy to GitHub Pages
54+
id: deployment
55+
uses: actions/deploy-pages@v4

‎.github/workflows/deploy.yml‎

Lines changed: 62 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,62 @@
1+
name: Deploy to GitHub Pages
2+
3+
on:
4+
push:
5+
branches:
6+
- main
7+
pull_request:
8+
branches:
9+
- main
10+
11+
# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
12+
permissions:
13+
contents: read
14+
pages: write
15+
id-token: write
16+
17+
# Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued.
18+
# However, do NOT cancel in-progress runs as we want to allow these production deployments to complete.
19+
concurrency:
20+
group: "pages"
21+
cancel-in-progress: false
22+
23+
jobs:
24+
# Build job
25+
build:
26+
runs-on: ubuntu-latest
27+
steps:
28+
- name: Checkout
29+
uses: actions/checkout@v4
30+
31+
- name: Setup Node.js
32+
uses: actions/setup-node@v4
33+
with:
34+
node-version: '20'
35+
cache: 'npm'
36+
37+
- name: Install dependencies
38+
run: npm ci
39+
40+
- name: Build Next.js application
41+
run: npm run build:github-pages
42+
43+
- name: Add .nojekyll file
44+
run: touch out/.nojekyll
45+
46+
- name: Upload artifact
47+
uses: actions/upload-pages-artifact@v3
48+
with:
49+
path: ./out
50+
51+
# Deployment job
52+
deploy:
53+
environment:
54+
name: github-pages
55+
url: ${{ steps.deployment.outputs.page_url }}
56+
runs-on: ubuntu-latest
57+
needs: build
58+
if: github.ref == 'refs/heads/main'
59+
steps:
60+
- name: Deploy to GitHub Pages
61+
id: deployment
62+
uses: actions/deploy-pages@v4

‎.nojekyll‎

Whitespace-only changes.

‎README.md‎

Lines changed: 18 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -11,7 +11,7 @@ This is the official portfolio website built with Next.js, Tailwind CSS, and Rad
1111
- **Components**: [Radix UI](https://www.radix-ui.com)
1212
- **Typography**: [Geist Font](https://vercel.com/font)
1313
- **Language**: TypeScript
14-
- **Deployment**: Vercel
14+
- **Deployment**: GitHub Pages (automated via GitHub Actions)
1515

1616
## Getting Started
1717

@@ -50,9 +50,26 @@ This project implements a comprehensive design system based on:
5050

5151
- `npm run dev` - Start development server
5252
- `npm run build` - Build for production
53+
- `npm run build:github-pages` - Build for GitHub Pages deployment
5354
- `npm run start` - Start production server
5455
- `npm run lint` - Run ESLint
5556

57+
## Deployment
58+
59+
This project supports two deployment methods:
60+
61+
### GitHub Pages (Recommended)
62+
The site is automatically deployed to GitHub Pages when changes are pushed to the main branch.
63+
64+
- **Live Site**: [https://codestorm-hub.github.io/CodeStorm-Hub.github.io/](https://codestorm-hub.github.io/CodeStorm-Hub.github.io/)
65+
- **Deployment**: Automatic via GitHub Actions
66+
- **Configuration**: See [GitHub Pages Deployment Guide](docs/github-pages-deployment.md)
67+
68+
### Vercel
69+
Alternative deployment platform with similar capabilities.
70+
71+
- **Configuration**: `vercel.json` included for Vercel deployments
72+
5673
## Contributing
5774

5875
We welcome contributions! Please see our contributing guidelines for more details.

‎docs/github-pages-deployment.md‎

Lines changed: 173 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,173 @@
1+
# GitHub Pages Deployment Guide
2+
3+
This document outlines the deployment process for CodeStorm Hub using GitHub Pages with automated GitHub Actions workflow.
4+
5+
## Overview
6+
7+
CodeStorm Hub is deployed using GitHub Pages with a Next.js static export. The deployment process is fully automated through GitHub Actions, which builds and deploys the site whenever changes are pushed to the main branch.
8+
9+
## Architecture
10+
11+
- **Framework**: Next.js 15 with static export (`output: 'export'`)
12+
- **Deployment Platform**: GitHub Pages
13+
- **Automation**: GitHub Actions workflow
14+
- **Branch**: `main` (production deployment)
15+
- **Build Output**: Static HTML/CSS/JS files in `/out` directory
16+
17+
## Deployment Configuration
18+
19+
### 1. Next.js Configuration (`next.config.ts`)
20+
21+
The application is configured for static export with GitHub Pages optimizations:
22+
23+
```typescript
24+
const nextConfig: NextConfig = {
25+
output: 'export',
26+
trailingSlash: true,
27+
images: {
28+
unoptimized: true, // Required for GitHub Pages
29+
remotePatterns: [new URL("https://github.com/CodeStorm-Hub.png")],
30+
},
31+
// GitHub Pages specific paths
32+
basePath: process.env.NODE_ENV === 'production' ? '/CodeStorm-Hub.github.io' : '',
33+
assetPrefix: process.env.NODE_ENV === 'production' ? '/CodeStorm-Hub.github.io/' : '',
34+
};
35+
```
36+
37+
### 2. GitHub Actions Workflow (`.github/workflows/deploy-github-pages.yml`)
38+
39+
Automated deployment workflow that:
40+
- Triggers on pushes to `main` branch
41+
- Can be manually triggered via workflow_dispatch
42+
- Builds the Next.js application as static files
43+
- Deploys to GitHub Pages
44+
45+
### 3. Additional Files
46+
47+
- `.nojekyll`: Prevents GitHub from processing the site with Jekyll
48+
- `404.html`: Custom 404 page (automatically generated by Next.js)
49+
50+
## Deployment Process
51+
52+
### Automatic Deployment
53+
54+
1. **Trigger**: Push changes to the `main` branch
55+
2. **Build**: GitHub Actions runs `npm run build:github-pages`
56+
3. **Export**: Next.js generates static files in `/out` directory
57+
4. **Deploy**: Files are deployed to GitHub Pages
58+
5. **Live**: Site is available at `https://codestorm-hub.github.io/CodeStorm-Hub.github.io/`
59+
60+
### Manual Deployment
61+
62+
You can manually trigger deployment:
63+
1. Go to the repository's Actions tab
64+
2. Select "Deploy to GitHub Pages" workflow
65+
3. Click "Run workflow" on the main branch
66+
67+
## Local Testing
68+
69+
To test the GitHub Pages build locally:
70+
71+
```bash
72+
# Install dependencies
73+
npm install
74+
75+
# Build for GitHub Pages
76+
npm run build:github-pages
77+
78+
# Serve the static files (optional)
79+
npx serve out
80+
```
81+
82+
## Repository Settings
83+
84+
Ensure the following GitHub repository settings are configured:
85+
86+
### Pages Settings
87+
1. Navigate to **Settings** → **Pages**
88+
2. **Source**: Deploy from a branch
89+
3. **Branch**: Select `gh-pages` (created automatically by the workflow)
90+
4. **Folder**: `/ (root)`
91+
92+
### Actions Permissions
93+
1. Navigate to **Settings** → **Actions** → **General**
94+
2. Ensure "Allow all actions and reusable workflows" is selected
95+
3. Under "Workflow permissions", select "Read and write permissions"
96+
97+
## Troubleshooting
98+
99+
### Common Issues
100+
101+
1. **Build Fails**
102+
- Check the Actions tab for error logs
103+
- Ensure all dependencies are properly listed in `package.json`
104+
- Verify TypeScript compilation passes locally
105+
106+
2. **Assets Not Loading**
107+
- Confirm `basePath` and `assetPrefix` are correctly configured
108+
- Check that images use the Next.js `Image` component
109+
- Verify links use Next.js `Link` component
110+
111+
3. **404 Errors on Page Refresh**
112+
- This is expected behavior for client-side routing in GitHub Pages
113+
- The custom 404.html handles fallback routing
114+
115+
4. **Workflow Permissions Error**
116+
- Ensure repository has proper Actions permissions
117+
- Check that GITHUB_TOKEN has necessary permissions
118+
119+
### Validation Steps
120+
121+
After deployment, verify:
122+
- [ ] Site loads at the GitHub Pages URL
123+
- [ ] Navigation works correctly
124+
- [ ] Images and assets load properly
125+
- [ ] All pages are accessible
126+
- [ ] Responsive design works across devices
127+
- [ ] Dark/light mode toggle functions
128+
- [ ] No console errors in browser developer tools
129+
130+
## Performance Optimizations
131+
132+
The GitHub Pages deployment includes several optimizations:
133+
134+
- **Static Generation**: All pages are pre-generated at build time
135+
- **Asset Optimization**: Images and assets are optimized for web delivery
136+
- **Bundle Splitting**: JavaScript is split into optimized chunks
137+
- **CSS Optimization**: Tailwind CSS is purged of unused styles
138+
- **Caching**: Static assets leverage browser caching
139+
140+
## Monitoring
141+
142+
Monitor deployment status:
143+
- **Actions Tab**: View build and deployment logs
144+
- **Pages Settings**: Check deployment status and URL
145+
- **Repository Insights**: Monitor site traffic and performance
146+
147+
## Maintenance
148+
149+
Regular maintenance tasks:
150+
- Monitor GitHub Actions workflow runs
151+
- Update dependencies periodically
152+
- Review and optimize Core Web Vitals
153+
- Test deployment after major changes
154+
- Keep documentation updated
155+
156+
## Custom Domain (Optional)
157+
158+
To use a custom domain:
159+
1. Add a `CNAME` file to the repository root
160+
2. Configure DNS records with your domain provider
161+
3. Update the domain in repository Pages settings
162+
4. Update `basePath` and `assetPrefix` in `next.config.ts`
163+
164+
## Security Considerations
165+
166+
- All builds run in isolated GitHub Actions environments
167+
- No sensitive data is exposed in client-side code
168+
- Dependencies are automatically scanned for vulnerabilities
169+
- HTTPS is enforced by default on GitHub Pages
170+
171+
---
172+
173+
For questions or issues with deployment, please refer to the [GitHub Pages documentation](https://docs.github.com/en/pages) or open an issue in this repository.

‎next.config.ts‎

Lines changed: 13 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,11 +1,21 @@
11
import type { NextConfig } from "next";
22

3+
const isGitHubPages = process.env.NODE_ENV === 'production' && process.env.GITHUB_ACTIONS === 'true';
4+
35
const nextConfig: NextConfig = {
4-
/* config options here */
5-
};
6-
module.exports = {
6+
// Only enable export for GitHub Pages production builds
7+
...(isGitHubPages && { output: 'export' }),
8+
trailingSlash: true,
79
images: {
10+
// Only disable optimization for GitHub Pages
11+
unoptimized: Boolean(isGitHubPages),
812
remotePatterns: [new URL("https://github.com/CodeStorm-Hub.png")],
913
},
14+
// GitHub Pages specific configuration
15+
...(isGitHubPages && {
16+
basePath: '/CodeStorm-Hub.github.io',
17+
assetPrefix: '/CodeStorm-Hub.github.io/',
18+
}),
1019
};
20+
1121
export default nextConfig;

‎package.json‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -5,6 +5,7 @@
55
"scripts": {
66
"dev": "next dev --turbopack",
77
"build": "next build --turbopack",
8+
"build:github-pages": "NODE_ENV=production GITHUB_ACTIONS=true next build --turbopack",
89
"start": "next start",
910
"lint": "eslint"
1011
},

0 commit comments

Comments
 (0)