Contributing to Qwik Icons

This guide explains how to contribute to the Qwik Icons package, including its structure, icon generation system, and testing approach.

Project Structure

The icons package follows a modular structure:

libs/icons/
├── src/
│   ├── generate/          # Icon generation scripts
│   │   ├── packs/        # Icon pack configurations
│   │   ├── download-icons.ts
│   │   └── generate-icons.ts
│   ├── icons/            # Generated icon components
│   ├── tests/            # Test files

Icon Generation System

The icon generation process consists of two main steps:

Downloading Icons: The download-icons.ts script fetches icon packs from their respective sources
Generating Components: The generate-icons.ts script converts SVG files into Qwik components

Icon Adapter System

The package uses an adapter system to handle different icon packs. Each icon pack has its own configuration in the generate/packs/ directory that defines:

Source URLs
File naming conventions
SVG optimization settings
Component generation rules

Dependencies

The icon generation process relies on several key dependencies:

SVGO: For optimizing SVG files
Node-stream-zip: For handling zip files during icon downloads
Vite: For building and development
TypeScript: For type safety and development

Development Workflow

Download Icons:
```
pnpm run download-icons
```
Generate Components:
```
pnpm run generate-icons
```
Build Package:
```
pnpm run build
```

Testing

The package includes unit tests for the icon generation process. Tests are located in src/tests/ and can be run using:

pnpm test

The main test file icon-generation.unit.ts verifies:

Icon component generation
SVG optimization
File structure correctness

Adding New Icon Packs

To add a new icon pack:

Create a new configuration file in generate/packs/
Define the pack's download and generation rules
Add the pack to the main configuration in generate/configs.ts
Run the download and generation scripts
Add tests for the new pack

Best Practices

SVG Optimization: Always optimize SVGs using SVGO before generating components
Type Safety: Maintain TypeScript types for all generated components
Testing: Add tests for new icon packs and generation features
Documentation: Update documentation when adding new features or packs

Troubleshooting

Common issues and solutions:

Download Failures: Check network connectivity and source URLs
Generation Errors: Verify SVG file integrity and configuration
Build Issues: Ensure all dependencies are up to date

Getting Help

If you encounter issues or have questions:

Check the existing documentation
Review the test files for examples
Open an issue in the repository