javascript-refactoring

JavaScript Code Refactoring Guide

Use this guide to split JavaScript into maintainable CommonJS modules in gh-aw without drifting into dead embedding patterns.

Overview

The current gh-aw architecture is action-centric:

• Shared JS modules live under pkg/workflow/js/*.cjs and actions/setup/js/*.cjs
• Action source files live under actions/<action-name>/src/
• Generated action bundles are committed under actions/<action-name>/index.js
• Shipping is driven by the action build pipeline (make actions-build, gh aw actions-build) and dependency maps such as pkg/cli/actions_build_command.go
• pkg/workflow/js.go is a stub; it no longer owns the runtime JavaScript shipping path for the main workflows

If you are refactoring a workflow utility, prefer the current action/module architecture over any older //go:embed pattern.

Top-Level Script Pattern

Top-level .cjs scripts executed directly in workflows follow this pattern:

✅ Correct Pattern - Export main, but don't call it:

async function main() {
  // Script logic here
  core.info("Running the script");
}

module.exports = { main };

❌ Incorrect Pattern - Don't call main in the file:

async function main() {
  // Script logic here
  core.info("Running the script");
}

await main(); // ❌ Don't do this!

module.exports = { main };

Why this pattern?

• The workflow bundler or action build step can wrap the script with await main() at execution time
• The module stays importable for tests while still being executable in GitHub Actions
• It makes unit testing easier and preserves a clean module boundary

Step 1: Put the code in the right source tree

Choose the correct location for the module before writing code:

• Shared workflow utilities: pkg/workflow/js/
• Action-specific JavaScript: actions/<action-name>/src/ or actions/setup/js/
• Generated bundle output: actions/<action-name>/index.js

File naming convention:

• Use snake_case for filenames (for example sanitize_content.cjs, load_agent_output.cjs)
• Use .cjs for CommonJS modules
• Keep the name aligned with the responsibility of the module