https://github.com/somritdasgupta/quefork
queFork is a simple, lightweight web API testing platform. Supports REST HTTP requests and real-time websockets protocols.
https://github.com/somritdasgupta/quefork
api-documentation api-testing rest-api serverless-framework websocket
Last synced: 4 months ago
JSON representation
queFork is a simple, lightweight web API testing platform. Supports REST HTTP requests and real-time websockets protocols.
- Host: GitHub
- URL: https://github.com/somritdasgupta/quefork
- Owner: somritdasgupta
- License: mit
- Created: 2025-01-15T08:54:22.000Z (over 1 year ago)
- Default Branch: main
- Last Pushed: 2025-12-14T16:29:22.000Z (6 months ago)
- Last Synced: 2025-12-17T01:55:33.276Z (6 months ago)
- Topics: api-documentation, api-testing, rest-api, serverless-framework, websocket
- Language: TypeScript
- Homepage: https://quefork.somritdasgupta.in
- Size: 4.49 MB
- Stars: 3
- Watchers: 1
- Forks: 0
- Open Issues: 5
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
queFork
Fast API testing client for REST, GraphQL, SOAP, WebSocket, SSE and Socket.IO
---
## Table of Contents
- [Overview](#overview)
- [Supported Protocols](#supported-protocols)
- [Features](#features)
- [Getting Started](#getting-started)
- [Docker](#docker)
- [Chrome Extension](#chrome-extension)
- [queFork Agent](#quefork-agent)
- [Custom CORS Proxy](#custom-cors-proxy)
- [Project Structure](#project-structure)
- [Tech Stack](#tech-stack)
- [Deployment](#deployment)
- [CI/CD](#cicd)
- [Contributing](#contributing)
- [License](#license)
---
## Overview
queFork is a browser-based API testing client that works entirely offline after first load. It supports six protocols, runs as a PWA for localhost testing, and requires zero backend setup. All data is stored locally in the browser.
---
## Supported Protocols
| Protocol | Capabilities |
|----------|-------------|
| REST | GET, POST, PUT, PATCH, DELETE, OPTIONS, HEAD with headers, params, and body |
| GraphQL | Query editor, variables panel, schema introspection |
| SOAP | XML envelope editor, Content-Type auto-detection |
| WebSocket | Bidirectional messaging, sub-protocol support |
| Socket.IO | Event-based messaging, transport configuration, event listeners |
| SSE | Auto-reconnect, event buffering, real-time statistics |
---
## Features
| Category | Details |
|----------|---------|
| Scripting | Pre/post request JavaScript with `qf.*` API |
| Variables | Environment variables using `{{variable}}` syntax |
| Collections | Organize requests into folders with workspace isolation |
| Code Export | cURL import and export to 14 languages |
| CORS | Built-in proxy cascade with custom proxy support |
| History | Searchable request history with date grouping |
| Auth | OAuth 2.0, Bearer, Basic, API Key |
| Themes | Dark and light mode |
| Offline | Full PWA support for localhost testing without internet |
| Dynamic Favicon | Green/red status dot on favicon based on response codes |
---
## Getting Started
### Prerequisites
- Node.js 18 or higher
- npm (included with Node.js)
### Steps
1. Clone the repository
```bash
git clone https://github.com/somritdasgupta/queFork.git
```
2. Navigate to the project directory
```bash
cd queFork
```
3. Install dependencies
```bash
npm install
```
4. Start the development server
```bash
npm run dev
```
5. Open the app at `http://localhost:8080`
### Available Scripts
| Command | Description |
|---------|-------------|
| `npm run dev` | Start development server with hot reload |
| `npm run build` | Create production build |
| `npm run preview` | Preview production build locally |
| `npm run lint` | Run ESLint checks |
| `npm test` | Run test suite |
| `npm run secrets:vercel` | Auto-set `VERCEL_*` GitHub secrets from local Vercel config |
---
## Docker
### Build and run locally
```bash
docker compose up -d
```
The app will be available at `http://localhost:3000`.
### Manual build
```bash
docker build -t quefork .
docker run -d -p 3000:80 quefork
```
### Pull from GitHub Container Registry
```bash
docker pull ghcr.io/somritdasgupta/quefork:latest
docker run -d -p 3000:80 ghcr.io/somritdasgupta/quefork:latest
```
### Docker configuration
| File | Purpose |
|------|---------|
| `Dockerfile` | Multi-stage build: Node 20 Alpine for build, Nginx Alpine for serving |
| `docker-compose.yml` | Single-command setup with health checks |
| `docker/nginx.conf` | Gzip, SPA routing, caching, security headers |
| `.dockerignore` | Excludes node_modules, .git, and non-essential files |
---
## Chrome Extension
A side-panel extension for CORS-free API testing directly inside Chrome.
### Installation
1. Open Chrome and navigate to `chrome://extensions`
2. Enable "Developer mode" in the top right
3. Click "Load unpacked"
4. Select the `chrome-extension/` folder from this repository
5. Click the queFork icon in the toolbar to open the side panel
All requests route through Chrome's background service worker, bypassing CORS restrictions entirely.
---
## queFork Agent
A lightweight local proxy for testing against localhost, private networks, and APIs that block browser requests.
### Installation
```bash
npm install -g quefork-agent
quefork-agent
```
### Options
| Flag | Description |
|------|-------------|
| `--port 9120` | Custom port |
| `--verbose` | Enable verbose logging |
Agent status appears in the app footer. When the agent is running, all requests are routed through it instead of the built-in CORS proxy.
---
## Custom CORS Proxy
Deploy your own proxy on Vercel for persistent CORS bypass:
```javascript
// api/proxy.js
export default async function handler(req, res) {
res.setHeader('Access-Control-Allow-Origin', '*');
res.setHeader('Access-Control-Allow-Methods', 'GET,POST,PUT,PATCH,DELETE,OPTIONS');
res.setHeader('Access-Control-Allow-Headers', '*');
if (req.method === 'OPTIONS') return res.status(200).end();
const { url, method, headers, body } = req.body;
const response = await fetch(url, {
method: method || 'GET',
headers: headers || {},
body: body ? JSON.stringify(body) : undefined,
});
const data = await response.text();
res.status(200).json({ status: response.status, body: data });
}
```
```bash
vercel deploy
```
---
## Project Structure
```
quefork/
├── src/
│ ├── components/ UI components
│ │ ├── AuthEditor OAuth 2.0, Bearer, Basic, API Key
│ │ ├── CodeEditor CodeMirror-based editor
│ │ ├── KeyValueEditor Drag-and-drop key-value pairs
│ │ ├── RealtimePanel WebSocket and Socket.IO
│ │ ├── RequestTabs Params, Headers, Body, Scripts
│ │ ├── ResponsePanel Body, Preview, Headers, Tests
│ │ └── ui/ shadcn/ui primitives
│ ├── lib/
│ │ ├── api-client Request execution and CORS cascade
│ │ ├── curl-parser Import/export for 14 languages
│ │ ├── dynamic-favicon Status dot overlay on favicon
│ │ └── secure-storage Encrypted localStorage
│ ├── assets/
│ │ └── brand/ Master brand assets (single source of truth)
│ ├── pages/
│ │ └── Index Main app layout and state management
│ └── types/
│ └── api TypeScript interfaces
├── chrome-extension/ Chrome side panel extension
├── docker/ Nginx configuration
├── .github/workflows/ CI/CD pipelines
├── Dockerfile Multi-stage production build
└── docker-compose.yml Container orchestration
```
---
## Tech Stack
| Technology | Role |
|-----------|------|
| React 18 | UI framework |
| TypeScript | Type safety |
| Vite | Build tooling and dev server |
| Tailwind CSS | Utility-first styling |
| shadcn/ui | Component primitives |
| CodeMirror 6 | Code editors |
| socket.io-client | Socket.IO protocol support |
| vite-plugin-pwa | PWA and offline support |
| Nginx | Production static file serving |
---
## Deployment
### Vercel
```bash
npm install -g vercel
vercel login
vercel link
npm run secrets:vercel
```
When Vercel asks for your code directory, use `.` (repository root).
Required repository secrets for deploy workflows:
- `VERCEL_TOKEN`
- `VERCEL_ORG_ID`
- `VERCEL_PROJECT_ID`
The `npm run secrets:vercel` command sets all three automatically after `vercel login` and `vercel link`.
### Netlify
```bash
npm run build
# Deploy the dist/ folder via Netlify dashboard or CLI
```
### Docker
See the [Docker](#docker) section above.
### Self-hosted
```bash
npm run build
# Serve the dist/ folder with any static file server
npx serve dist
```
---
## CI/CD
| Workflow | Trigger | Description |
|----------|---------|-------------|
| `ci.yml` | Push to main/develop, pull requests | Lint, test, and build matrix checks |
| `build-deploy.yml` | Push to main, manual dispatch | Build + deploy summary workflow |
| `edge-deploy.yml` | Push to main/develop, pull requests, manual dispatch | Type check, build, deploy to Vercel |
| `docker-publish.yml` | Push to main, tags, manual dispatch | Build and push Docker image to GHCR |
| `extension-release.yml` | Tag push `extension-v*`, manual dispatch | Package Chrome extension and publish GitHub release |
| `dependency-update.yml` | Weekly schedule, manual dispatch | Update dependencies, verify build, create PR |
### Extension Release Automation
Automatic release from tag:
```bash
git tag extension-v2.1.0
git push origin extension-v2.1.0
```
Manual release is still available from the Actions tab via `workflow_dispatch`.
### Badge Status Note
GitHub Actions badges show `no status` until that workflow has at least one run on the default branch.
---
## Contributing
1. Fork the repository
2. Clone your fork
```bash
git clone https://github.com/YOUR_USERNAME/queFork.git
cd queFork
npm install
```
3. Create a feature branch
```bash
git checkout -b feature/your-feature
```
4. Make changes and test
```bash
npm run dev
npm test
npm run lint
```
5. Commit and push
```bash
git add .
git commit -m "Add your feature"
git push origin feature/your-feature
```
6. Open a pull request on GitHub
---
## License
MIT -- [Somrit Dasgupta](https://github.com/somritdasgupta)