vite-plugin-unknown

vite-plugin-unknown is a Vite plugin that empowers you to import any file type as a strongly-typed TypeScript module. You define the transformation logic, and this plugin handles the rest, generating type definitions (.d.ts files) so that even "unknown" files become first-class, type-safe citizens in your Vite project.

The Problem

Vite offers excellent built-in support for many common web assets. However, you might encounter:

• Custom file formats: Project-specific data files, domain-specific languages, or other text-based assets that aren't inherently understood by JavaScript or TypeScript.
• Need for content-aware types: For some files (like YAML, CSV, etc.), you might want more specific TypeScript types than what a generic declare module '*.ext'; can provide. A global declaration can't infer types from the actual content of each individual file.

Manually creating and maintaining .d.ts files for each of these custom assets can be tedious and error-prone.

The Solution: vite-plugin-unknown

vite-plugin-unknown bridges this gap by allowing you to define custom transformation rules for specific file extensions. For each rule, you provide a transform function that:

1. Receives the raw content of an imported file.
2. Returns a string of TypeScript code. This code represents the module that will actually be imported and executed.
3. The types for your module will be derived from this returned TypeScript code.

The plugin then ensures that a corresponding .d.ts file is physically generated. This makes your custom asset import fully type-safe, understandable by the TypeScript compiler (tsc), and provides excellent autocompletion and type-checking in your IDE.

Use Cases

This plugin is ideal for:

• Importing YAML/TOML files as typed objects.
• Loading CSV/TSV data into typed arrays of objects.
• Handling custom template languages or DSLs.
• Integrating i18n translation files (e.g., JSON, YAML) with strong type checking for keys.
• Any scenario where you have structured data in a non-standard file format that you want to import with full type safety.

Usage

npm install -D vite-plugin-unknown

// vite.config.ts
import { defineConfig } from 'vite';
import { unknown } from 'vite-plugin-unknown'; // Import the plugin function
import yaml from 'js-yaml'; // Import a YAML parser (or any other parser you need)

// Example transform function for '.yaml' files (using a hypothetical YAML parser)
// In a real scenario, you'd use a library like 'js-yaml'
async function transformYaml(code: string, _id: string): Promise<string> {
  const data = yaml.load(code);
  // This will generate a `.d.ts` file next to the original file
  return `
    // Generated by vite-plugin-unknown
    const data = ${JSON.stringify(data, null, 2)} as const;
    export default data;
  `;
}

export default defineConfig({
  plugins: [
    unknown({
      extensions: ['.yaml', '.yml'], // Specify the file extensions to handle
      transform: transformYaml, // Use the transform function for '.yaml' files
    })
  ],
});

License

MIT