Thank you for helping improve protocol-launcher. Contributions to protocol integrations, tests, documentation,
examples, and issue triage are welcome.
By participating, you agree to follow the project Code of Conduct.
- Use GitHub Discussions for usage questions, integration help, ideas, and showcases.
- Use GitHub Issues for reproducible bugs, concrete feature proposals, and documentation problems.
- Search existing issues and discussions before opening a new one.
A bug report should include the protocol-launcher version, the generated URL, the expected URL, the affected app
and app version, the operating system, and a public minimal reproduction when possible. Remove API keys, tokens, and
other sensitive values before sharing URLs or payloads.
This repository is a pnpm workspace managed with Turbo. It uses the Node.js version declared in .nvmrc and the pnpm version declared in package.json.
git clone https://github.com/zhensherlock/protocol-launcher.git
cd protocol-launcher
nvm use
corepack enable
pnpm installRun the documentation site, promo video app, and their package watchers together:
pnpm devUse a focused development command when working on one workspace:
pnpm --filter ./packages/protocol-launcher dev
pnpm --filter ./apps/docs dev
pnpm --filter ./apps/promo-video devUse path filters rather than package-name filters because the root package and the published library package are
both named protocol-launcher.
- Create a focused branch from the current
mainbranch. - Keep the change limited to one problem or feature.
- Add or update Vitest coverage for behavior changes.
- Update both
apps/docs/enandapps/docs/zhwhen changing user-facing APIs or documentation. - Add a changeset with
pnpm changesetfor package-visible changes. - Use a Conventional Commit message such as
feat: add raycast protocol supportorfix: encode vscode file paths.
When adding a protocol integration, keep the implementation, exports, tests, and documentation in sync. A typical addition includes:
packages/protocol-launcher/src/<name>/index.ts- the namespace export in
packages/protocol-launcher/src/index.ts - the
./<name>export inpackages/protocol-launcher/package.json packages/protocol-launcher/tests/<name>.test.ts- matching English and Chinese documentation pages and navigation entries
Follow the ordering and conventions of nearby integrations. Do not edit generated output such as dist, coverage,
VitePress build/cache directories, Turbo caches, or rendered promo-video files.
Run the checks relevant to your change before opening a pull request. The CI-equivalent library and documentation checks are:
npx biome check .
pnpm build
pnpm coverageFor a focused library change, run the closest test and package build first:
pnpm test packages/protocol-launcher/tests/vscode.test.ts
pnpm --filter ./packages/protocol-launcher buildFor promo-video changes, run:
pnpm check:promo
pnpm build:promo- Link the related issue or discussion when one exists.
- Explain the problem, the chosen solution, and any tradeoffs.
- Include generated URL examples and the source of the app's official URL-scheme behavior for protocol changes.
- Include screenshots or recordings for visible documentation or promo-video changes.
- Call out breaking changes and migration steps explicitly.
- Keep unrelated formatting, dependency, and generated-file changes out of the pull request.
- Make sure the relevant checks pass and package-visible changes include an appropriate changeset.
Maintainers may ask for a smaller reproduction, official protocol documentation, or additional exact-string tests before reviewing an implementation. This keeps reviews focused and helps prevent invalid or unsafe launch URLs.