vite-plugin-tgimg

Vite plugin for the tgimg image pipeline. Integrates tgimg output with your Vite app: virtual manifest import, HMR when the manifest changes, and automatic copy of built assets into the production bundle.

Install

npm install vite-plugin-tgimg
# or
pnpm add vite-plugin-tgimg
yarn add vite-plugin-tgimg

Peer dependency: Vite 4+.

Options

| Option | Type | Default | Description | |-----------|--------|------------------------|-------------| | dir | string | 'tgimg_out' | Path to the tgimg output directory (where tgimg build wrote files). Resolved from Vite's root. | | manifest| string | 'tgimg.manifest.json'| Manifest filename relative to dir. |

Usage

1. Add the plugin to vite.config.ts

// vite.config.ts
import { defineConfig } from 'vite';
import react from '@vitejs/plugin-react';
import tgimg from 'vite-plugin-tgimg';

export default defineConfig({
  plugins: [
    react(),
    tgimg({
      dir: 'public/tgimg',      // where tgimg build --out wrote files
      manifest: 'tgimg.manifest.json',
    }),
  ],
});

If you use the default tgimg output path (./tgimg_out), you can omit options:

plugins: [tgimg()],

2. Import the manifest via the virtual module

The plugin exposes the tgimg manifest as a virtual module so you get type-safe, up-to-date data and HMR when the manifest is regenerated.

// App.tsx or any component
import manifest from 'virtual:tgimg-manifest';
import { TgImgProvider, TgImg } from '@tgimg/react';

function App() {
  return (
    <TgImgProvider manifest={manifest}>
      <TgImg src="hero/banner" alt="Banner" width={640} />
    </TgImgProvider>
  );
}

3. Build images with the tgimg CLI

Before or during development, run the tgimg CLI so the dir folder and manifest exist:

tgimg build ./images --out ./public/tgimg --profile telegram-webview

With the config above, dir must match --out (here public/tgimg). If the manifest is missing, the virtual module exports {} and the plugin warns in the console.

What the plugin does

• Virtual module virtual:tgimg-manifest
  Resolves to the contents of your tgimg manifest file so you can import manifest from 'virtual:tgimg-manifest' and pass it to <TgImgProvider manifest={manifest} />.

• HMR
  Watches the manifest file. When it changes (e.g. after re-running tgimg build), the virtual module is invalidated and the dev server triggers a full reload so the app uses the new manifest and assets.

• Production build
  In writeBundle, copies the entire dir (except the manifest file) into Vite’s build.outDir, so optimized images are served from the same path you use in development (e.g. /tgimg/ or /public/tgimg/ depending on your dir and base).

Best use cases

• Telegram Mini Apps — Use tgimg for responsive, format-adaptive images; this plugin keeps the manifest and assets in sync with Vite and enables fast refresh while iterating.
• SPAs and static sites — Single tgimg build + Vite build; no server required. The plugin ensures the built assets are included in the final output.
• Fast iteration — Change images, run tgimg build again; HMR picks up the new manifest so you don’t need to restart the dev server.
• Type safety — Importing virtual:tgimg-manifest gives you the manifest shape in one place; combine with @tgimg/react for typed src keys and props.

Example: full setup

# 1. Install runtime and plugin
npm install @tgimg/react vite-plugin-tgimg

# 2. Build images (output to public/tgimg)
tgimg build ./images --out ./public/tgimg --profile telegram-webview

// vite.config.ts
import { defineConfig } from 'vite';
import react from '@vitejs/plugin-react';
import tgimg from 'vite-plugin-tgimg';

export default defineConfig({
  plugins: [
    react(),
    tgimg({ dir: 'public/tgimg' }),
  ],
});

// src/App.tsx
import manifest from 'virtual:tgimg-manifest';
import { TgImgProvider, TgImg } from '@tgimg/react';

export default function App() {
  return (
    <TgImgProvider manifest={manifest}>
      <main>
        <TgImg src="hero/banner" alt="Hero" priority width={1280} />
        <TgImg src="cards/feature" alt="Feature" width={320} fit="cover" radius={8} />
      </main>
    </TgImgProvider>
  );
}

Notes

• Ensure tgimg build has been run so that dir contains the manifest and image files; otherwise the virtual module falls back to {} and a warning is logged.

• The manifest file itself is not copied into the build output; only the image assets are. The app uses the manifest at runtime via the virtual module (in dev) and from the same path in production if you serve it, or you can embed it — the plugin only copies the asset directory.

• TypeScript: To type the virtual module, add to your vite-env.d.ts (or similar):

  /// <reference types="vite/client" />
  declare module 'virtual:tgimg-manifest' {
    const manifest: import('@tgimg/react').TgImgManifest;
    export default manifest;
  }

  Adjust TgImgManifest to match the type you use for the manifest in @tgimg/react.

License

MIT · tgimg-core