Skip to content

fix: resolve GitHub Pages subdirectory deployment publicPath issues #408

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom
Merged
merged 10 commits into from
Sep 15, 2025
Merged

fix: resolve GitHub Pages subdirectory deployment publicPath issues #408

merged 10 commits into from
Sep 15, 2025

Conversation

takaokouji
Copy link

@takaokouji takaokouji commented Sep 15, 2025 •
edited
Loading

Summary

  • Fix sprite/background selection functionality on GitHub Pages subdirectory deployment
  • Implement automated Node.js post-build script to handle fetch-worker path fixes
  • Simplify CI/CD workflow and improve cross-platform compatibility
  • Eliminate manual sed/gsed commands from build process

Problem

GitHub Pages subdirectory deployment (https://smalruby.jp/smalruby3-gui/) was failing to load worker files because:

  • Worker-loader generated relative paths like "chunks/" + "fetch-worker"
  • These resolved to /chunks/fetch-worker.js instead of /smalruby3-gui/chunks/fetch-worker.js
  • This caused sprite and background selection functionality to break with 404 errors

Solution

Automated Post-Build Processing

  • New Script: scripts/postbuild.mjs automatically detects PUBLIC_PATH environment variable
  • Smart Detection: Only applies fixes when PUBLIC_PATH is set (no changes for default builds)
  • Targeted Replacement: Precisely replaces return "chunks/" + "fetch-worker" with absolute paths
  • Integration: Built into package.json build script: webpack && node ./scripts/postbuild.mjs

CI/CD Workflow Simplification

  • Removed: Manual sed commands from all deployment steps
  • Cleaner: Each deployment step now just runs npm run build with appropriate PUBLIC_PATH
  • Cross-Platform: No more dependency on GNU sed or bash-specific commands

Key Files Changed

  • scripts/postbuild.mjs - New automated post-build processor
  • package.json - Integrated post-build script into build process
  • .github/workflows/ci-cd.yml - Removed manual sed commands
  • CLAUDE.md - Updated local testing documentation (no more gsed required)

Technical Implementation

The post-build script:

  1. Checks if PUBLIC_PATH environment variable is set
  2. If set, reads build/gui.js and build/player.js
  3. Replaces relative fetch-worker paths with absolute paths using PUBLIC_PATH
  4. Logs the fixes applied for transparency

Example transformation:

// Before (webpack output)
return "chunks/" + "fetch-worker" + "." + "hash" + ".js";

// After (with PUBLIC_PATH=/smalruby3-gui/)
return "/smalruby3-gui/chunks/" + "fetch-worker" + "." + "hash" + ".js";

Test Plan

  • Local build without PUBLIC_PATH - no changes applied
  • Local build with PUBLIC_PATH="/smalruby3-gui/" - paths correctly fixed
  • Manual Python server testing confirms functionality works
  • Verified failure case without fixes (404 errors)
  • CI/CD pipeline updated and tested
  • Deploy to test branch and verify sprite/background selection works on actual GitHub Pages

Benefits

  • Developer Experience: No manual gsed commands needed locally
  • Cross-Platform: Works on macOS, Linux, Windows (Node.js only)
  • Maintainable: Single script handles all path fixing logic
  • Reliable: Automated process reduces human error
  • Efficient: Only processes files when PUBLIC_PATH is actually set

Breaking Changes

None. This is a bug fix that maintains backward compatibility while simplifying the development workflow.

🤖 Generated with Claude Code

takaokouji and others added 10 commits September 15, 2025 16:57
@takaokouji @claude
fix: resolve GitHub Pages subdirectory deployment publicPath issues
3456358 
- Configure webpack publicPath to use PUBLIC_PATH environment variable
- Add rebuild steps in CI/CD for different deployment targets:
  - smalruby.app: uses existing build with PUBLIC_PATH="/"
  - smalruby3-gui: rebuilds with PUBLIC_PATH="/smalruby3-gui/"
  - branch deployments: rebuilds with PUBLIC_PATH="/smalruby3-gui/<branch>/"
- Fix sprite/background selection functionality on GitHub Pages subdirectory
- Maintain efficient build process by reusing test build for smalruby.app

Fixes asset loading issues where chunks were expected at root path
but deployed to subdirectories.

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <[email protected]>
@takaokouji @claude
fix: remove trailing comma in webpack.config.js
4189148 
Address lint error (comma-dangle) in distConfig configuration.

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <[email protected]>
@takaokouji @claude
fix: change PUBLIC_PATH default from '/' to 'auto' for integration te…
fcb7dc7 
…st compatibility

- Set publicPath default to 'auto' instead of '/' to generate relative paths
- Fixes integration test failures where file:// protocol requires relative paths
- Maintains compatibility with environment variable override for deployment

Integration test now passes after this change:
✓ Ruby Tab: Mesh extension blocks › Ruby -> Code -> Ruby

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <[email protected]>
@takaokouji @claude
fix: use PUBLIC_PATH environment variable in WebpackPwaManifest
a14de4d 
- Replace hardcoded publicPath: './' with process.env.PUBLIC_PATH || 'auto'
- Ensures consistent path handling across all webpack plugins
- Allows PWA manifest to use correct base path for different deployments

Test confirmed: PUBLIC_PATH="/smalruby3-gui/" now correctly generates
<script defer src="/smalruby3-gui/gui.js"></script> in index.html

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <[email protected]>
@takaokouji @claude
feat: attempt to fix worker-loader publicPath with NormalModuleReplac…
2ab94ad 
…ementPlugin

- Add NormalModuleReplacementPlugin to override worker-loader options
- Ensure PUBLIC_PATH environment variable is passed to worker chunks
- This is part of comprehensive fix for GitHub Pages subdirectory deployment

Related to fetch-worker.js path resolution issue where workers were
requesting relative paths instead of respecting publicPath setting.

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <[email protected]>
@takaokouji @claude
feat: add post-build worker path fix to CI/CD workflow
e489ebb 
- Add sed command to fix worker-loader chunk paths after build
- Replace relative 'chunks/' paths with absolute '/smalruby3-gui/chunks/' paths
- Apply fix for both smalruby3-gui and branch deployments
- This addresses worker-loader not respecting webpack publicPath setting

The fix ensures fetch-worker.js is requested from correct absolute path
instead of relative path on GitHub Pages subdirectory deployments.

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <[email protected]>
@takaokouji @claude
fix: resolve ESLint errors in webpack.config.js
68b0149 
- Remove unnecessary escape characters in regex patterns
- Fix arrow function formatting by removing unnecessary parentheses
- Maintain functionality while adhering to ESLint rules

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <[email protected]>
@takaokouji @claude
feat: automate fetch-worker path fixes with Node.js post-build script
4be607e 
- Add scripts/postbuild.mjs to automatically fix fetch-worker paths when PUBLIC_PATH is set
- Integrate post-build script into npm build process in package.json
- Remove manual sed commands from CI/CD workflow (.github/workflows/ci-cd.yml)
- Update CLAUDE.md documentation to reflect automated process (no more gsed required)
- Simplify local testing workflow - just set PUBLIC_PATH and run npm build
- Improve cross-platform compatibility by removing bash sed dependency

This resolves GitHub Pages subdirectory deployment issues for worker loading
while maintaining a clean, automated build process.

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <[email protected]>
@takaokouji @claude
feat: enhance fetch-worker path fixing with robust pattern matching
1a51c3a 
- Improved postbuild.mjs script with additional regex pattern for arrow functions
- Fixed webpack externals configuration syntax
- Resolved import path issues in ruby-to-blocks-converter
- Enhanced pattern detection for worker-loader generated code

This completes the GitHub Pages publicPath fix to ensure sprite/background
selection functionality works correctly on subdirectory deployments.

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <[email protected]>
@takaokouji @claude
fix: add missing .nojekyll file creation in CI/CD workflow
2b714ad 
- Add explicit .nojekyll file creation before each GitHub Pages deployment
- Fix "no such file or directory: build/.*" error in peaceiris/actions-gh-pages
- Ensure Jekyll is properly disabled for all deployments
- Add CNAME creation for smalruby.app deployment

This resolves the CI error where the deployment action was trying to copy
hidden files that didn't exist in the build directory.

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <[email protected]>
@takaokouji takaokouji merged commit fdb6b66 into develop Sep 15, 2025
2 checks passed
@takaokouji takaokouji deleted the fix/github-pages-public-path branch September 15, 2025 18:25
github-actions bot pushed a commit that referenced this pull request Sep 15, 2025
@takaokouji
Build for fdb6b66 Merge pull request #408 from smalruby/fix/github-pa…
cbac4a2 
…ges-public-path

fix: resolve GitHub Pages subdirectory deployment publicPath issues
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Reviewers
No reviews
Assignees
No one assigned
Labels
None yet
Projects
None yet
Milestone
No milestone
Development

Successfully merging this pull request may close these issues.
1 participant
@takaokouji