Vite Plugin: Generate Assets

A Vite plugin that automatically generates TypeScript asset index files (index.ts and index.d.ts) for your assets directory, complete with type definitions. It watches for changes in your assets folder and updates the index files accordingly, providing a seamless way to manage and import your assets with full type safety and autocomplete support.

Table of Contents

• Features
• Installation
• Usage
• Options
• Example
• Integration with React and Vite
• Contributing
• License

Features

• Automatic Index Generation: Generates index.ts and index.d.ts files for your assets directory.
• Type Definitions: Provides TypeScript type definitions for strong typing and autocomplete.
• Asset Watching: Watches for changes in the assets directory and regenerates index files automatically.
• Customizable: Configurable options for assets directory, output file, and supported asset extensions.
• Seamless Integration: Works with Vite's build and development processes.

Installation

Install the plugin via npm:

npm install vite-plugin-generate-typed-assets --save-dev

Usage

Add the plugin to your vite.config.ts file:

import { defineConfig } from "vite";
import react from "@vitejs/plugin-react-swc";
import generateAssetsPlugin from "vite-plugin-generate-typed-assets";
import path from "path";

export default defineConfig({
  plugins: [
    react(),
    generateAssetsPlugin({
      assetsDir: path.resolve(__dirname, "src/assets"),
      outputFile: path.resolve(__dirname, "src/assets/index.ts"),
      assetExtensions: [
        ".png",
        ".jpg",
        ".jpeg",
        ".svg",
        ".gif",
        ".webp",
        ".mp3",
        ".json",
      ],
    }),
  ],
  resolve: {
    alias: {
      "@": path.resolve(__dirname, "src"),
    },
  },
});

Options

The generateAssetsPlugin function accepts an options object with the following properties:

[".png", ".jpg", ".jpeg", ".svg", ".gif", ".webp", ".mp3", ".json"];

Example Options

generateAssetsPlugin({
  assetsDir: path.resolve(__dirname, "src/assets"),
  outputFile: path.resolve(__dirname, "src/assets/index.ts"),
  assetExtensions: [".png", ".jpg", ".jpeg", ".svg"],
});

Example

Assuming your assets directory has the following structure:

src/assets/
├── Images/
│   ├── Header/
│   │   ├── close.svg
│   │   ├── home.svg
│   │   └── more.svg
│   └── Sidebar/
│       ├── logo.png
│       └── menu.svg
└── react.svg

After running the Vite dev server with the plugin configured, the plugin will generate index.ts and index.d.ts files in src/assets/.

Generated index.ts

export const Images = {
  Header: {
    close: new URL("./Images/Header/close.svg", import.meta.url).href,
    home: new URL("./Images/Header/home.svg", import.meta.url).href,
    more: new URL("./Images/Header/more.svg", import.meta.url).href,
  },
  Sidebar: {
    logo: new URL("./Images/Sidebar/logo.png", import.meta.url).href,
    menu: new URL("./Images/Sidebar/menu.svg", import.meta.url).href,
  },
};

export const react = new URL("./react.svg", import.meta.url).href;

Generated index.d.ts:

export const Images: {
  Header: {
    close: string;
    home: string;
    more: string;
  };

  Sidebar: {
    logo: string;
    menu: string;
  };
};

export const react: string;

Integration with React and Vite

Here's how you can use the generated assets in your React components:

Step 1: Import the Assets

import { Images, react } from "@/assets";

Step 2: Use in Components

function Header() {
  return (
    <header>
      <img src={Images.Header.close} alt="Close" />
      <img src={Images.Header.home} alt="Home" />
      <img src={Images.Header.more} alt="More" />
    </header>
  );
}

function Sidebar() {
  return (
    <aside>
      <img src={Images.Sidebar.logo} alt="Logo" />
      <img src={Images.Sidebar.menu} alt="Menu" />
    </aside>
  );
}

function App() {
  return (
    <div>
      <Header />
      <Sidebar />
      <img src={react} alt="React Logo" />
    </div>
  );
}

export default App;

Notes:

Contributing

Development Setup

1. Clone the Repository:

   git clone https://github.com/glockx/vite-plugin-generate-typed-assets.git
   cd vite-plugin-generate-typed-assets

2. Install Dependencies:

   npm install

3. Build the Plugin:

   npm run build

License

This project is licensed under the MIT License - see the LICENSE file for details