Kayston’s Forge is built with Next.js 14 App Router and TypeScript. All processing runs client-side, making it a fully static, privacy-first developer utilities suite.
Prerequisites
Node.js 18 or laternpm or yarn package managerA modern code editor (VS Code recommended)
Clone and Install
Clone the repository
git clone < repository-ur l > cd kaystons-forge
Install dependencies
This will install all required dependencies including:
Next.js 14 and React 18
TypeScript with strict mode
Tailwind CSS for styling
Zustand for UI state management
Dexie for IndexedDB storage
Vitest for testing
Start the development server
The application will be available at http://localhost:3000 and will redirect to the default tool (/tools/json-format-validate). Available Scripts The project includes several npm scripts for development and maintenance:
Development
Building
Testing
Linting & Auditing
# Start Next.js dev server with hot reload npm run dev
Project Structure Understanding the codebase structure will help you navigate and contribute effectively:
kaystons-forge/ ├── app/ │ ├── page.tsx # Root redirect to default tool │ ├── tools/[toolId]/page.tsx # Dynamic tool pages │ └── globals.css # Global styles & CSS variables ├── components/ │ ├── layout/ │ │ └── AppShell.tsx # Main layout component │ └── tools/ │ └── ToolWorkbench.tsx # Unified tool UI ├── lib/ │ ├── tools/ │ │ ├── registry.ts # Tool definitions (51 tools) │ │ ├── engine.ts # Tool processing logic │ │ ├── php-tools.ts # PHP serialization │ │ ├── curl-to-code.ts # cURL converter │ │ ├── json-to-code.ts # JSON to TypeScript/Python/Go/Rust │ │ ├── cert-decoder.ts # X.509 certificate parser │ │ ├── list-compare.ts # List operations │ │ └── csv-to-sql.ts # CSV to SQL converter │ ├── store.ts # Zustand state management │ └── db.ts # Dexie IndexedDB wrapper ├── hooks/ │ └── useHistory.ts # Tool history management ├── types/ │ ├── index.ts # TypeScript interfaces │ └── vendor.d.ts # Third-party type declarations ├── tests/ │ └── unit/ │ ├── engine.test.ts # Tool engine tests (57 tests) │ ├── bugfixes.test.ts # Regression tests (28 tests) │ └── fuzz.test.ts # Robustness tests (72 tests) ├── public/ │ ├── manifest.json # PWA manifest │ └── sw.js # Service worker └── next.config.mjs # Next.js configuration
Development Workflow
Make your changes
Edit files in app/, components/, lib/, or other directories as needed.
Test locally
The dev server automatically reloads when you save changes. Test your modifications in the browser.
Run tests
Ensure all 157 tests pass before committing.
Lint your code
Fix any ESLint warnings or errors.
Build for production
Verify the static export builds successfully. Output will be in the out/ directory. Keyboard Shortcuts These shortcuts work in the running application:
Shortcut Action Cmd/Ctrl + KOpen command palette Cmd/Ctrl + 1Toggle sidebar Cmd/Ctrl + EnterExecute active tool action Cmd/Ctrl + Shift + CCopy output Cmd/Ctrl + Shift + SDownload output Cmd/Ctrl + [Previous tool Cmd/Ctrl + ]Next tool EscClear input
Tech Stack Overview Kayston’s Forge uses modern web technologies:
Next.js 14 with App Router for static site generationReact 18 with TypeScript strict modeTailwind CSS for utility-first stylingZustand for lightweight UI state managementDexie for client-side IndexedDB storageHeroicons for consistent iconographyVitest with jsdom for component and unit testing
The bundle size is currently ~513 kB on first load because all tool dependencies load on every page. Future optimization with dynamic imports is planned.
Troubleshooting Port Already in Use If port 3000 is already occupied:
# Use a different port PORT = 3001 npm run dev
TypeScript Errors Ensure your editor is using the workspace TypeScript version:
# In VS Code, open command palette and select: # "TypeScript: Select TypeScript Version" → "Use Workspace Version"
Test Failures If tests fail unexpectedly:
# Clear Vitest cache rm -rf node_modules/.vitest npm run test
Next Steps Now that you have a local environment running:
