Deployment

This project deploys the React app to Vercel (live site). At build time, scripts/fetchProjects.js fetches GitHub data and writes static artifacts to public/ before the React build starts. The generated API docs are published separately to GitHub Pages via the gh-pages branch.

Contents

• Deployment targets
• Environment variables
• Deploying to Vercel
• Running locally
• Build artifacts
• Security
• Troubleshooting
• References

Deployment targets

Environment variables

Set these in the Vercel dashboard under Project → Settings → Environment Variables, targeting the Build step for both Production and Preview environments.

Deploying to Vercel

Vercel runs prebuild automatically before build, so no manual intervention is required after the initial setup.

1. Connect the GitHub repository to a Vercel project (first-time setup only).
2. Set GH_PROJECTS_TOKEN in the Vercel dashboard, targeting the Build step.
3. Optionally set DEEPL_API_KEY in the same location.
4. Push to main — Vercel detects the push and starts a new deployment.
5. Vercel runs npm run prebuild (scripts/fetchProjects.js), then npm run build (react-scripts build).
6. Vercel publishes the output from build/ to the live URL.

flowchart LR
    A[Push to main] --> B[Vercel build trigger]
    B --> C[npm run prebuild\nfetchProjects.js]
    C --> D[npm run build\nreact-scripts build]
    D --> E[Publish build/\nto Vercel CDN]

Running locally

Use these steps to preview generated artifacts before committing or deploying.

1. Create a .env.local file at the repository root (gitignored by CRA):

GH_PROJECTS_TOKEN=your_github_pat_here
DEEPL_API_KEY=optional_deepl_key

2. Optionally enable debug output in the current shell only:

$env:DEBUG_FETCH = '1'

3. Run the fetch script to generate artifacts:

node .\scripts\fetchProjects.js

4. Run the React build:

npm run build

5. Optionally prepare and deploy a prebuilt Vercel output:

Remove-Item -Recurse -Force .vercel\output -ErrorAction SilentlyContinue
New-Item -ItemType Directory -Force .vercel\output\static | Out-Null
Copy-Item -Path build\* -Destination .vercel\output\static -Recurse -Force
Copy-Item -Path public\projects.json -Destination .vercel\output\static\projects.json -Force
Copy-Item -Path public\projects_media -Destination .vercel\output\static\projects_media -Recurse -Force

@"
{
  "version": 3,
  "routes": [
    { "handle": "filesystem" },
    { "src": "/(.*)", "dest": "/index.html" }
  ]
}
"@ | Out-File -FilePath .vercel\output\config.json -Encoding utf8

npx vercel --prebuilt . --token $env:VERCEL_TOKEN --yes

Build artifacts

The files public/projects.json and public/projects_media/ are generated by scripts/fetchProjects.js and are intentionally excluded from version control. CI regenerates them on every build. If these files appear committed in the repository, remove them — committing them risks leaking tokens or including large binary blobs.

Security

• Scope the GitHub PAT to the minimum required permissions and rotate it regularly.
• Do not commit tokens to source control — store them in Vercel environment variables or GitHub Actions secrets.
• DEBUG_FETCH can expose sensitive request details in build logs; disable it after debugging.

Troubleshooting

• GraphQL errors during build — verify that GH_PROJECTS_TOKEN is valid and has the correct scope.
• Missing artifacts after build — enable DEBUG_FETCH=1 on a single preview deploy to inspect build logs, then remove it.
• Prebuild failures blocking deployment — the default behaviour is fail-fast. To allow deployments to continue when the fetch fails, modify prebuild in package.json to: node ./scripts/fetchProjects.js || echo 'fetch failed'.

References

• Vercel documentation
• GitHub Pages documentation
• Create React App — environment variables