agerix/iconify
2
0
Fork 0
mirror of https://github.com/iconify/iconify.git synced 2024-12-12 13:47:49 +00:00
Code Issues Releases Activity
8f962a090b
iconify/README.md
Vjacheslav Trushkin 859a77b4bf Fix dev container environment
2022-07-08 13:24:51 +03:00

223 lines
11 KiB
Markdown
Raw Blame History

Iconify is the most versatile icon framework.
- Unified icon framework that can be used with any icon library.
- Out of the box includes 100+ icon sets with more than 100,000 icons.
- Embed icons in HTML with SVG framework or components for front-end frameworks.
- Embed icons in designs with plug-ins for Figma, Sketch and Adobe XD.
- Add icon search to your applications with Iconify Icon Finder.
For more information visit [https://iconify.design/](https://iconify.design/).
## Iconify parts
There are several parts of project, some are in this repository, some are in other repositories.
What is included in this repository?
- Directory `packages` contains main reusable packages: types, utilities, reusable functions used by various components.
- Directory `iconify-icon` contains `iconify-icon` web component that renders icons. It also contains wrappers for various frameworks that cannot handle web components.
- Directory `components` contains older version of icon components that are native to various frameworks, which do not use web component.
Other repositories you might want to look at:
- Data for all icons is available in [`iconify/icon-sets`](https://github.com/iconify/icon-sets) repository.
- Tools for parsing icons and generating icon sets are available in [`iconify/tools`](https://github.com/iconify/tools) repository.
## Iconify icon components
Main packages in this repository are various icon components.
Why are those icon components needed? Iconify icon components are not just yet another set of icon components. Unlike other icon components, Iconify icon components do not include icon data. Instead, icon data is loaded on demand from Iconify API.
Iconify API provides data for over 100,000 open source icons! API is hosted on publicly available servers, spread out geographically to make sure visitors from all over the world have the fastest possible connection with redundancies in place to make sure it is always online.
#### Why is API needed?
When you use an icon font, each visitor loads an entire font, even if your page only uses a few icons. This is a major downside of using icon fonts. That limits developers to one or two fonts or icon sets.
If you are using typical icon set that is not a font, you still need to bundle all icons used in your application, even ones that visitor does not need.
Unlike icon fonts and components for various icon sets, Iconify icon components dynamically load icon data from Iconify API whenever it is needed.
This makes it possible to have an unlimited choice of icons!
## Packages in this repository
There are several types of packages, split in their own directories.
### Main packages
Directory `packages` contains main packages that are reusable by all other packages in this repository as well as third party components.
Main packages:
- [Iconify types](./packages/types/) - TypeScript types.
- [Iconify utils](./packages/utils/) - common files used by various Iconify projects (including tools, API, etc...).
- [Iconify core](./packages/core/) - common files used by various icon components.
- [API redundancy](./packages/api-redundancy/) - library for managing redundancies for loading data from API: handling timeouts, rotating hosts.
### Web component
Directory `iconify-icon` contains `iconify-icon` web component and wrappers for various frameworks.
| Package | Usage |
| ---------------------------------------- | ---------- |
| [Web component](./iconify-icon/icon/) | Everywhere |
| [React wrapper](./iconify-icon/react/) | React |
| [SolidJS wrapper](./iconify-icon/solid/) | SolidJS |
Frameworks that are confirmed to work with web components without custom wrappers:
- Svelte.
- Lit.
- Ember.
- Vue 2 and Vue 3, but requires custom config when used in Nuxt (see below).
- React, but with small differences, such as using `class` instead of `className`. Wrapper fixes it and provides types.
#### Demo
Directory `iconify-icon-demo` contains demo packages that show usage of `iconify-icon` web component.
- [Ember demo](./iconify-icon-demo/ember-icon-demo/) - demo using web component with Ember. Run `npm run build` to build demo and `npm run start` to start it.
- [React demo](./iconify-icon-demo/react-demo/) - demo using web component with React. Run `npm run dev` to start demo.
- [Next.js demo](./iconify-icon-demo/nextjs-demo/) - demo for web component with Next.js. Run `npm run dev` to start demo.
- [Svelte demo with Vite](./iconify-icon-demo/svelte-demo/) - demo for web component with Svelte using Vite. Run `npm run dev` to start demo.
- [SvelteKit demo](./iconify-icon-demo/sveltekit-demo/) - demo for web component with SvelteKit. Run `npm run dev` to start the demo.
- [Vue 3 demo](./iconify-icon-demo/vue-demo/) - demo for web component with Vue 3. Run `npm run dev` to start demo.
- [Nuxt 3 demo](./iconify-icon-demo/nuxt3-demo/) - demo for web component with Nuxt 3. Run `npm run dev` to start demo. Requires custom config, see below.
- [Vue 2 demo](./iconify-icon-demo/vue2-demo/) - demo for web component with Vue 2. Run `npm run build` to build demo and `npm run serve` to start it.
- [SolidJS demo](./iconify-icon-demo/solid-demo/) - demo using web component with SolidJS. Run `npm run dev` to start demo.
- [Lit demo](./iconify-icon-demo/lit-demo/) - demo for web component with Lit. Run `npm run start` to start demo.
#### Nuxt 3 usage
When using web component with Nuxt 3, you need to tell Nuxt that `iconify-icon` is a custom element. Otherwise it will show few errors.
Example `nuxt.config.ts`:
```ts
import { defineNuxtConfig } from 'nuxt3';
export default defineNuxtConfig({
vue: {
compilerOptions: {
isCustomElement: (tag) => tag === 'iconify-icon',
},
},
});
```
This configuration change is not needed when using Vue with `@vitejs/plugin-vue`.
### Iconify icon components
Directory `components` contains Iconify icon components and SVG framework.
| Package | Usage |
| ---------------------------------------- | ------ |
| [SVG Framework](./components/iconify/) | HTML |
| [React component](./components/react/) | React |
| [Vue 3 component](./components/vue/) | Vue 3 |
| [Vue 2 component](./components/vue2/) | Vue 2 |
| [Svelte component](./components/svelte/) | Svelte |
| [Ember component](./components/ember/) | Ember |
#### Deprecation notice
Components in directory `components` are slowly phased out in favor of `iconify-icon` web component. Components are still maintained and supported, but it is better to switch to web component.
Functionality is identical, but web component has some advantages:
- No framework specific shenanigans. Events and attributes are supported for all frameworks.
- Works better with SSR (icon is rendered only in browser, but because icon is contained in shadow DOM, it does not cause hydration problems).
- Better interoperability. All parts of applicaiton reuse same web component, even if those parts are written in different frameworks.
Deprecation status:
- SVG Framework: can be replaced with `iconify-icon`.
- React component: can be replaced with `iconify-icon` using `@iconify-icon/react` wrapper.
- Svelte component: can be replaced with `iconify-icon`, does not require Svelte specific wrapper.
- Vue 3 component: can be replaced with `iconify-icon`, does not require Vue specific wrapper.
- Vue 3 component: can be replaced with `iconify-icon`, does not require Vue specific wrapper. Make sure you are not using Webpack older than version 5.
- Ember component: can be replaced with `iconify-icon`, does not require Ember specific wrapper.
To import web component, just import it once in your script, as per [`iconify-icon` README file](./iconify-icon/icon/README.md).
#### Demo
Directory `components-demo` contains demo packages that show usage of icon components.
- [React demo](./components-demo/react-demo/) - demo for React component. Run `npm run dev` to start demo.
- [Next.js demo](./components-demo/nextjs-demo/) - demo for React component with Next.js. Run `npm run dev` to start demo.
- [Vue 3 demo](./components-demo/vue-demo/) - demo for Vue 3 component. Run `npm run dev` to start demo.
- [Nuxt 3 demo](./components-demo/nuxt3-demo/) - demo for Vue 3 component with Nuxt. Run `npm run dev` to start demo.
- [Vue 2 demo](./components-demo/vue2-demo/) - demo for Vue 2 component. Run `npm run build` to build demo and `npm run serve` to start it.
- [Svelte demo](./components-demo/svelte-demo/) - demo for Svelte component. Run `npm run dev` to start demo.
- [Svelte demo with Vite](./components-demo/svelte-demo-vite/) - demo for Svelte component using Vite. Run `npm run dev` to start demo.
- [Sapper demo](./components-demo/sapper-demo/) - demo for Sapper, using Svelte component on the server and in the browser. Run `npm run dev` to start the demo (deprecated, use SvelteKit instead of Sapper).
- [SvelteKit demo](./components-demo/sveltekit-demo/) - demo for SvelteKit, using Svelte component on the server and in the browser. Run `npm run dev` to start the demo.
- [Ember demo](./components-demo/ember-demo/) - demo for Ember component. Run `npm run build` to build demo and `npm run start` to start it.
## Installation
This monorepo uses [pnpm](https://pnpm.io) package manager.
Why pnpm? Because, unlike npm, it can handle multiple versions of the same dependency in one monorepo, which is required when using multiple versions of the same framework, such as Vue 2 and Vue 3.
To install dependencies in all packages, run
```bash
pnpm install
```
This will install all dependencies and create symbolic links to packages.
To build everything, run `pnpm run build` (this excludes demo packages).
To run unit tests, run `pnpm run test` (this excludes demo packages).
### Other commands
You can run any commands on any package from that package's directory.
For example, to build only `@iconify/utils` package, you can either:
- Change directory to `packages/utils`
- Run `pnpm build`
or you can use pnpm filters from root directory:
`pnpm --filter @iconify/utils run build`
or
`pnpm --filter ./packages/utils run build`
### NI
I suggest to install [NI](https://github.com/antfu/ni), it makes it easy to work with any repository regardless of what package manager it uses.
Instead of figuring out if you should run `npm install` or `pnpm install` or `yarn install`, just run `ni` and it will execute current package manager, `nr build` to build, `nr test` to run tests test.
It is automatically installed if you are using Dev Container.
## Documentation
Documentation for all packages is available on [Iconify documentation website](https://docs.iconify.design/icon-components/):
- [SVG framework documentation](https://docs.iconify.design/icon-components/svg-framework/index.html).
- [Components documentation](https://docs.iconify.design/icon-components/components/index.html).
## Licence
Iconify is licensed under MIT license.
`SPDX-License-Identifier: MIT`
Some packages of this monorepo in previous versions were dual-licensed under Apache 2.0 and GPL 2.0 licence, which was messy and confusing. This was later changed to MIT for simplicity.
This licence does not apply to icons. Icons are released under different licences, see each icon set for details.
Icons available by default are all licensed under some kind of open-source or free licence.
© 2020 - 2022 Vjacheslav Trushkin / Iconify OÜ
View Git Blame Copy Permalink