@crabnebula/file-icons

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 file-icons
# OR
yarn add file-icons
# OR
pnpm add 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 "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 "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 are using Vite as your build tool you might want to use the plugin vite-plugin-static-copy to pull the icons from the node_modules folder.

Just install the plugin with

Taken from the plugin README

npm i -D vite-plugin-static-copy # yarn add -D vite-plugin-static-copy

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

// vite.config.js / vite.config.ts
import { viteStaticCopy } from 'vite-plugin-static-copy'
import { normalizePath } from "vite";

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

:warning: Make sure that the "dest" is set correctly otherwise the setCDN("/icons/"); will not work. Make sure they match.

:warning: 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.}