Developer Setup

Relevant source files

The following files were used as context for generating this wiki page:

• CONTRIBUTING.md
• README.md
• package.json
• src/admin-html.ts
• src/server.ts
• src/index.ts
• SECURITY.md
• src/utils/validation.ts
• src/handlers/admin.ts

This document provides a comprehensive guide for setting up the gr8hopper development environment. It covers the initial setup, running the application in its different deployment modes, project structure, and key development workflows. The project is a TypeScript-based URL redirect service built on the Hono framework, designed for high performance and deployable to both Node.js servers and Cloudflare Workers.

The setup process is designed to support development for both target platforms. Developers can run a local server that mimics a VPS deployment or use the Wrangler CLI to emulate the Cloudflare Workers environment. Understanding both is crucial for contributing to the project.

Sources: CONTRIBUTING.md, README.md

1. Prerequisites

Before you begin, ensure you have the following installed on your system:

• Node.js: Version 20 or higher.
• npm: Comes bundled with Node.js.
• Git: For cloning the repository.

The project uses tsx for hot-reloading in Node.js development and wrangler for Cloudflare Workers development, both of which are managed as dev dependencies in package.json.

Sources: package.json:62-69, CONTRIBUTING.md:7

2. Initial Setup

The initial setup involves cloning the repository and installing the required dependencies.

1. Fork and Clone the Repository:

   git clone https://github.com/dima6312/gr8hopper.git
   cd gr8hopper
   

2. Install Dependencies:
   This command installs all necessary dependencies, including Hono, TypeScript, ESLint, and development tools like Wrangler.

   npm install
   

Sources: CONTRIBUTING.md:6-7, package.json:51-69

3. Running the Application Locally

gr8hopper can be run in two distinct modes for local development, each corresponding to a production deployment target.

3.1. Node.js / VPS Mode

This mode simulates a traditional server deployment using a Node.js server. It uses a local JSON file for data storage.

To start the server:

npm run dev:node

This command uses tsx to watch for file changes and restart the server automatically.

Required Configuration:
For the server to start, you must set ADMIN_USERNAME and ADMIN_PASSWORD as environment variables. The server will exit with a fatal error if they are not set. For security, the username admin is explicitly disallowed.

export ADMIN_USERNAME=your-dev-username
export ADMIN_PASSWORD=your-dev-password
npm run dev:node

The following diagram illustrates the startup process for the Node.js server.

This flow shows how the server initializes, validates required credentials, sets up storage, and starts listening for requests.

Sources: CONTRIBUTING.md:8, package.json:13, src/server.ts:80-111

3.2. Cloudflare Workers Mode

This mode uses wrangler to run a local development server that emulates the Cloudflare Workers environment. It uses a local file to simulate the KV namespace for data storage.

To start the server:

npm run dev

Required Configuration:
This mode relies on a .dev.vars file in the project root to load environment variables, including the required ADMIN_USERNAME and ADMIN_PASSWORD.

Create a .dev.vars file:

# .dev.vars
ADMIN_USERNAME="your-dev-username"
ADMIN_PASSWORD="your-dev-password"

The following sequence diagram shows the request handling flow on a cold start in the Workers environment.

On subsequent requests, the initialized handlers are reused, skipping the setup steps.

Sources: CONTRIBUTING.md:8, package.json:12, src/index.ts:16-52

4. Project Structure

The project is organized into modules with clear responsibilities, facilitating maintenance and contributions.

This diagram shows the relationship between the entry points, core logic modules, and configuration files.

Directory/File	Description	Source
src/index.ts	Entry point for Cloudflare Workers. Initializes storage and handlers on first request.	src/index.ts
src/server.ts	Entry point for Node.js/Bun/Docker. Sets up an HTTP server using @hono/node-server.	src/server.ts
src/handlers/	Contains Hono request handlers. admin.ts for the API and redirect.ts for the core redirect logic.	README.md:256-259
src/storage/	Contains storage adapters (KVAdapter, JsonFileAdapter) that implement the StorageAdapter interface.	README.md:260-263
src/middleware/	Contains Hono middleware, such as auth.ts for Basic Authentication.	README.md:264-265
src/utils/	Utility functions for validation (validation.ts) and sanitization (sanitize.ts).	README.md:266-268
src/admin-html.ts	A single function that returns the complete HTML, CSS, and JavaScript for the admin panel.	src/admin-html.ts
routes.json	Default storage file for routes and settings when running in Node.js mode.	src/server.ts:77
wrangler.toml	Configuration file for the Cloudflare Workers deployment and local development.	README.md:269

Sources: CONTRIBUTING.md:38-46, README.md:253-273

5. Development Workflow

The standard workflow for making changes involves creating a feature branch, implementing changes, and ensuring all checks pass before opening a pull request.

5.1. NPM Scripts

The package.json file defines several scripts to aid in development:

Script	Description	Source
dev	Runs the Cloudflare Workers local dev server using wrangler dev.	package.json:12
dev:node	Runs the Node.js server with hot-reloading using tsx watch.	package.json:13
build	Compiles TypeScript to JavaScript in the dist/ directory.	package.json:14
test	Runs the test suite using vitest.	package.json:20
lint	Lints the src/ directory using ESLint.	package.json:18
import:routes	A script to bulk import routes from a JSON file into Cloudflare KV.	package.json:17

5.2. Code Style and Quality

• TypeScript: The project uses TypeScript with strict mode enabled for strong type safety.
• Linting: ESLint is configured to enforce code style and catch common errors. Run npm run lint to check your code.
• Type Checking: Before committing, run npx tsc --noEmit to ensure there are no TypeScript compilation errors.
• Commit Messages: Follow conventional commit message formats (e.g., feat:, fix:, docs:).

Sources: CONTRIBUTING.md:10-36, package.json:18-24

6. Security in Development

Even in a local development environment, gr8hopper enforces basic security measures that developers must be aware of.

• Mandatory Admin Credentials: The application will not start without ADMIN_USERNAME and ADMIN_PASSWORD being set. This prevents accidental deployment without security.
• Username Restriction: The username admin is disallowed to discourage the use of weak, default credentials.
• Input Validation: The admin API includes robust validation for all inputs. For example, route IDs are validated with validateRouteIdPattern to prevent malformed patterns, and destination URLs are checked with isValidUrlScheme to block dangerous protocols like javascript:.

// Example from src/handlers/admin.ts
const idValidation = validateRouteIdPattern(id)
if (!idValidation.valid) {
  return c.json({ error: `Invalid route ID: ${idValidation.reason}` }, 400)
}

const config = validateRouteConfig(body)
if (!config) {
  return c.json({ error: 'Invalid route configuration' }, 400)
}

This snippet shows how route ID patterns and configurations are validated upon creation.

Sources: src/server.ts:80-111, src/handlers/admin.ts:110-119, src/utils/validation.ts:40-62, SECURITY.md:14-19