Zen Downloads

A Chrome extension that automatically organizes your downloads into folders based on customizable rules. Stop organizing manually. Chaos to order, instantly.

Features

• 📁 Automatic Organization: Automatically organize downloads into folders based on URL patterns, file types, and custom conditions
• 🎯 Flexible Rules Engine: Create custom rules with multiple conditions and actions
• 📝 Template System: Use dynamic path templates with variables like {host}, {ext}, {yyyy-mm-dd}, and more
• 🔄 Conflict Resolution: Handle file name conflicts with options like uniquify, overwrite, or prompt
• 🎨 Modern UI: Built with React and Tailwind CSS for a clean, intuitive interface
• ⚡ Real-time Preview: See how your rules will organize files before applying them
• 💾 Import/Export: Share rule configurations or back them up

Installation

From Source

1. Clone this repository:

   git clone https://github.com/Yuta-31/custom_download_path.git
   cd custom_download_path

2. Install dependencies:

   npm install

3. Build the extension:

   npm run build

4. Load the extension in Chrome:

   • Open Chrome and navigate to chrome://extensions/
   • Enable "Developer mode"
   • Click "Load unpacked"
   • Select the appPackages folder from the project directory

Usage

Creating Rules

1. Click the extension icon in your browser toolbar
2. Click "Settings" to open the options page
3. Add a new rule with:
   • Name: A descriptive name for your rule
   • Enabled: Toggle to enable/disable the rule
   • Domains: URL patterns to match (e.g., *.github.qkg1.top, example.com)
   • Conditions: File conditions (extension, mime type, size, etc.)
   • Path Template: Where to save the file using template variables
   • Conflict Resolution: How to handle existing files with the same name

Template Variables

Use these variables in your path templates:

• {file} - Original filename
• {name} - Filename without extension
• {ext} - File extension
• {host} - Hostname of the download URL
• {domain} - Domain name (without subdomain)
• {path} - URL path
• {yyyy} - Year (4 digits)
• {mm} - Month (2 digits)
• {dd} - Day (2 digits)
• {hh} - Hour (2 digits)
• {MM} - Minute (2 digits)
• {ss} - Second (2 digits)
• {yyyy-mm-dd} - Full date (e.g., 2024-01-15)

Example Rules

Organize images by date and site:

Path: {host}/images/{yyyy-mm-dd}/{file}
Conditions: Extension in [png, jpg, jpeg, gif, webp]

Separate documents by type:

Path: Documents/{ext}/{file}
Conditions: Extension in [pdf, doc, docx, txt]

Group downloads from specific sites:

Path: Projects/GitHub/{name}.{ext}
Domains: *.github.qkg1.top

Configuration

Rule Structure

Rules are evaluated in order from top to bottom. The first matching rule is applied.

{
  id: "unique-id",
  name: "Rule Name",
  enabled: true,
  domains: ["*.example.com"],
  conditions: [
    { key: "ext", op: "in", value: ["pdf", "doc"] }
  ],
  actions: {
    pathTemplate: "{host}/{yyyy-mm-dd}/{file}",
    conflict: "uniquify"
  }
}

Condition Operators

• in - Value is in the list
• notIn - Value is not in the list
• eq - Value equals
• ne - Value does not equal
• contains - Value contains substring
• notContains - Value does not contain substring
• startsWith - Value starts with
• endsWith - Value ends with
• matches - Value matches regex pattern

Conflict Resolution Options

• uniquify - Add a number suffix to create a unique filename (e.g., file(1).pdf)
• overwrite - Replace the existing file
• prompt - Ask the user what to do

Development

Project Structure

src/
├── background/      # Background service worker
├── content/         # Content scripts
├── popup/           # Extension popup UI
├── options/         # Settings page
├── lib/             # Shared utilities
│   └── rules/       # Rules engine and template system
└── schemas/         # Zod schemas for validation

Scripts

• npm run dev - Start development server
• npm run build - Build for production
• npm run test - Run tests
• npm run test:watch - Run tests in watch mode
• npm run lint - Lint code
• npm run package - Package extension for distribution
• npm run license:check - Check licenses of all dependencies
• npm run license:generate - Generate third-party license notices

Tech Stack

• Framework: React 19 + TypeScript
• Build Tool: Vite
• UI Components: shadcn/ui (Radix UI primitives + class-variance-authority)
• Styling: Tailwind CSS
• State Management: React Context
• Validation: Zod
• Testing: Vitest

UI Components

The UI follows the shadcn/ui approach:

• Location: Components live under src/components/ui
• Primitives: Built on Radix UI (e.g., @radix-ui/react-alert-dialog)
• Variants: Styled via class-variance-authority (cva) with consistent variant and size props
• Composition: Uses Slot and a cn utility for class merging

When adding components, mirror existing patterns (e.g., Button) and export both the component and its variants for reuse.

Changelog

Version 1.2.0 (2026-01-27)

New Features:

• Added pause/resume functionality via popup UI
• Display active rules for the current page in popup
• Added conflict resolution settings with enhanced selection UI
• Enhanced rule configuration with conflict resolution options

UI Enhancements:

• New popup interface with breathing glow effects and elegant toggle button
• Smooth state transitions between active and paused modes

User Experience:

• Quick access to pause download organization without opening settings
• Visual feedback showing which rules apply to the current site

Version 1.1.0 (2026-01-26)

Improvements:

• Enhanced preview display with Downloads/ prefix to clearly show the final save location
• Added informative notes explaining that actual downloads may use different filenames provided by the server
• Empty test URL now displays a default preview (Downloads/{file})
• Rules without matches now show the default save path in preview

Bug Fixes:

• Fixed an issue where rules might not apply on the first download after opening the browser (improved rule cache initialization)

Developer Experience:

• Added comprehensive logging throughout the options UI (RulesContext, SettingsCard, RuleList, file operations)
• Improved debugging capabilities with structured logger output

Version 1.0.0 (2024-01-15)

Initial Release:

• Automatic download organization based on customizable rules
• Flexible rules engine with multiple conditions and operators
• Dynamic path templates with date, URL, and file variables
• Real-time preview of rule outcomes
• Import/export functionality for rule configurations
• Modern React-based settings UI with dark mode support

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

License

This project is licensed under the MIT License. See the LICENSE file for details.

Third-Party Licenses

This project uses various open-source packages. Their licenses can be found in the THIRD-PARTY-NOTICES.md file.

To view a summary of all dependency licenses:

npm run license:check

To regenerate the third-party notices:

npm run license:generate

Acknowledgments

• Built with Vite
• UI built with shadcn/ui on top of Radix UI
• Icons from Lucide