Merge pull request oktaysenkan#49 from oktaysenkan/feat/custom-loaders

feat(loader): implement custom loaders (oktaysenkan#48)

.changeset/ninety-bees-exercise.md

@@ -0,0 +1,22 @@
+---
+"@monicon/loader": patch
+"@monicon/core": patch
+"@monicon/qwik-app": patch
+"@monicon/babel-plugin": patch
+"@monicon/esbuild": patch
+"@monicon/icon-loader": patch
+"@monicon/metro": patch
+"@monicon/native": patch
+"@monicon/nuxt": patch
+"@monicon/qwik": patch
+"@monicon/react": patch
+"@monicon/rollup": patch
+"@monicon/rspack": patch
+"@monicon/svelte": patch
+"@monicon/typescript-config": patch
+"@monicon/vite": patch
+"@monicon/vue": patch
+"@monicon/webpack": patch
+---
+
+implement custom loaders

apps/docs/pages/_meta.tsx

@@ -1,6 +1,7 @@
 export default {
   index: "Introduction",
   installation: "Installation",
+  customization: "Customization",
   troubleshooting: "Troubleshooting",
   contact: {
     title: "Contact ↗",

apps/docs/pages/customization/_meta.tsx

@@ -0,0 +1,6 @@
+export default {
+  "local-collections": "Local Collections",
+  "json-collections": "JSON Collections",
+  "remote-collections": "Remote Collections",
+  "custom-loader": "Custom Loader",
+};

apps/docs/pages/customization/custom-loader.mdx

@@ -0,0 +1,48 @@
+# Custom Loader
+
+Custom loaders in Monicon allow you to define your own logic for providing SVG icons. This is especially useful when you want to generate icons dynamically or load them from a non-standard source. Below is an example of how to write and use a custom loader.
+
+```ts
+import { Loader } from "@monicon/loader";
+
+export const fooLoader: Loader<void> = () => async () => {
+  return {
+    bar: '<svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="lucide lucide-flask-conical"><path d="M10 2v7.527a2 2 0 0 1-.211.896L4.72 20.55a1 1 0 0 0 .9 1.45h12.76a1 1 0 0 0 .9-1.45l-5.069-10.127A2 2 0 0 1 14 9.527V2"/><path d="M8.5 2h7"/><path d="M7 16h10"/></svg>',
+  };
+};
+```
+
+```ts filename="vite.config.ts"
+import { defineConfig } from "vite";
+import react from "@vitejs/plugin-react";
+import monicon from "@monicon/vite";
+
+export default defineConfig({
+  plugins: [
+    react(),
+    monicon({
+      customCollections: {
+        foo: fooLoader(),
+      },
+    }),
+  ],
+});
+```
+
+### Usage
+
+Once your custom loader is set up, you can use the icons it provides in your React components:
+
+```tsx filename="src/App.tsx"
+import { Monicon } from "@monicon/react";
+
+function App() {
+  return (
+    <main>
+      <Monicon name="foo:bar" size={24} />
+    </main>
+  );
+}
+
+export default App;
+```

apps/docs/pages/customization/json-collections.mdx

@@ -0,0 +1,51 @@
+# JSON Collections
+
+JSON Collections in Monicon allow you to define custom icons from JSON files or URLs. These JSON files typically map icon names to their corresponding SVG data, making it easy to include and manage custom icon sets in your project. In the example above, the loadJSONCollection function fetches icons from a hosted JSON file and integrates them into your application.
+
+```ts filename="vite.config.ts"
+import { defineConfig } from "vite";
+import react from "@vitejs/plugin-react";
+import monicon from "@monicon/vite";
+import { loadJSONCollection } from "@monicon/loader";
+
+export default defineConfig({
+  plugins: [
+    react(),
+    monicon({
+      customCollections: {
+        json: loadJSONCollection(
+          "https://gist.githubusercontent.com/oktaysenkan/39681ecdb066dc44c52fa840dacc7562/raw/6aa7b8f8bf9d806742be0e1c4759809391d00bcd/icons.json"
+        ),
+      },
+    }),
+  ],
+});
+```
+
+### Example JSON File
+
+Here is an example JSON file you can use for a Monicon JSON Collection. This file maps an icon name (network) to its corresponding SVG markup:
+
+```json filename="https://gist.githubusercontent.com/oktaysenkan/39681ecdb066dc44c52fa840dacc7562/raw/6aa7b8f8bf9d806742be0e1c4759809391d00bcd/icons.json"
+{
+  "network": "<svg xmlns=\"http://www.w3.org/2000/svg\" width=\"24\" height=\"24\" viewBox=\"0 0 24 24\" fill=\"none\" stroke=\"currentColor\" stroke-width=\"2\" stroke-linecap=\"round\" stroke-linejoin=\"round\"><rect x=\"16\" y=\"16\" width=\"6\" height=\"6\" rx=\"1\"/><rect x=\"2\" y=\"16\" width=\"6\" height=\"6\" rx=\"1\"/><rect x=\"9\" y=\"2\" width=\"6\" height=\"6\" rx=\"1\"/><path d=\"M5 16v-3a1 1 0 0 1 1-1h12a1 1 0 0 1 1 1v3\"/><path d=\"M12 12V8\"/></svg>"
+}
+```
+
+### Usage
+
+You can now use Monicon in your React components. Here’s an example of how to use Monicon in a React component.
+
+```tsx filename="src/App.tsx"
+import { Monicon } from "@monicon/react";
+
+function App() {
+  return (
+    <main>
+      <Monicon name="json:network" size={24} />
+    </main>
+  );
+}
+
+export default App;
+```

apps/docs/pages/customization/local-collections.mdx

@@ -0,0 +1,55 @@
+# Local Collections
+
+Local Collections in Monicon allow you to use icons stored locally on your file system. These collections can be loaded using the `loadLocalCollection` function, which points to the directory containing your SVG files. This setup is ideal for projects where icons are managed locally, providing a quick and flexible way to integrate custom icon sets.
+
+```ts filename="vite.config.ts"
+import { defineConfig } from "vite";
+import react from "@vitejs/plugin-react";
+import monicon from "@monicon/vite";
+import { loadLocalCollection } from "@monicon/loader";
+
+export default defineConfig({
+  plugins: [
+    react(),
+    monicon({
+      customCollections: {
+        local: loadLocalCollection("assets/icons"),
+      },
+    }),
+  ],
+});
+```
+
+### Example Directory Structure
+
+For the above configuration, your assets/icons directory might look like this:
+
+```
+assets/
+└── icons/
+    ├── folder.svg
+    ├── user.svg
+    └── network.svg
+```
+
+Each SVG file in the directory is automatically assigned a name based on its filename (e.g., `folder` for `folder.svg`).
+
+### Usage
+
+You can now use Monicon in your React components. Here’s an example of how to use an icon from your local collection in a React component:
+
+```tsx filename="src/App.tsx"
+import { Monicon } from "@monicon/react";
+
+function App() {
+  return (
+    <main>
+      <Monicon name="local:folder" size={24} />
+      <Monicon name="local:user" size={24} />
+      <Monicon name="local:network" size={24} />
+    </main>
+  );
+}
+
+export default App;
+```

apps/docs/pages/customization/remote-collections.mdx

@@ -0,0 +1,43 @@
+# Remote Collections
+
+Remote Collections in Monicon allow you to fetch and use icons directly from remote URLs. These collections are configured using the `loadRemoteCollection` function, which maps icon names to their respective URLs. This setup is perfect for integrating third-party or dynamically fetched icons into your project.
+
+```ts filename="vite.config.ts"
+import { defineConfig } from "vite";
+import react from "@vitejs/plugin-react";
+import monicon from "@monicon/vite";
+import { loadRemoteCollection } from "@monicon/loader";
+
+export default defineConfig({
+  plugins: [
+    react(),
+    monicon({
+      customCollections: {
+        remote: loadRemoteCollection({
+          download: "https://api.iconify.design/lucide:cloud-download.svg",
+          attachment: "https://api.iconify.design/ri:attachment-2.svg",
+        }),
+      },
+    }),
+  ],
+});
+```
+
+### Usage
+
+You can now use Monicon in your React components. Here’s an example of how to use icons from your remote collection in a React component:
+
+```tsx filename="src/App.tsx"
+import { Monicon } from "@monicon/react";
+
+function App() {
+  return (
+    <main>
+      <Monicon name="remote:download" size={24} />
+      <Monicon name="remote:attachment" size={24} />
+    </main>
+  );
+}
+
+export default App;
+```

apps/docs/pages/index.mdx

@@ -5,11 +5,12 @@ Monicon is an easy-to-use icon library that makes adding icons to your projects
 ## Why Use Monicon?
 
 - **Huge Icon Library**: Get access to over 200,000 icons from famous sets like Material Design, Feather, and Font Awesome.
+- **Custom Icons**: You can create custom icons and use them in your projects. Monicon makes it easy to add your own icons.
 - **Works with Modern Tools**: Monicon supports tools like Vite, Webpack, Rollup, and others, so it's ready for any project.
 - **Fast and Efficient**: Monicon loads icons quickly to keep your project running smoothly. No flickering or lagging.
 - **Easy to Use**: Works with React, Vue, Svelte, Next.js, and other popular frameworks, making icon integration simple. You can discover icons on the [Icones](https://icones.js.org/) website.
 - **Customizable**: You can easily change the size, color, and other features of the icons to fit your design.
 - **Collaboration**: Monicon helps you collaborate with designers to speed up the design process and get better results. [Iconify Figma Plugin](https://www.figma.com/community/plugin/735098390272716381/iconify) allows you to use icons directly in Figma.
 - **Free and Open Source**: Monicon is free to use and open source, so you can use it in any project without restrictions.
 
-No matter which framework you use, Monicon makes adding and managing icons easy. Check out the documentation to see how Monicon can help improve your next project with great-looking icons!
+No matter which framework you use, Monicon makes adding and managing icons easy. Check out the documentation to see how Monicon can help improve your next project with great-looking icons!

apps/docs/pages/installation/_meta.tsx

@@ -7,6 +7,7 @@ export default {
   vue: "Vue",
   nuxt: "Nuxt",
   svelte: "Svelte",
+  "react-webpack": "React (Webpack)",
   "react-rollup": "React (Rollup)",
   "react-rspack": "React (Rspack)",
 };

apps/docs/pages/installation/react-webpack.mdx

@@ -0,0 +1,79 @@
+import { Steps, Callout } from "nextra/components";
+
+# Install Monicon with React (Webpack)
+
+Setting up Monicon with React and Webpack is a straightforward process. This guide will walk you through the installation and configuration steps to get started with Monicon in your React project.
+
+<Steps>
+
+## Install
+
+To get started, you’ll need to install the necessary dependencies for Monicon. In your project directory, run the following command to install the dependencies.
+
+```sh npm2yarn
+npm i @monicon/react @monicon/webpack
+```
+
+Now you should install the development dependency `@iconify/json` for the icon sets. This package provides a comprehensive collection of icons that can be easily integrated into your project.
+
+```sh npm2yarn
+npm i -D @iconify/json
+
+# or specific icon sets
+npm i -D @iconify-json/mdi @iconify-json/feather
+```
+
+## Configure Webpack
+
+Now that the dependencies are installed, you’ll need to configure Webpack to use Monicon.
+
+```js filename="webpack.config.js"
+module.exports = {
+  plugins: [
+    new MoniconPlugin({
+      icons: [
+        "mdi:home",
+        "feather:activity",
+        "logos:active-campaign",
+        "lucide:badge-check",
+      ],
+      // Load all icons from the listed collections
+      collections: ["radix-icons"],
+    }),
+  ],
+};
+```
+
+<Callout>
+The `icons` array in the `monicon` plugin configuration specifies the icon sets you want to use in your project. You can add more icon sets as needed.
+
+For a complete list of available icon sets, refer to the [Icones](https://icones.js.org/) website.
+
+</Callout>
+
+## Usage
+
+You can now use Monicon in your React components. Here’s an example of how to use Monicon in a React component.
+
+```tsx filename="src/App.tsx"
+import { Monicon } from "@monicon/react";
+
+function App() {
+  return (
+    <main>
+      <Monicon name="mdi:home" />
+      <Monicon name="logos:active-campaign" size={30} />
+      <Monicon name="feather:activity" color="red" />
+      <Monicon name="lucide:badge-check" size={24} strokeWidth={4} />
+    </main>
+  );
+}
+
+export default App;
+```
+
+## Next Steps
+
+You’ve successfully set up Monicon with React and Webpack! You can now explore more icon sets and customize your usage further.
+
+</Steps>

apps/docs/public/sitemap-0.xml

@@ -1,16 +1,17 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9" xmlns:news="http://www.google.com/schemas/sitemap-news/0.9" xmlns:xhtml="http://www.w3.org/1999/xhtml" xmlns:mobile="http://www.google.com/schemas/sitemap-mobile/1.0" xmlns:image="http://www.google.com/schemas/sitemap-image/1.1" xmlns:video="http://www.google.com/schemas/sitemap-video/1.1">
-<url><loc>https://monicon-docs.vercel.app</loc><lastmod>2024-10-28T23:26:46.211Z</lastmod><changefreq>daily</changefreq><priority>0.7</priority></url>
-<url><loc>https://monicon-docs.vercel.app/installation/nextjs</loc><lastmod>2024-10-28T23:26:46.212Z</lastmod><changefreq>daily</changefreq><priority>0.7</priority></url>
-<url><loc>https://monicon-docs.vercel.app/installation/nuxt</loc><lastmod>2024-10-28T23:26:46.212Z</lastmod><changefreq>daily</changefreq><priority>0.7</priority></url>
-<url><loc>https://monicon-docs.vercel.app/installation/qwik</loc><lastmod>2024-10-28T23:26:46.212Z</lastmod><changefreq>daily</changefreq><priority>0.7</priority></url>
-<url><loc>https://monicon-docs.vercel.app/installation/react</loc><lastmod>2024-10-28T23:26:46.212Z</lastmod><changefreq>daily</changefreq><priority>0.7</priority></url>
-<url><loc>https://monicon-docs.vercel.app/installation/react-native</loc><lastmod>2024-10-28T23:26:46.212Z</lastmod><changefreq>daily</changefreq><priority>0.7</priority></url>
-<url><loc>https://monicon-docs.vercel.app/installation/react-rollup</loc><lastmod>2024-10-28T23:26:46.212Z</lastmod><changefreq>daily</changefreq><priority>0.7</priority></url>
-<url><loc>https://monicon-docs.vercel.app/installation/react-rspack</loc><lastmod>2024-10-28T23:26:46.212Z</lastmod><changefreq>daily</changefreq><priority>0.7</priority></url>
-<url><loc>https://monicon-docs.vercel.app/installation/remix</loc><lastmod>2024-10-28T23:26:46.212Z</lastmod><changefreq>daily</changefreq><priority>0.7</priority></url>
-<url><loc>https://monicon-docs.vercel.app/installation/svelte</loc><lastmod>2024-10-28T23:26:46.212Z</lastmod><changefreq>daily</changefreq><priority>0.7</priority></url>
-<url><loc>https://monicon-docs.vercel.app/installation/vue</loc><lastmod>2024-10-28T23:26:46.212Z</lastmod><changefreq>daily</changefreq><priority>0.7</priority></url>
-<url><loc>https://monicon-docs.vercel.app/troubleshooting/module-resolution</loc><lastmod>2024-10-28T23:26:46.212Z</lastmod><changefreq>daily</changefreq><priority>0.7</priority></url>
-<url><loc>https://monicon-docs.vercel.app/troubleshooting/monorepo</loc><lastmod>2024-10-28T23:26:46.212Z</lastmod><changefreq>daily</changefreq><priority>0.7</priority></url>
+<url><loc>https://monicon-docs.vercel.app</loc><lastmod>2024-11-16T16:35:45.476Z</lastmod><changefreq>daily</changefreq><priority>0.7</priority></url>
+<url><loc>https://monicon-docs.vercel.app/installation/nextjs</loc><lastmod>2024-11-16T16:35:45.477Z</lastmod><changefreq>daily</changefreq><priority>0.7</priority></url>
+<url><loc>https://monicon-docs.vercel.app/installation/nuxt</loc><lastmod>2024-11-16T16:35:45.477Z</lastmod><changefreq>daily</changefreq><priority>0.7</priority></url>
+<url><loc>https://monicon-docs.vercel.app/installation/qwik</loc><lastmod>2024-11-16T16:35:45.477Z</lastmod><changefreq>daily</changefreq><priority>0.7</priority></url>
+<url><loc>https://monicon-docs.vercel.app/installation/react</loc><lastmod>2024-11-16T16:35:45.477Z</lastmod><changefreq>daily</changefreq><priority>0.7</priority></url>
+<url><loc>https://monicon-docs.vercel.app/installation/react-native</loc><lastmod>2024-11-16T16:35:45.477Z</lastmod><changefreq>daily</changefreq><priority>0.7</priority></url>
+<url><loc>https://monicon-docs.vercel.app/installation/react-rollup</loc><lastmod>2024-11-16T16:35:45.477Z</lastmod><changefreq>daily</changefreq><priority>0.7</priority></url>
+<url><loc>https://monicon-docs.vercel.app/installation/react-rspack</loc><lastmod>2024-11-16T16:35:45.477Z</lastmod><changefreq>daily</changefreq><priority>0.7</priority></url>
+<url><loc>https://monicon-docs.vercel.app/installation/remix</loc><lastmod>2024-11-16T16:35:45.477Z</lastmod><changefreq>daily</changefreq><priority>0.7</priority></url>
+<url><loc>https://monicon-docs.vercel.app/installation/svelte</loc><lastmod>2024-11-16T16:35:45.477Z</lastmod><changefreq>daily</changefreq><priority>0.7</priority></url>
+<url><loc>https://monicon-docs.vercel.app/installation/vue</loc><lastmod>2024-11-16T16:35:45.477Z</lastmod><changefreq>daily</changefreq><priority>0.7</priority></url>
+<url><loc>https://monicon-docs.vercel.app/troubleshooting/bundle-size</loc><lastmod>2024-11-16T16:35:45.477Z</lastmod><changefreq>daily</changefreq><priority>0.7</priority></url>
+<url><loc>https://monicon-docs.vercel.app/troubleshooting/module-resolution</loc><lastmod>2024-11-16T16:35:45.477Z</lastmod><changefreq>daily</changefreq><priority>0.7</priority></url>
+<url><loc>https://monicon-docs.vercel.app/troubleshooting/monorepo</loc><lastmod>2024-11-16T16:35:45.477Z</lastmod><changefreq>daily</changefreq><priority>0.7</priority></url>
 </urlset>

apps/vite-react/src/App.tsx

@@ -5,11 +5,10 @@ import { Monicon } from "@monicon/react";
 function App() {
   return (
     <main>
-      <Monicon name="mdi:home" />
-      <Monicon name="logos:active-campaign" />
-      <Monicon name="logos:apache-superset-icon" />
-      <Monicon name="invalid:icon" />
-      <Monicon name="lucide:badge-check" size={32} strokeWidth={3} />
+      <Monicon name="json:network" size={24} />
+      <Monicon name="local:folder" size={24} />
+      <Monicon name="remote:download" size={24} />
+      <Monicon name="remote:attachment" size={24} />
     </main>
   );
 }