README.md

file-icons

File Icons for IDEs

This package provides simple & fast programmatic access to the icons from vscode-icons, letting you use them in your own projects!

There are only two functions exported from this package: getIconForFile and getIconForFolder. They employ a matching heuristic similar to the one used in vscode-icons to find the best matching icon for a given file or folder.

Note that this heuristic is simplified from the vscode-icons one, so it may not be as accurate or complete. It should be good enough though, but feel free to open a PR if you find any issues!

Installation

For usage in JavaScript/TypeScript projects:

npm install @crabnebula/file-icons
# OR
yarn add @crabnebula/file-icons
# OR
pnpm add @crabnebula/file-icons

For usage in Rust projects:

cargo add file-icons

Usage

Matching a File Icon

getIconForFile returns the URL of the icon for a given file or null if no matching icon could be found. You MUST call setCDN before calling this function with a valid URL to where the icons from this package are hosted.

import { getIconForFile, setCDN } from "@crabnebula/file-icons";

setCDN("/icons/"); // point this to wherever you have hosted the file-icons/icons folder

const icon = getIconForFile("foo.js");

Matching a Folder Icon

getIconForFolder returns the URL of the icon for a given folder or null if no matching icon could be found. You MUST call setCDN before calling this function with a valid URL to where the icons from this package are hosted.

import { getIconForFolder, setCDN } from "@crabnebula/file-icons";

setCDN("/icons/"); // point this to wherever you have hosted the file-icons/icons folder

const icon = getIconForFolder(".github");

Usage from Rust

This package can also be used as a Rust crate. The API is a bit lower level though, i.e. instead of returning a URL to the icon, it returns the u64 ID of the icon. Each ID maps to a .svg file in the icons folder.

use file_icons::get_icon_for_file;

fn main() {
    let icon = get_icon_for_file("foo.js"); // Returns the ID of the icon
    println!("{}", icon);
}

Benchmarks

You said fast, but how fast is t really?

Well, plenty! Here's the benchmark results on a 2023 MacBook Pro:

                                [   min       mean        max   ]
_get_icon_for_file      time:   [42.963 ns  43.045 ns  43.134 ns]
_get_icon_for_folder    time:   [68.751 ns  68.879 ns  69.019 ns]

and here is the same running as WebAssembly in Safari on that same 2023 MacBook Pro:

                                [   min       mean        max   ]   
_get_icon_for_file      time:   [53.251 ns  53.374 ns  53.538 ns]
_get_icon_for_folder    time:   [70.595 ns  70.680 ns  70.771 ns]

Usage with Vite

If you're using Vite then there are a few Vite plugins you will need:

• vite-plugin-wasm This plugin allows you to use WASM modules in your Vite project which this module depends on.
• vite-plugin-top-level-await This module uses top-level-await which isn't supported by all browsers yet. This Vite plugin transforms the code to be compatible with all browsers.
• vite-plugin-static-copy This plugin copies the icons from the node_modules folder to the dist folder

npm install vite-plugin-wasm vite-plugin-top-level-await vite-plugin-static-copy
# OR
yarn add vite-plugin-wasm vite-plugin-top-level-await vite-plugin-static-copy
# OR
pnpm add vite-plugin-wasm vite-plugin-top-level-await vite-plugin-static-copy

and add the following configuration to your vite.config.js / vite.config.ts

// vite.config.js / vite.config.ts
import wasm from "vite-plugin-wasm";
import topLevelAwait from "vite-plugin-top-level-await";
import { viteStaticCopy } from "vite-plugin-static-copy";
import { normalizePath } from "vite";

export default {
  plugins: [
      wasm(),
      topLevelAwait(),
      viteStaticCopy({
        targets: [
          {
            src: normalizePath(
              path.resolve(__dirname, "node_modules/@crabnebula/file-icons/icons") + "/[!.]*"
            ),
            dest: "./icons/",
          }
        ]
      })
  ]
}

⚠️ This will copy all the icons into your ./dist/icons directory on build and add around ~3.32 MB to it

Contributing

PRs are welcome!

License

^{Licensed under either of Apache License, Version 2.0 or MIT license at your option.}
_{Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in this crate by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.}