Ionicons Deployment and Usage Guide

Prerequisites

Node.js (version 16 or higher)
npm (version 8 or higher)
TypeScript (for development)
SVGO (for SVG optimization)
Playwright (for testing)
Git (for cloning the repository)

Installation

Clone the repository:

git clone https://github.com/ionic-team/ionicons.git
cd ionicons

Install dependencies:
```
npm install
```

Install development dependencies:

npm install -D @stencil/core playwright @playwright/test

Configuration

Ionicons doesn't require specific environment variables or API keys for basic usage. However, for development and testing:

Ensure you have the latest version of Node.js and npm installed
For testing, Playwright will automatically download the necessary browser binaries

Build & Run

Development Build

Build the project:
```
npm run build
```
This will:
- Create necessary directories
- Optimize SVG files
- Generate JSON data files
- Create icon packages
- Generate cheatsheet and web types
- Copy files for testing
Run tests:
```
npx playwright test
```

Production Build

For production, the build process is the same as development. The build script handles both scenarios:

npm run build

This will generate optimized files in the dist directory ready for production use.

Deployment

Ionicons is a library of icons, so deployment typically involves:

NPM Package: The primary distribution method is through npm. To publish:
```
npm login
npm publish
```
CDN: For CDN deployment, you can use services like:
- jsDelivr
- unpkg
- Cloudflare CDN
Self-hosted: If you need to host the icons yourself, simply copy the contents of the dist directory to your web server.

Usage

Web Component

Ionicons provides a web component that can be used in any framework or vanilla JavaScript:

<script type="module" src="https://unpkg.com/ionicons@7.0.0/dist/ionicons/ionicons.esm.js"></script>
<script nomodule src="https://unpkg.com/ionicons@7.0.0/dist/ionicons/ionicons.js"></script>

<ion-icon name="heart"></ion-icon>

Manual Import

You can also manually import icons:

import { addIcons } from 'ionicons';
import { heart } from 'ionicons/icons';

addIcons({
  'heart': heart
});

Troubleshooting

Common Issues

SVG Optimization Errors
- Issue: Build fails during SVG optimization
- Solution: Ensure SVGO is installed and up to date. Check SVG syntax for any invalid elements.
TypeScript Compilation Errors
- Issue: TypeScript compilation fails
- Solution: Verify TypeScript version compatibility. Run npm install to ensure all dependencies are installed.
Testing Failures
- Issue: Playwright tests fail
- Solution: Ensure browser binaries are installed (npx playwright install). Check for any console errors in the test environment.
Icon Not Displaying
- Issue: Icons don't render in the browser
- Solution: Check that the web component script is loaded correctly. Verify the icon name is correct and the icon exists in the library.
Build Directory Issues
- Issue: Build process fails to create directories
- Solution: Check file permissions. Ensure no other processes are using the build directories.

Debug Commands

To clean the build directory:
```
npm run clean
```
To rebuild from scratch:
```
npm run clean && npm run build
```

To run specific tests:

npx playwright test --project="Mobile Chrome"

Performance Tips

Use the web component for best performance and tree-shaking
Only import the icons you need for smaller bundle sizes
Consider using a CDN for faster global delivery
Cache icons appropriately in your application

This guide provides a comprehensive overview of deploying and using Ionicons in your projects. For more detailed information, refer to the official documentation and source code comments.

How to Deploy & Use ionic-team/ionicons