Contributing

Thanks for helping improve GenX API. This guide explains the contribution process, coding standards, and release workflow.

Code of Conduct

Participation is governed by the Contributor Covenant. Be respectful, inclusive, and collaborative.

Development Environment

git clone https://github.com/genxapi/genxapi.git
cd genxapi
npm install
npm run build:cli
npm run genxapi:cli -- --help

💡 Tip: Use npm run build:cli while iterating on CLI or template changes. Run npm run build when you want the full workspace build.

Useful Scripts

Script	Description
`npm run build`	Builds the template and CLI.
`npm run build:cli`	Rebuilds the local CLI plus the in-repo templates it depends on.
`npm run genxapi:cli -- --help`	Runs the locally built CLI from the monorepo root.
`npm run genxapi:example:orval`	Regenerates the Orval sample into `examples/multi-client-demo`.
`npm run genxapi:example:kubb`	Regenerates the Kubb sample into `examples/multi-client-kubb`.
`npm run test`	Runs Vitest suites for each workspace.
`npm run lint`	Lints all TypeScript sources.
`npm run typecheck`	Type-checks without emitting files.
`npm run clean`	Removes `dist/` folders across workspaces.
`npm run pack:cli:smoke`	Verifies the packaged CLI tarball and bin entrypoints separately from the local dev flow.

Local CLI & Examples

Use the root genxapi:* scripts when validating CLI and template changes locally:

npm run build:cli
npm run genxapi:cli -- --help

npm run genxapi:cli -- ... is intentionally fast and assumes you have already run npm run build:cli after changing CLI or template code.

That repo-local shortcut is for monorepo development only. The public command surface remains npx genxapi generate ... and npx genxapi publish ....

Dry-run both bundled configs before doing a real generation:

npm run genxapi:cli -- generate --config samples/orval-multi-client.config.json --template orval --dry-run
npm run genxapi:cli -- generate --config samples/kubb-multi-client.config.json --template kubb --dry-run

When you need the tracked examples refreshed, use the shortcut scripts:

npm run genxapi:example:orval
npm run genxapi:example:kubb

Those commands generate into examples/multi-client-demo and examples/multi-client-kubb. They also install dependencies inside each generated package because template installDependencies defaults to true.

To rerun the native generator from inside either example package:

cd examples/multi-client-demo
npm run generate

cd ../multi-client-kubb
npm run generate

Current caveats:

The generated example packages do not currently ship src/**/*.test.ts, so npm test is not a useful validation step there yet.
Real example generation and regeneration require network access because the sample configs fetch the live Swagger Petstore spec.
npm run genxapi:example:orval and npm run genxapi:example:kubb rewrite tracked example directories, so review your diff after running them.

Project Structure

packages/
├── template-orval/  # Orval adapter (schema + generateClients)
├── template-kubb/   # Kubb adapter
└── cli/            # CLI implementation, commands, unified schema
docs/                            # User-facing documentation (this folder)
examples/                        # Sample configs and generated outputs
samples/                         # Reference configuration files

Coding Guidelines

TypeScript: Target ES2022, enable strict mode, and prefer explicit return types.
Testing: Add coverage to Vitest suites for new features. Use snapshot tests for template output when feasible.
Formatting: Run npm run format before submitting. The repo enforces Prettier defaults (2 spaces, single quotes where applicable).
Commits: Follow Conventional Commits (feat, fix, docs, chore, etc.). This keeps changelog automation reliable.

🛠️ Tip: If you touch both template and CLI, split changes into separate commits for clarity.

Pull Request Checklist

Tests pass locally (npm test).
Types compile (npm run typecheck).
Documentation updated when behaviour changes.
Run npm version if the change requires publishing a new template or CLI release.
Fill out the PR template with context, testing steps, and screenshots when relevant.

Working on Documentation

Update Markdown pages under docs/.
Use callouts (> 💡 Tip) for noteworthy hints.
Keep section titles in Title Case.
Link to related pages using relative paths (./configuration.md).

Releasing

Use Conventional Commits in the PR you plan to merge (fix, feat, and BREAKING CHANGE drive release types).
Merge the PR into main.
.github/workflows/publish-template-orval.yml, .github/workflows/publish-template-kubb.yml, and .github/workflows/publish-cli.yml run semantic-release for their matching package only.
The repo-local package-scoped semantic-release plugin filters commits per package, applies the correct SemVer bump, publishes to npm, and creates package-specific git tags plus GitHub releases.
Keep genxapi manual unless the proxy package itself changes:
- npm run publish -- --workspace genxapi --pkg-manager npm --access public
Optionally run npx genxapi publish --token <token> --owner <owner> --repo <repo> --tag vX.Y.Z to create an additional GitHub release from the CLI itself.

⚠️ Warning: npm disallows publishing over an existing version. semantic-release now handles version selection for the scoped packages, but manual releases such as genxapi still require you to choose a new version yourself.

Getting Help

Open a GitHub Discussion for feature ideas or questions.
File issues with reproduction steps and configuration snippets.
Join the roadmap conversation in Next Steps.

Thank you for contributing! Your improvements help teams ship reliable SDKs faster.

Next Steps

Review the Versioning guide to understand release expectations.
Explore the Next Steps roadmap to see where help is most needed.

Next: Next Steps →