Skip to content

docs(icons-gallery): align README with actual stack (Vite + Vitest) #561

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
isaquebock wants to merge 2 commits into
base: main
Choose a base branch
from
Open

docs(icons-gallery): align README with actual stack (Vite + Vitest) #561

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
abb5c9e
docs(icons-gallery): align README with actual stack (Vite + Vitest)
isaquebock May 20, 2026
37b5323
Merge branch 'main' into docs/icons-gallery-readme
isaquebock May 20, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
158 changes: 80 additions & 78 deletions apps/icons-gallery/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,7 @@

[![MIT License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
[![Vue 3](https://img.shields.io/badge/Vue-3.x-4FC08D?logo=vue.js)](https://vuejs.org/)
[![Vite](https://img.shields.io/badge/Vite-6.x-646CFF?logo=vite)](https://vitejs.dev/)

---

Expand All @@ -28,19 +29,19 @@ The application is deployed on **Azion's Edge Platform** for low-latency global

| Layer | Technology | Purpose |
|-------|------------|---------|
| **Framework** | Vue 3 (Composition API) | Reactive UI components |
| **Framework** | Vue 3 (Composition API, `<script setup>`) | Reactive UI components |
| **Build** | Vite | Dev server, bundling, preview |
| **Styling** | Tailwind CSS | Utility-first CSS framework |
| **Icons** | @aziontech/icons | Icon font package (workspace dependency) |
| **Color Picker** | vue3-colorpicker | Color selection widget |
| **Build** | Vue CLI | Development server and bundling |
| **Testing** | Jest + Vue Test Utils | Unit testing |
| **Icons** | `@aziontech/icons` | Icon font + catalog (workspace dependency) |
| **Color Picker** | `vue3-colorpicker` | Color selection widget |
| **Testing** | Vitest + jsdom | Unit testing |
| **Deployment** | Azion Edge Platform | Global edge deployment |

### Application Flow

```mermaid
flowchart TD
A[User visits gallery] --> B[Load icons.json]
A[User visits gallery] --> B[Import catalog from @aziontech/icons]
B --> C[Render icon grid]
C --> D{User interaction}
D -->|Search| E[Filter icons by name/keywords]
Expand Down Expand Up @@ -69,9 +70,9 @@ flowchart TB
H[Size Slider] --> I[Update size state]
J[Theme Toggle] --> K[Dark/Light mode]
end
L[icons.json] --> M[Icon metadata]
L["@aziontech/icons/catalog"] --> M[Icon metadata]
M --> App.vue
N[@aziontech/icons] --> O[Icon fonts CSS]
N["@aziontech/icons"] --> O[Icon fonts CSS]
O --> App.vue
```

Expand All @@ -82,32 +83,31 @@ flowchart TB
```
apps/icons-gallery/
├── public/
│ ├── favicon.ico # Site favicon
│ └── index.html # HTML template
│ └── favicon.ico # Site favicon
├── src/
│ ├── components/
│ │ ├── IconCard.vue # Individual icon display card
│ │ └── SearchBar.vue # Search input with filtering
│ ├── App.vue # Main application component
│ ├── icons.json # Icon metadata (name, class, keywords)
│ ├── main.css # Global styles and Tailwind imports
│ ├── main.js # Application entry point
│ └── theme.js # Dark/light theme management
├── tests/
│ └── unit/
│ ├── __mocks__/
│ ├── iconDownload.spec.js # Download functionality tests
│ └── jest.setup.js # Jest configuration
├── azion/ # Azion deployment config
│ ├── args.json # Build arguments
│ └── jest.setup.js # Vitest setup file (legacy filename)
├── azion/
│ ├── args.json # Build arguments for Azion CLI
│ └── azion.json # Edge application manifest
├── azion.config.cjs # Azion project configuration
├── babel.config.js # Babel configuration
├── jest.config.js # Jest test configuration
├── index.html # Vite HTML entry point
├── jsconfig.json # JavaScript/IDE configuration
├── package.json # Dependencies and scripts
├── postcss.config.js # PostCSS configuration
├── tailwind.config.js # Tailwind CSS configuration
└── vue.config.js # Vue CLI configuration
├── vite.config.js # Vite dev/build configuration
└── vitest.config.js # Vitest test configuration
```

### Key Files Explained
Expand All @@ -117,17 +117,20 @@ apps/icons-gallery/
| [`src/App.vue`](src/App.vue) | Main component containing icon grid, controls, and state management |
| [`src/components/IconCard.vue`](src/components/IconCard.vue) | Renders individual icon with hover actions (copy code, copy image, download) |
| [`src/components/SearchBar.vue`](src/components/SearchBar.vue) | Search input with real-time filtering |
| [`src/icons.json`](src/icons.json) | Metadata for all icons including name, class, and searchable keywords |
| [`src/theme.js`](src/theme.js) | Theme initialization and toggle functionality |
| [`vite.config.js`](vite.config.js) | Vite dev server (port 3333) and build config |
| [`vitest.config.js`](vitest.config.js) | Vitest config (jsdom environment, setup file) |
| [`azion.config.cjs`](azion.config.cjs) | Edge deployment configuration with caching rules |

Icon metadata is **not** stored locally — it is imported at runtime from `@aziontech/icons/catalog` (resolved to `packages/icons/dist/catalog.json`).

---

## Getting Started

### Prerequisites

- Node.js 18+
- Node.js 18+
- pnpm (workspace package manager)

### Installation
Expand All @@ -137,77 +140,89 @@ This app is part of a pnpm monorepo. From the workspace root:
```bash
# Install all workspace dependencies
pnpm install

# Or install only for this app
cd apps/icons-gallery
pnpm install
```

### Development Server

```bash
# Start development server on port 3333
# From the app directory
pnpm serve

# Or from workspace root
pnpm --filter icons-gallery serve
```

The app will be available at `http://localhost:3333` with hot module replacement enabled.
The app will be available at `http://localhost:3333` with HMR enabled (configured in `vite.config.js`).

### Build for Production

```bash
# Build for Vue CLI output
# Standard Vite build → ./dist
pnpm build

# Build for Azion Edge deployment
# Build optimized for Azion Edge Platform
pnpm build:azion
```

The production build outputs to `dist/` directory.

---

## Available Scripts

| Script | Description |
|--------|-------------|
| `pnpm serve` | Start development server with HMR on port 3333 |
| `pnpm build` | Build production bundle via Vue CLI |
| `pnpm serve` | Start Vite dev server with HMR on port 3333 |
| `pnpm build` | Build production bundle via Vite |
| `pnpm build:azion` | Build optimized for Azion Edge Platform |
| `pnpm test:unit` | Run Jest unit tests |
| `pnpm lint` | Run ESLint on source files |
| `pnpm format` | Format code with Prettier |
| `pnpm preview` | Preview production build with Vite |
| `pnpm publish` | Deploy to Azion Edge Platform (local mode) |
| `pnpm test:unit` | Run Vitest unit tests once |
| `pnpm test:unit:watch` | Run Vitest in watch mode |
| `pnpm lint` | Run ESLint with autofix |
| `pnpm format` | Format `src/` with Prettier |
| `pnpm publish` | Deploy to Azion Edge Platform (`azion deploy --local --debug`) |

---

## Configuration

### Vue CLI (`vue.config.js`)
### Vite (`vite.config.js`)

```javascript
module.exports = {
publicPath: '/',
devServer: {
port: 3333, // Development server port
historyApiFallback: true, // SPA routing support
hot: true, // Hot module replacement
open: true // Auto-open browser
import vue from '@vitejs/plugin-vue'
import { fileURLToPath, URL } from 'node:url'
import { defineConfig } from 'vite'

export default defineConfig({
plugins: [vue()],
resolve: {
alias: { '@': fileURLToPath(new URL('./src', import.meta.url)) }
},
server: { port: 3333, open: true }
})
```

### Vitest (`vitest.config.js`)

```javascript
import { defineConfig } from 'vitest/config'
import vue from '@vitejs/plugin-vue'

export default defineConfig({
plugins: [vue()],
test: {
environment: 'jsdom',
setupFiles: ['./tests/unit/jest.setup.js'],
include: ['tests/unit/**/*.{test,spec}.{js,mjs,cjs,ts,mts,cts,jsx,tsx}'],
globals: true
}
}
})
```

### Tailwind CSS (`tailwind.config.js`)

Extends the root workspace Tailwind configuration:

```javascript
module.exports = {
content: ['./src/**/*.{vue,js,ts}'],
// Uses workspace-level theme extensions
content: ['./index.html', './src/**/*.{vue,js,ts}']
// Theme extensions defined inline.
}
```

Expand All @@ -224,9 +239,9 @@ Configures edge deployment with:

## Icon Showcase

The gallery displays icons from two font families:
The gallery displays icons from two font families. Counts below match the current `@aziontech/icons/catalog` snapshot:

### Azionicons (`ai`) — 87 Icons
### Azionicons (`ai`) — 88 icons

Azion-specific product and platform icons organized by category:

Expand Down Expand Up @@ -274,7 +289,7 @@ Azion-specific product and platform icons organized by category:
| Ask Azion | `ai ai-ask-azion` | AI assistant |
| Marketplace | `ai ai-marketplace` | Marketplace services |

### PrimeIcons (`pi`) — 315+ Icons
### PrimeIcons (`pi`) — 314 icons

General-purpose UI icons from the PrimeIcons library. Some commonly used icons:

Expand Down Expand Up @@ -318,33 +333,21 @@ General-purpose UI icons from the PrimeIcons library. Some commonly used icons:

## Adding New Icons

When new icons are added to `@aziontech/icons`, update the gallery:
The gallery has no local icon list — it consumes the catalog generated by `@aziontech/icons`. To make new icons show up:

1. **Rebuild the icons package**:
1. Add the icon to `packages/icons` (SVG sources + catalog entry as the package's build expects).
2. Rebuild the icons package:
```bash
cd packages/icons
pnpm build
```

2. **Update `src/icons.json`** with the new icon entry:
```json
{
"icon": "ai ai-new-icon",
"keywords": "new, icon, keywords",
"name": "ai-new-icon"
}
pnpm --filter @aziontech/icons build
```

3. **Verify** the icon displays correctly in the gallery.
3. Restart the gallery dev server (`pnpm serve`) — the new icon appears automatically once `packages/icons/dist/catalog.json` is regenerated.

---

## Deployment

### Azion Edge Platform

The gallery is designed for deployment on Azion's Edge Platform:

```bash
# Build for edge deployment
pnpm build:azion
Expand All @@ -353,6 +356,8 @@ pnpm build:azion
pnpm publish
```

> The `publish` script in this app does **not** publish to npm — it calls `azion deploy --local --debug`. The name is preserved for legacy automation reasons.

#### Deployment Architecture

```mermaid
Expand All @@ -376,24 +381,21 @@ The deployment configuration includes:

## Testing

### Unit Tests

```bash
# Run all unit tests
# Run all unit tests once
pnpm test:unit

# Run with coverage
pnpm test:unit -- --coverage
# Watch mode
pnpm test:unit:watch
```

Tests are located in `tests/unit/` and use Jest with Vue Test Utils.
Tests live in `tests/unit/` and run on **Vitest** with the **jsdom** environment. The setup file is `tests/unit/jest.setup.js` (filename kept for git-history continuity after the Jest → Vitest migration).

### Test Coverage
### Current Coverage

| Module | Tests |
|--------|-------|
| Icon Download | PNG/SVG download functionality |
| Components | Vue component rendering |
| Icon Download | PNG/SVG download helpers (`iconDownload.spec.js`) |

---

Expand Down Expand Up @@ -426,7 +428,7 @@ Tests are located in `tests/unit/` and use Jest with Vue Test Utils.

| Package | Description |
|---------|-------------|
| [@aziontech/icons](../../packages/icons/README.md) | Icon font library (azionicons + primeicons) |
| [`@aziontech/icons`](../../packages/icons/README.md) | Icon font library (azionicons + primeicons) |

---

Expand Down
Loading