Contributing

Contributing

Use a supported Node.js 24 release, as CI does, and the pnpm version pinned in package.json. Nuxt requires Node.js ^22.19.0 || ^24.11.0 || >=26.0.0.

# Install dependencies and prepare all development workspaces
pnpm install
pnpm dev:prepare

# Develop with the playground
pnpm dev

# Check formatting, module TypeScript and Vue templates
pnpm fmt:check
pnpm lint

# Check the DevTools client and playground with vue-tsc
pnpm typecheck

# Run unit and in-process functional handler tests
pnpm test

# Build the module, check published types and bundle the DevTools client
pnpm prepack

# Check and build the docs, then run their browser smoke test
pnpm --dir docs verify

The shared checks cover source, tests, scripts and all development apps. Oxlint and Vue template lint require zero warnings. Lint violations and compiler errors fail the check.

End-to-end tests

Provider credentials are declared in secretspec.toml. Configure SecretSpec's e2e provider with access to the nuxt-oidc-auth 1Password vault, then run:

pnpm test:e2e:providers:secrets

Generic OIDC does not require provider credentials. Unconfigured cloud providers are skipped. CI reads the same profile and vault with its own read-only OP_SERVICE_ACCOUNT_TOKEN.

Keycloak coverage stays manual and separate from quick CI and provider-matrix runs. Start deterministic fixture, then run dedicated suite:

docker compose -f test/fixtures/keycloak/compose.yaml up -d --wait
pnpm test:e2e:keycloak
docker compose -f test/fixtures/keycloak/compose.yaml down

Fixture imports realm nuxt-oidc-test with local user testuser / p@ssword.

Release gate

Prepare version and changelog without creating a commit, tag, or publication:

git switch -c release/<version>
pnpm release:prepare -- <version> [--from <previous-release-commit>]

Review generated changes, commit them with signing enabled, and merge them through pull request.

From clean, up-to-date main, record exact release commit and dispatch Provider E2E:

release_commit=$(git rev-parse HEAD)
gh workflow run e2e-providers.yml --ref main

Confirm workflow run succeeded and its headSha equals $release_commit. Configured online-provider and Dex rows must pass; Apple and PayPal remain excluded. Create and push signed tag only from exact verified commit:

pnpm release:tag -- "$release_commit"

Tagging refuses dirty trees, commits other than origin/main, mismatched provider-test commit, missing changelog entry, existing npm version, or existing/mismatched tag. Signed tag records the exact Provider E2E commit. Existing v1.0.0-beta.11 tag must remain untouched.

Configure npm trusted publishing for GitHub organization/user itpropro, repository nuxt-oidc-auth, workflow filename release.yml, no environment, and allow npm publish. After signed-tag Provider E2E succeeds, publish a GitHub prerelease for the tag. The release event publishes npm automatically. Retry a failed Publish npm release run from GitHub Actions so event tag and source provenance remain unchanged. Workflow requires a signed tag in origin/main ancestry with matching event SHA, Provider E2E attestation, changelog/package version, and unpublished npm version. It builds once, packs with lifecycle scripts disabled, and publishes that exact archive with explicit latest dist-tag through GitHub OIDC. npm records provenance without repository npm credentials.