nullcoder · nullcoder · Jun 6, 2025 · Jun 6, 2025 · Jun 6, 2025
diff --git 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
@@ -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
@@ -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 <PID>
+```
+
+### 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
@@ -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
@@ -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
@@ -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",