Thanks for helping improve the project. Small, focused contributions with tests and clear documentation are easiest to review.
Use Node.js 20.9 or newer and npm. Fork the repository, then clone your fork:
git clone https://github.com/<your-github-user>/devtools-hub.git
cd devtools-hub
npm ci
npm run devOpen http://localhost:3000. Keep the upstream repository as upstream if you want to sync changes:
git remote add upstream https://github.com/zytherdev/devtools-hub.gitgit switch -c feat/short-descriptionUse a concise branch name that describes one change. Avoid mixing unrelated refactors and features.
Every tool has exactly one canonical folder: app/tools/<slug>/. It contains definition.ts (metadata and UI defaults), logic.ts (the public run(input, options) entry point), Tool.tsx (the UI entry), and README.md (usage, options, limitations, and privacy). Put private helpers in that folder's lib/. Tests are at tests/tools/<slug>.test.cjs. Do not create tool-specific code under app/components/tools, app/lib/tools, or a separate route.
The id, folder name, and href slug must be identical. Add the definition to app/tools/registry.ts and the view to app/tools/componentRegistry.ts. The first is the canonical metadata registry; app/lib/utils/tools.ts provides derived catalog/category views to the rest of the app. Keep categories and quick links derived from tool definitions—never duplicate a tool object.
The App Router has one dynamic page at app/(tools)/[slug]/page.tsx; do not add one route page per tool. A standard Tool.tsx composes UniversalTool with its definition and slug; the shared toolEngine.ts dispatches that slug to the folder's logic.ts. Use a bespoke UI in the same Tool.tsx only when richer controls are required. Shared UI primitives belong in app/components; helpers belong in app/lib/tools only when genuinely shared by multiple tools.
Use the shared page header, panel components, global tokens, input/output conventions, and inline error feedback. Support light and dark themes, keyboard access, and narrow screens. Keep processing separate from React state where possible.
- Prefer local processing. If a feature needs a network request, explain the request in the UI and document what input is sent and to which provider.
- Never execute user input or use
eval/Functionto process it. Do not use unsafe deserialization. - Render user-controlled data as text; validate parser options and impose reasonable input, output, depth, and workload limits.
- Handle malformed input with a useful inline error. Do not use blocking dialogs or return an error message as if it were valid output.
- Do not set a tool's status to implemented until its logic and UI are connected and meaningful tests pass.
Before opening a pull request, run:
npm run lint
npm run typecheck
npm test
npm run buildOr run the same sequence with npm run check. If a check cannot run, include the exact command and reason in the PR description.
Push your branch to your fork and open a PR against zytherdev/devtools-hub. Include the problem and intended behavior, a concise change summary, test commands and results, screenshots for visual changes when practical, and any network/data-flow changes.
- The slug, folder, definition, registry entry, route, and output behavior agree.
- The tool uses shared components/tokens and works with both themes and mobile widths.
- Normal, invalid, boundary, and safety-sensitive inputs are tested.
- Per-tool README and coverage status are accurate.
-
npm run lint,npm run typecheck,npm test, andnpm run buildpass.