This file provides guidance when working with code in this repository.

angular-cli-ghpages is an Angular CLI builder/schematic that deploys Angular applications to GitHub Pages, Cloudflare Pages, or any Git repository. It wraps the gh-pages npm package and integrates with Angular CLI's deployment infrastructure via ng deploy.

All development commands must be run from the src directory:

IMPORTANT: The src/.npmrc file contains ignore-scripts=false to override global npm settings. DO NOT DELETE OR MODIFY this file - it's required for build scripts to run.

Build process: prebuild (clean + regenerate schema.d.ts) - build (tsc) - postbuild (copy metadata to dist/).

schema.json is source of truth for deployment options. Editing it requires rebuild.

For testing changes locally with an Angular project:

1. Build and link from src/dist:

   cd src
   npm run build
   cd dist
   npm link

2. In your Angular test project:

   npm link angular-cli-ghpages
   ng add angular-cli-ghpages
   ng deploy --dry-run # Test without deploying

To debug the deploy builder in VSCode, use this launch.json configuration in your Angular project:

Alternatively, debug from command line:

For debugging the standalone engine directly, use the "Launch Standalone Program" task in VSCode (configured in .vscode/launch.json).

Publishing uses npm Trusted Publishers with OIDC - no tokens stored in CI!

1. Go to Actions - Publish to npm
2. Click Run workflow - select branch
3. Leave "Dry-run" checked to test, or uncheck for real publish
4. Wait for approval (5 min timer + required reviewer)

Publishes with provenance attestation for supply chain security.

For pre-release versions, after publishing:

1. Angular CLI Integration (src/deploy/):

   • builder.ts - Angular builder entry point, called by ng deploy
   • actions.ts - Orchestrates build and deployment process
   • schema.json - Defines CLI options/arguments

2. Schematic (src/ng-add.ts):

   • Implements ng add angular-cli-ghpages
   • Adds deploy target to angular.json

3. Standalone CLI (src/angular-cli-ghpages):

   • Bash script for non-Angular CLI usage
   • Uses commander for CLI parsing

4. Core Engine (src/engine/):

   • engine.ts - Core deployment logic (wraps gh-pages)
   • defaults.ts - Default configuration values

Precedence:

1. prerenderTarget - For SSG/prerendering builds (if specified, overrides all others)
2. buildTarget - Standard build target (if specified)
3. Default - ${project}:build:production

Implementation details:

• Static build target: buildTarget || default (see src/deploy/builder.ts)
• Final target: prerenderTarget || staticBuildTarget (see src/deploy/builder.ts)

Output directory resolution:

• Checks angular.json for outputPath
• If string: appends /browser (modern Angular convention)
• If object: uses ${base}/${browser} properties
• Can be overridden with --dir option

The engine automatically injects authentication tokens into HTTPS repository URLs:

1. Discovers remote URL from current git repo (if --repo not specified)
2. Checks environment variables in order: GH_TOKEN, PERSONAL_TOKEN, GITHUB_TOKEN
3. Transforms: https://github.com/... - https://x-access-token:TOKEN@github.com/...

Note: Tokens only work with HTTPS, not SSH URLs (git@github.com).

The engine appends CI metadata to commit messages when running on:

• Travis CI (TRAVIS env var)
• CircleCI (CIRCLECI env var)
• GitHub Actions (GITHUB_ACTIONS env var)

CRITICAL: Angular CLI passes --no-X flags as noX: true, NOT as X: false. The engine must manually invert these:

• --no-dotfiles - Angular passes { noDotfiles: true } - Engine converts to { dotfiles: false }
• --no-notfound - Angular passes { noNotfound: true } - Engine converts to { notfound: false }
• --no-nojekyll - Angular passes { noNojekyll: true } - Engine converts to { nojekyll: false }

1. No Server-Side Rendering: GitHub Pages only supports static files. SSR/Universal build targets are not supported.

2. 404.html Handling:

   • GitHub Pages: Requires 404.html workaround (only way to get SPA routing, but returns HTTP 404 status)
   • Cloudflare Pages: MUST NOT have 404.html - its presence disables native SPA mode
   • Future: Consider changing default or auto-detecting deployment target

3. Jekyll Bypass: Creates .nojekyll to prevent GitHub Pages from processing files through Jekyll (which would break files starting with _ or .txt in assets).

4. Breaking Changes in v2: Changed from guessing build conventions in Angular 17+. Projects may need explicit --build-target specification.

Current deprecated options:

• noSilent - Ignored with warning

Rejected options (v2.1+):

• browserTarget - Actively rejected with clear error message ("Use buildTarget instead"). Not silently ignored - users get explicit feedback.

• Uses Jest (npm test), tests in *.spec.ts files
• Requires git clone with origin remote (see test-prerequisites.spec.ts)
• All tests preserve/restore process.env using originalEnv pattern
• No test counts in documentation - they become stale quickly and are bragging

1. Use .toBe() for scalar equality (strings, numbers, booleans)
2. Use .toContain() for array membership or substring checks in long messages
3. Variable reuse for passthrough (same var = no transformation)
4. Separate variables for transformations (input != expected)

Avoid:

• .toContain('partial') when you could use .toBe(fullExpectedValue)
• Reusing literals instead of variables to show intent

Use proper types, unknown, or Partial instead. For mocks: Partial cast to CompleteType.

For sync considerations with AngularFire, monitor:

• https://github.com/angular/angularfire/blob/master/src/schematics/deploy/builder.ts
• https://github.com/angular/angularfire/blob/master/src/schematics/deploy/actions.ts

When performing GitHub operations (creating issues, PRs, etc.), use the gh CLI tool instead of web requests to avoid rate limiting and authentication issues.