Contributing
Contributions are welcome! Whether it’s a bug fix, new provider, or documentation improvement.
git clone https://github.com/vineethkrishnan/ipwhoami.gitcd ipwhoamiNo npm install needed — ipwhoami has zero dependencies.
Development
Section titled “Development”Run the CLI directly:
node bin/ipwhoami.js --helpnode bin/ipwhoami.js 8.8.8.8node bin/ipwhoami.js -c 1.1.1.1Check syntax:
node --check src/**/*.js bin/**/*.jsProject Structure
Section titled “Project Structure”ipwhoami/├── bin/ipwhoami.js # CLI entry point├── src/ # CLI source code│ ├── cli.js # Argument parsing & routing│ ├── colors.js # Terminal colors│ ├── config.js # Constants│ ├── formatter.js # Output formatting│ ├── ip.js # IP validation & detection│ └── providers/ # Geolocation provider implementations│ ├── base.js # Shared fetch logic│ ├── index.js # Provider registry│ ├── ipinfo.js # ipinfo.io│ ├── ipapi.js # ipapi.co│ └── ip-api.js # ip-api.com├── test/ # CLI unit & integration tests├── api/ # Self-hosted geolocation API│ ├── src/ # Hono app, DB loader, rate limiter│ ├── test/ # API tests│ └── scripts/ # DB download script├── scripts/ # Standalone Bash/PowerShell├── docs/ # This documentation (Starlight)├── Dockerfile # Docker image for CLI├── package.json├── LICENSE└── README.mdMaking Changes
Section titled “Making Changes”- Create a branch for your change
- Make your edits
- Test locally with
node bin/ipwhoami.js - Submit a pull request
Adding a Provider
Section titled “Adding a Provider”See the Adding a Provider guide for the full walkthrough.
Documentation
Section titled “Documentation”The docs site is built with Astro Starlight. To work on docs:
cd docsnpm installnpm run devThis starts a local dev server at http://localhost:4321.
Code Style
Section titled “Code Style”- ESM modules (
import/export) - No dependencies — use Node.js built-ins
- Keep provider implementations simple and consistent
- Return normalized result shapes from all providers