Relevant source files

The following files were used as context for generating this wiki page: - [README.md](https://github.com/YueMiyuki/devutils/blob/main/README.md) - [package.json](https://github.com/YueMiyuki/devutils/blob/main/package.json) - [src-tauri/tauri.conf.json](https://github.com/YueMiyuki/devutils/blob/main/src-tauri/tauri.conf.json) - [components/tool-content.tsx](https://github.com/YueMiyuki/devutils/blob/main/components/tool-content.tsx) - [components/tool-sidebar.tsx](https://github.com/YueMiyuki/devutils/blob/main/components/tool-sidebar.tsx) - [messages/en.json](https://github.com/YueMiyuki/devutils/blob/main/messages/en.json) - [components/tools/blame-intern.tsx](https://github.com/YueMiyuki/devutils/blob/main/components/tools/blame-intern.tsx)

# Contributor Guide This guide provides a comprehensive overview of the `devutils` project for prospective contributors. It covers the project's architecture, development setup, and the process for adding new tools. The application is a desktop tool suite built with Tauri and Next.js, designed to be a multi-tab environment for various developer utilities. The core of the application is its modular design, where each tool is a self-contained React component. This guide will walk you through the steps required to create and integrate a new tool into the existing framework. ## Getting Started This section covers the initial setup required to get the development environment running locally. ### Prerequisites The project uses `pnpm` as its package manager. Ensure you have Node.js and `pnpm` installed. ### Installation and Build To get started, clone the repository and run the installation and build commands. ```bash pnpm install pnpm tauri build ``` The `pnpm install` command installs all the necessary dependencies defined in `package.json`. The `pnpm tauri build` command compiles the Next.js frontend and then builds the final Tauri desktop application. Sources: [README.md:5-9](), [package.json:5-7]() ### Development Scripts The `package.json` file contains several scripts to aid in development. | Script | Description | | --------------------- | ------------------------------------------------------------------------------------------------------- | | `dev` | Starts the Next.js development server. | | `build` | Builds the Next.js application for production. | | `lint` | Runs ESLint to find and fix problems in the codebase. | | `tauri` | Provides access to the Tauri CLI for commands like `dev` and `build`. | | `check-types` | Concurrently transpiles the code with SWC and runs `tsgo` to check for TypeScript errors. | | `prepare` | Installs Husky for git hooks. | | `prettier` | Formats all files in the project using Prettier. | | `pre-commit` | A git hook that runs `check-types`, `lint`, and `prettier` before a commit is made to ensure code quality. | | `knip` | Detects and removes unused files, dependencies, and exports. | Sources: [package.json:4-19]() The following diagram illustrates the initial setup and development workflow. ```mermaid flowchart TD A[Clone Repository] --> B[Run `pnpm install`]; B --> C{Choose Workflow}; C --> D[Run `pnpm dev` for web dev]; C --> E[Run `pnpm tauri dev` for desktop dev]; C --> F[Run `pnpm tauri build` for production app]; G[Make Code Changes] --> H[Run `git commit`]; H --> I[pre-commit hook runs]; I --> J["`check-types`, `lint`, `prettier`"]; J --> K{Checks Pass?}; K -- Yes --> L[Commit Successful]; K -- No --> G; ``` Sources: [README.md:5-9](), [package.json:4-19]() ## Project Structure The project is organized into several key directories. Understanding this structure is crucial for adding new features. ```mermaid graph TD A[devutils] A --> B[components] A --> C[messages] A --> D[src-tauri] A --> E[package.json] A --> F[README.md] B --> B1[tools] B --> B2[tool-content.tsx] B --> B3[tool-sidebar.tsx] B1 --> B1a["[tool-name].tsx"] C --> C1[en.json] C --> C2[zh.json] D --> D1[tauri.conf.json] subgraph "Key Files & Directories" B2 B3 B1a C1 D1 E end style B1a fill:#f9f,stroke:#333,stroke-width:2px style B2 fill:#ccf,stroke:#333,stroke-width:2px style B3 fill:#ccf,stroke:#333,stroke-width:2px style C1 fill:#cfc,stroke:#333,stroke-width:2px style D1 fill:#fcf,stroke:#333,stroke-width:2px style E fill:#fcf,stroke:#333,stroke-width:2px ``` - **`components/tools/`**: Contains the individual React components for each tool (e.g., `jwt-decoder.tsx`, `base64-tool.tsx`). Each file in this directory represents a distinct utility in the application. - **`components/tool-content.tsx`**: This file acts as a router for the main content area. It contains a mapping from a `toolId` to its corresponding React component. - **`components/tool-sidebar.tsx`**: This component renders the list of available tools. It defines which tools are available and handles the logic for opening a tool in a new tab. - **`messages/`**: This directory holds the internationalization (i18n) files. `en.json` and `zh.json` contain the names, descriptions, and other UI strings for all tools. - **`src-tauri/tauri.conf.json`**: The main configuration file for the Tauri application. It defines the application's identifier, version, window properties, and security capabilities. - **`package.json`**: Defines project metadata, dependencies, and development scripts. Sources: [components/tool-content.tsx](), [components/tool-sidebar.tsx](), [messages/en.json](), [src-tauri/tauri.conf.json](), [package.json]() ## How to Add a New Tool Adding a new tool involves creating the tool's component and registering it within the application's framework. The following steps outline the process. This diagram shows the workflow for adding a new tool. ```mermaid flowchart TD subgraph "Step 1: Create Component" A[Create `my-new-tool.tsx` in `components/tools/`] end subgraph "Step 2: Add i18n Strings" B[Add tool name & description to `messages/en.json`] end subgraph "Step 3: Register in Sidebar" C[Add tool ID to `utilityToolIds` in `tool-sidebar.tsx`] D[Add icon to `toolIcons` map in `tool-sidebar.tsx`] C --> D end subgraph "Step 4: Map Component" E[Import `MyNewTool` in `tool-content.tsx`] F[Add entry to `toolComponents` map in `tool-content.tsx`] E --> F end A --> B --> C --> E ``` ### 1. Create the Tool Component Create a new file for your tool in the `components/tools/` directory (e.g., `my-new-tool.tsx`). The component must be a React functional component that accepts `tabId` as a prop. **Example Structure:** ```typescript // components/tools/my-new-tool.tsx "use client"; import { Card, CardContent, CardHeader, CardTitle } from "@/components/ui/card"; interface MyNewToolProps { tabId: string; } // The tabId prop is passed but can be ignored if not needed. // eslint-disable-next-line @typescript-eslint/no-unused-vars export function MyNewTool({ tabId: _tabId }: MyNewToolProps) { return (

My New Tool

This is the content of the new tool.

); } ``` Sources: [components/tools/blame-intern.tsx:87-89]() ### 2. Add Internationalization Strings Add the necessary strings for your tool's name, short name, and description to the i18n files. **File:** `messages/en.json` ```json { "tools": { "myNewTool": { "name": "My New Awesome Tool", "shortName": "New Tool", "description": "A short description of what this tool does." }, // ... other tools } } ``` You should also add corresponding translations to other language files like `messages/zh.json`. Sources: [messages/en.json:10-80]() ### 3. Register the Tool in the Sidebar To make the tool appear in the sidebar, you need to modify `components/tool-sidebar.tsx`. 1. **Add the Tool ID:** Add your new tool's ID (e.g., `my-new-tool`) to either the `utilityToolIds` or `funToolIds` array. 2. **Add a Tool Key:** Add an entry to the `toolKeyMap` to link the tool ID to its i18n key. 3. **Add an Icon:** Add an icon for your tool in the `toolIcons` object. Import the icon from `lucide-react`. **File:** `components/tool-sidebar.tsx` ```typescript // ... imports import { /*...,*/ Wrench as NewToolIcon } from "lucide-react"; const utilityToolIds = [ // ... "my-new-tool", ]; const toolKeyMap: Record = { // ... "my-new-tool": "myNewTool", }; const toolIcons = { // ... "my-new-tool": NewToolIcon, }; ``` Sources: [components/tool-sidebar.tsx:30-36](), [components/tool-sidebar.tsx:40-51](), [components/tool-sidebar.tsx:53-64]() ### 4. Map the Tool Component Finally, register the component in `components/tool-content.tsx` so the application knows what to render when the tool is selected. 1. **Import your component.** 2. **Add it to the `toolComponents` map.** **File:** `components/tool-content.tsx` ```typescript // ... imports import { MyNewTool } from "@/components/tools/my-new-tool"; const toolComponents: Record> = { // ... other tools "my-new-tool": MyNewTool, }; export function ToolContent() { // ... existing logic } ``` Sources: [components/tool-content.tsx:20-31]() After completing these steps, your new tool will be fully integrated into the DevUtils application. ## Technology Stack The project utilizes a modern technology stack for both the frontend and the desktop application layer. | Category | Technology - | | --------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Desktop Framework** | [Tauri](https://tauri.app/) - | | **Frontend Framework** | [Next.js](https://nextjs.org) - | | **UI Library** | React, Radix UI, Tailwind CSS, lucide-react - | | **State Management** | Zustand - | | **Internationalization** | i18next, react-i18next - | | **Code Quality** | TypeScript, ESLint, Prettier, Husky, Knip - | Sources: [package.json:22-89](), [src-tauri/tauri.conf.json]()