diff --git a/CLAUDE.md b/CLAUDE.md index 8a5fe1c..738013c 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -34,13 +34,17 @@ src/ ### Common Commands ```bash -npm run dev # Start development server +npm run dev # Start Next.js development server +npm run preview # Build and run with local Cloudflare Workers simulation npm run build # Build for production npm run test # Run tests npm run lint # Run ESLint npm run typecheck # Run TypeScript checks +npm run deploy # Deploy to production ``` +For more commands, see the [Local Development Guide](docs/LOCAL_DEVELOPMENT.md). + ### Testing Checklist - [ ] Encryption/decryption works correctly diff --git a/README.md b/README.md index ec3e4de..b32231a 100644 --- a/README.md +++ b/README.md @@ -62,12 +62,11 @@ Simply open the shared link - the decryption key is in the URL fragment and neve ### Prerequisites -- Node.js 18+ +- Node.js 20+ - npm or yarn -- Cloudflare account (for Workers and R2) -- Wrangler CLI (`npm install -g wrangler`) +- Git -### Setup +### Quick Start ```bash # Clone the repository @@ -77,19 +76,14 @@ cd ghostpaste # Install dependencies npm install -# Login to Cloudflare -wrangler login - -# Create R2 bucket -wrangler r2 bucket create ghostpaste-bucket - -# Copy wrangler configuration -cp wrangler.toml.example wrangler.toml - -# Run development server -npm run dev +# Start development server +npm run dev # Next.js development (hot reload) +# OR +npm run preview # Full Cloudflare Workers simulation ``` +See our [Local Development Guide](./docs/LOCAL_DEVELOPMENT.md) for detailed setup instructions. + ### Configuration Create a `wrangler.toml` file: diff --git a/docs/LOCAL_DEVELOPMENT.md b/docs/LOCAL_DEVELOPMENT.md new file mode 100644 index 0000000..249eacc --- /dev/null +++ b/docs/LOCAL_DEVELOPMENT.md @@ -0,0 +1,189 @@ +# 🚀 Local Development Setup + +This guide explains how to set up and run GhostPaste locally for development. + +## Prerequisites + +- Node.js 20.x or later +- npm or yarn +- Git + +## Initial Setup + +1. **Clone the repository** + + ```bash + git clone https://github.com/nullcoder/ghostpaste.git + cd ghostpaste + ``` + +2. **Install dependencies** + + ```bash + npm install + ``` + +3. **Set up local environment variables** + Create a `.dev.vars` file in the root directory: + ```bash + # Local development secrets + # Add any local development secrets here + # Example: + # API_SECRET=your-secret-here + ``` + +## Development Workflows + +### Standard Next.js Development + +For regular Next.js development without Cloudflare Workers features: + +```bash +npm run dev +``` + +This starts the Next.js development server at `http://localhost:3000` with hot module replacement. + +### Cloudflare Workers Development + +For development with full Cloudflare Workers features (R2, KV, etc.): + +```bash +npm run preview +``` + +This command: + +1. Builds the app with `@opennextjs/cloudflare` +2. Starts wrangler dev with local Miniflare v3 simulation +3. Persists local state to `.wrangler/state` directory + +#### Local vs Remote Development + +- **Local development (default)**: Uses Miniflare v3 to simulate Cloudflare services locally + + ```bash + npm run preview # Local simulation (no billing) + ``` + +- **Remote development**: Connects to actual Cloudflare services + ```bash + npm run preview:remote # Uses real Cloudflare resources (may incur charges) + ``` + +## Available Scripts + +| Script | Description | +| ------------------------ | ------------------------------------------------- | +| `npm run dev` | Start Next.js development server | +| `npm run build` | Build Next.js for production | +| `npm run preview` | Build and run with local Cloudflare simulation | +| `npm run preview:remote` | Build and run with remote Cloudflare resources | +| `npm run cf:dev` | Run wrangler dev without rebuilding | +| `npm run deploy` | Deploy to production | +| `npm run deploy:staging` | Deploy to staging environment | +| `npm run test` | Run tests | +| `npm run lint` | Run ESLint | +| `npm run typecheck` | Run TypeScript type checking | +| `npm run cf:typegen` | Generate TypeScript types for Cloudflare bindings | +| `npm run cf:tail` | Tail production logs | + +## Local Services Simulation + +When using `npm run preview`, the following services are simulated locally: + +### R2 Storage + +- Local R2 bucket simulation for file storage +- Data persisted in `.wrangler/state/r2` +- No AWS S3 API calls or charges + +### KV Storage (when enabled) + +- Local KV namespace simulation +- Data persisted in `.wrangler/state/kv` +- No Cloudflare KV API calls or charges + +### Environment Variables + +- Development environment uses `env.development` from `wrangler.toml` +- Secrets loaded from `.dev.vars` file +- `ENVIRONMENT=development` and `NEXT_PUBLIC_APP_URL=http://localhost:3000` + +## Debugging + +### View Logs + +During local development, all console logs are visible in the terminal. + +### Inspect Local State + +Check the `.wrangler/state` directory to inspect: + +- R2 bucket contents +- KV namespace data +- Cache contents + +### TypeScript Types + +Generate types for Cloudflare bindings: + +```bash +npm run cf:typegen +``` + +This updates `worker-configuration.d.ts` with the latest binding types. + +## Troubleshooting + +### Port Already in Use + +If port 8787 is already in use: + +```bash +# Find the process using the port +lsof -i :8787 + +# Kill the process +kill -9 +``` + +### Build Errors + +If you encounter build errors: + +1. Delete `.next` and `.open-next` directories +2. Run `npm run cf:build` again + +### R2 Bucket Not Found + +Ensure the R2 binding is correctly configured in `wrangler.toml`: + +```toml +[[r2_buckets]] +binding = "GHOSTPASTE_BUCKET" +bucket_name = "ghostpaste-bucket" +``` + +### Hot Reload Not Working + +The Cloudflare Workers preview doesn't support hot reload. You need to: + +1. Make your changes +2. Stop the dev server (Ctrl+C) +3. Run `npm run preview` again + +For faster development of UI components, use `npm run dev` for Next.js hot reload, then test with `npm run preview` when you need Workers features. + +## Performance Tips + +1. **Use local development** (`npm run preview`) for most development to avoid API charges +2. **Persist state** with `--persist-to` flag to maintain data between restarts +3. **Clear state** by deleting `.wrangler/state` when you need a fresh start +4. **Use remote development** (`npm run preview:remote`) only when testing with production-like data + +## Next Steps + +- Check out the [Architecture Guide](./SPEC.md) to understand the system design +- Review [Security Guidelines](./SPEC.md#security-considerations) for encryption implementation +- See [Contributing Guide](../README.md#contributing) for code standards diff --git a/docs/MINIFLARE_DECISION.md b/docs/MINIFLARE_DECISION.md new file mode 100644 index 0000000..159867c --- /dev/null +++ b/docs/MINIFLARE_DECISION.md @@ -0,0 +1,74 @@ +# Miniflare Configuration Decision + +## Summary + +After researching the current state of Miniflare and Wrangler in 2024, we've determined that **separate Miniflare installation is not needed**. Miniflare v3 is already integrated into Wrangler 4.x, which we're using. + +## Key Findings + +1. **Miniflare v3 is integrated into Wrangler**: Since Wrangler v3, Miniflare has been integrated directly into the CLI. Our project uses Wrangler 4.19.1, which includes Miniflare v3. + +2. **Better accuracy with workerd**: Miniflare v3 uses the open-source workerd runtime, providing near-perfect parity with production Cloudflare Workers. + +3. **Performance improvements**: 10x faster startup times and 60x faster script reload times compared to remote development. + +4. **Local simulation benefits**: + - No billing for R2/KV operations during development + - Faster development cycles + - Offline development capability + - State persistence between restarts + +## What We Did + +Instead of installing Miniflare separately, we: + +1. **Enhanced development scripts** in `package.json`: + + - Added `cf:dev` for direct wrangler dev access + - Added state persistence with `--persist-to .wrangler/state` + - Added `preview:remote` for testing with real Cloudflare resources + - Added deployment scripts for staging + +2. **Created comprehensive documentation**: + + - `LOCAL_DEVELOPMENT.md` with detailed setup instructions + - Updated README.md with quick start guide + - Updated CLAUDE.md with new commands + +3. **Configured local development**: + - Local R2 bucket simulation + - Environment-specific configurations in wrangler.toml + - `.dev.vars` for local secrets + +## Development Workflow + +### For UI development (with hot reload): + +```bash +npm run dev +``` + +### For full Cloudflare Workers simulation: + +```bash +npm run preview +``` + +### For testing with production resources: + +```bash +npm run preview:remote +``` + +## Benefits of Current Setup + +- ✅ No additional dependencies needed +- ✅ Miniflare v3 already integrated via Wrangler +- ✅ Accurate local simulation with workerd runtime +- ✅ State persistence for better development experience +- ✅ Clear separation between local and remote development +- ✅ No charges for local R2/KV operations + +## Conclusion + +The current Wrangler setup with integrated Miniflare v3 provides everything needed for local Cloudflare Workers development. No additional Miniflare installation or configuration is required. diff --git a/docs/TODO.md b/docs/TODO.md index ca777b1..538ce7a 100644 --- a/docs/TODO.md +++ b/docs/TODO.md @@ -40,13 +40,13 @@ This document tracks the implementation progress of GhostPaste. Check off tasks ### Type Definitions -- [ ] Create TypeScript interfaces for GistMetadata - [#26](https://github.com/nullcoder/ghostpaste/issues/26) -- [ ] Create TypeScript interfaces for UserMetadata - [#26](https://github.com/nullcoder/ghostpaste/issues/26) -- [ ] Create TypeScript interfaces for EncryptedData - [#26](https://github.com/nullcoder/ghostpaste/issues/26) -- [ ] Create TypeScript interfaces for API responses - [#26](https://github.com/nullcoder/ghostpaste/issues/26) -- [ ] Create TypeScript interfaces for error types - [#26](https://github.com/nullcoder/ghostpaste/issues/26) -- [ ] Create type for binary file format - [#26](https://github.com/nullcoder/ghostpaste/issues/26) -- [ ] Export all types from `types/index.ts` - [#26](https://github.com/nullcoder/ghostpaste/issues/26) +- [x] Create TypeScript interfaces for GistMetadata - [#26](https://github.com/nullcoder/ghostpaste/issues/26) +- [x] Create TypeScript interfaces for UserMetadata - [#26](https://github.com/nullcoder/ghostpaste/issues/26) +- [x] Create TypeScript interfaces for EncryptedData - [#26](https://github.com/nullcoder/ghostpaste/issues/26) +- [x] Create TypeScript interfaces for API responses - [#26](https://github.com/nullcoder/ghostpaste/issues/26) +- [x] Create TypeScript interfaces for error types - [#26](https://github.com/nullcoder/ghostpaste/issues/26) +- [x] Create type for binary file format - [#26](https://github.com/nullcoder/ghostpaste/issues/26) +- [x] Export all types from `types/index.ts` - [#26](https://github.com/nullcoder/ghostpaste/issues/26) ### Configuration @@ -55,7 +55,7 @@ This document tracks the implementation progress of GhostPaste. Check off tasks - [x] Set up feature flags system - [#27](https://github.com/nullcoder/ghostpaste/issues/27) - [x] Configure bindings types for TypeScript (handled by wrangler types) - [x] Create env.d.ts for Cloudflare bindings (handled by worker-configuration.d.ts) -- [ ] Set up local development with miniflare - [#29](https://github.com/nullcoder/ghostpaste/issues/29) +- [x] Set up local development with miniflare - [#29](https://github.com/nullcoder/ghostpaste/issues/29) ### Utilities diff --git a/package.json b/package.json index 224c771..611f7c8 100644 --- a/package.json +++ b/package.json @@ -11,9 +11,13 @@ "format": "prettier --write .", "format:check": "prettier --check .", "cf:build": "npx @opennextjs/cloudflare build", - "preview": "npm run cf:build && wrangler dev", + "cf:dev": "wrangler dev --local --persist-to .wrangler/state", + "preview": "npm run cf:build && npm run cf:dev", + "preview:remote": "npm run cf:build && wrangler dev --remote", "deploy": "npm run cf:build && wrangler deploy", + "deploy:staging": "npm run cf:build && wrangler deploy --env staging", "cf:typegen": "wrangler types --env-interface CloudflareEnv", + "cf:tail": "wrangler tail", "prepare": "husky", "test": "vitest", "test:ui": "vitest --ui",