Set up GitHub Pages deployment with static export - #1
Merged
Conversation
Add a workflow that builds on every push and deploys main to Pages via the Actions artifact flow. Pages is a static host, so switch Next.js to `output: "export"` with image optimization off. A project site lives under /<repo>, so the build passes that prefix to basePath/assetPrefix as NEXT_PUBLIC_BASE_PATH; the value is empty locally, and committing a domain to public/CNAME switches it to the root for a custom domain. basePath is not applied to `next/image` sources when images are unoptimized, so import the three image assets instead of referencing them as root-relative URLs — the bundler emits those with the prefix. The build deliberately does not call actions/configure-pages: GITHUB_TOKEN cannot create the Pages site on this org, and a failure there would break the build on every branch rather than just the deploy. Pages has to be pointed at GitHub Actions once by hand. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01CKwW1rRwjbAA2CZZh6tWh8
zagdrath
force-pushed
the
claude/nextjs-github-pages-workflow-n2pumu
branch
from
July 26, 2026 01:14
cb3e003 to
214e2ca
Compare
Add public/CNAME so each deploy asserts the custom domain on Pages. The workflow already keys the base path off that file, so the build switches from the /quartz-systems-website project path to the root. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01CKwW1rRwjbAA2CZZh6tWh8
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
This PR configures the project for deployment to GitHub Pages as a static site.
Summary
The project is now configured to build as a static export and deploy to GitHub Pages via a new CI/CD workflow. This includes updating the Next.js configuration, adding a GitHub Actions workflow, and adjusting image imports to work correctly with the base path prefix used for project sites.
Key Changes
Added GitHub Actions workflow (
.github/workflows/deploy.yml): Builds on every push and deploys themainbranch to GitHub Pages. The workflow handles Pages enablement, builds the static export, runs linting, and deploys the artifact.Updated Next.js configuration (
next.config.ts):output: "export"for static generationbasePathandassetPrefixconfiguration that reads fromNEXT_PUBLIC_BASE_PATHenvironment variable (set by the workflow for project sites, empty for local builds and custom domains)trailingSlashfor proper static routingunoptimized: true) since GitHub Pages is a static hostUpdated image imports in three components (
site-nav.tsx,site-footer.tsx,products.tsx): Changed from URL-based references (src="/assets/...") to ES module imports so that asset URLs are rewritten by the bundler to include the base path prefix. This prevents 404s when the site is served from a subdirectory.Updated README with deployment documentation explaining the static export setup, base path handling, and one-time repository configuration needed.
Implementation Details
The base path approach allows the same build to work both as a project site (served from
/<repo>) and behind a custom domain (served from/). Theconfigure-pagesaction automatically derives the correct base path from the repository's Pages configuration, eliminating the need for manual config changes when switching between deployment modes.https://claude.ai/code/session_01CKwW1rRwjbAA2CZZh6tWh8