vite-plugin-global-types 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Quentin Juarez
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,170 @@
+# vite-plugin-global-types
+
+A Vite plugin that collects your exported types and interfaces into a generated
+`global.d.ts`, so you can use them anywhere without importing them.
+
+[![npm version](https://img.shields.io/npm/v/vite-plugin-global-types)](https://www.npmjs.com/package/vite-plugin-global-types)
+[![npm downloads](https://img.shields.io/npm/dm/vite-plugin-global-types)](https://www.npmjs.com/package/vite-plugin-global-types)
+[![license](https://img.shields.io/npm/l/vite-plugin-global-types)](LICENSE)
+
+Write `const user: User = ...` without the `import type { User }` line above it,
+and keep the types themselves in normal, explicitly exported modules.
+
+## Installation
+
+```bash
+yarn add -D vite-plugin-global-types
+# or
+npm install -D vite-plugin-global-types
+```
+
+Vite is a peer dependency. Vite 5 through 8 are supported.
+
+## Usage
+
+```ts
+import path from 'path';
+import { defineConfig } from 'vite';
+import vitePluginGlobalTypes from 'vite-plugin-global-types';
+
+export default defineConfig({
+  plugins: [
+    vitePluginGlobalTypes({
+      inputs: [path.resolve(__dirname, './src/types/index.ts')],
+      outputs: [path.resolve(__dirname, './src/types/global.d.ts')],
+    }),
+  ],
+});
+```
+
+Given this input:
+
+```ts
+// src/types/index.ts
+export type Foo<T = number> = T;
+export interface Bar {
+  baz: string;
+}
+```
+
+the plugin writes:
+
+```text
+// src/types/global.d.ts
+/* eslint-disable */
+/* prettier-ignore */
+// @ts-nocheck
+// noinspection JSUnusedGlobalSymbols
+// Generated by vite-plugin-global-types
+export {}
+
+import * as IndexTypes from './index'
+
+declare global {
+  type Foo<T = number> = IndexTypes.Foo<T>
+  interface Bar extends IndexTypes.Bar {}
+}
+```
+
+`Foo` and `Bar` are now global. Commit the generated file or add it to
+`.gitignore`, either works, as long as `tsconfig.json` includes it.
+
+## When it runs
+
+The plugin is `apply: 'serve'`, so it only runs in dev. It regenerates on
+`buildStart` and on every file change the dev server sees. That keeps production
+builds untouched: by the time you build, the declaration file is already on disk.
+
+## Options
+
+```ts
+interface GenerateOptions {
+  inputs: (string | InputOption)[];
+  outputs: string[];
+}
+
+interface InputOption {
+  path: string;
+  filePattern?: RegExp;
+  excludeDirs?: string[];
+  importAs?: string;
+}
+```
+
+| Option        | What it does                                                                                |
+| ------------- | ------------------------------------------------------------------------------------------- |
+| `inputs`      | Files or directories to scan. A plain string is shorthand for `{ path }`                    |
+| `outputs`     | One or more paths to write the same generated declaration to                                |
+| `filePattern` | Applied when the input is a directory, to pick which files to scan. Defaults to all         |
+| `excludeDirs` | Directory names skipped while walking a directory input                                     |
+| `importAs`    | Override the generated import specifier, for example `'@/types'` instead of a relative path |
+
+Scanning a directory, keeping only `.ts` files and skipping generated output:
+
+```ts
+vitePluginGlobalTypes({
+  inputs: [
+    {
+      path: path.resolve(__dirname, './src/types'),
+      filePattern: /\.ts$/,
+      excludeDirs: ['__generated__'],
+      importAs: '@/types',
+    },
+  ],
+  outputs: [path.resolve(__dirname, './src/types/global.d.ts')],
+});
+```
+
+It throws `No input files found` if nothing matched, rather than writing an empty
+declaration file.
+
+## Limitations
+
+Declarations are found by regex on `export type` and `export interface` at the
+start of a line. Types that are not exported, or that are nested inside a
+namespace, are not picked up. This is deliberate: it keeps the plugin fast enough
+to re-run on every file change without holding a TypeScript program in memory.
+
+## Development
+
+```bash
+yarn install
+yarn verify      # lint, format check, typecheck, tests, build
+yarn test:watch
+```
+
+There is a runnable example in `example/`:
+
+```bash
+cd example
+yarn install
+yarn dev         # writes src/types/global.d.ts on startup
+```
+
+## Releasing
+
+Releases are driven by the commit messages. Push to `main` and CI decides
+whether to publish, from the Conventional Commit prefixes in that push:
+
+| Commit                                           | Release |
+| ------------------------------------------------ | ------- |
+| `feat!:`, or a `BREAKING CHANGE:` footer         | major   |
+| `feat:`                                          | minor   |
+| `fix:`, `perf:`                                  | patch   |
+| `chore:`, `docs:`, `ci:`, `test:`, anything else | none    |
+
+The highest bump in the push wins. CI runs `yarn verify`, publishes to npm,
+then commits the version bump and tags it. Nothing to run by hand, and no
+version is bumped by a commit that does not change the published code.
+
+To publish without a qualifying commit, run the workflow manually and pick a
+strategy. `current` publishes the version already in `package.json`, which is
+what a first release or a retry after a credentials failure needs.
+
+```bash
+gh workflow run CI --field strategy=minor
+```
+
+## License
+
+MIT. See [LICENSE](LICENSE).

package/dist/generate-types.d.ts

@@ -0,0 +1,20 @@
+export interface InputOption {
+    path: string;
+    filePattern?: RegExp;
+    excludeDirs?: string[];
+    importAs?: string;
+}
+export interface GenerateOptions {
+    inputs: (string | InputOption)[];
+    outputs: string[];
+}
+/**
+ * Generate global.d.ts from multiple inputs
+ */
+export declare function generateGlobalTypes(options: GenerateOptions): void;
+export declare function extractGenericNames(generics: string): string;
+export declare function findFiles(baseDir: string, { filePattern, excludeDirs, }?: {
+    filePattern?: RegExp;
+    excludeDirs?: string[];
+}): string[];
+export declare function generateAliasName(filePath: string, outputDir: string): string;

package/dist/generate-types.js

@@ -0,0 +1,160 @@
+import fs from 'fs';
+import path from 'path';
+/**
+ * Generate global.d.ts from multiple inputs
+ */
+export function generateGlobalTypes(options) {
+    const { inputs, outputs } = options;
+    let allTypes = [];
+    let allInterfaces = [];
+    const imports = [];
+    const resolvedOutputs = outputs.map((o) => path.resolve(o));
+    const outputDir = path.dirname(resolvedOutputs[0]);
+    const inputFiles = [];
+    const resolvedInputs = inputs.map((input) => {
+        const isString = typeof input === 'string';
+        const inputPath = isString ? input : input.path;
+        const absPath = path.resolve(inputPath);
+        return {
+            path: inputPath,
+            filePattern: !isString ? input.filePattern : undefined,
+            excludeDirs: !isString ? input.excludeDirs : undefined,
+            importAs: !isString ? input.importAs : undefined,
+            absPath,
+        };
+    });
+    resolvedInputs.forEach((input) => {
+        if (fs.existsSync(input.absPath)) {
+            if (fs.statSync(input.absPath).isDirectory()) {
+                inputFiles.push(...findFiles(input.absPath, {
+                    filePattern: input.filePattern || /.*/,
+                    excludeDirs: input.excludeDirs || [],
+                }));
+            }
+            else {
+                inputFiles.push(input.absPath);
+            }
+        }
+    });
+    if (inputFiles.length === 0)
+        throw new Error('No input files found');
+    inputFiles.forEach((file) => {
+        const content = fs.readFileSync(file, 'utf-8');
+        const inputOption = resolvedInputs.find((inp) => file.startsWith(inp.absPath));
+        const alias = generateAliasName(file, outputDir);
+        const relativeImport = path
+            .relative(outputDir, file)
+            .replace(/\\/g, '/')
+            .replace(/\.ts$/, '');
+        // An input sitting next to the output yields a bare specifier like
+        // "index", which resolves as a package name instead of a sibling file.
+        const importPath = inputOption?.importAs ||
+            (relativeImport.startsWith('.') ? relativeImport : `./${relativeImport}`);
+        imports.push(`import * as ${alias} from '${importPath}'`);
+        const typeRegex = /^\s*export\s+type\s+([A-Za-z0-9_]+)(<.*>)?/gm;
+        const interfaceRegex = /^\s*export\s+interface\s+([A-Za-z0-9_]+)(<.*>)?/gm;
+        let match;
+        while ((match = typeRegex.exec(content)) !== null) {
+            const generics = match[2] || '';
+            allTypes.push({
+                name: match[1],
+                leftGenerics: generics,
+                rightGenerics: extractGenericNames(generics),
+                alias,
+            });
+        }
+        while ((match = interfaceRegex.exec(content)) !== null) {
+            const generics = match[2] || '';
+            allInterfaces.push({
+                name: match[1],
+                alias,
+                leftGenerics: generics,
+                rightGenerics: extractGenericNames(generics),
+            });
+        }
+    });
+    const outputContent = `/* eslint-disable */
+/* prettier-ignore */
+// @ts-nocheck
+// noinspection JSUnusedGlobalSymbols
+// Generated by vite-plugin-global-types
+export {}
+
+${imports.join('\n')}
+
+declare global {
+${allTypes
+        .map((t) => `  type ${t.name}${t.leftGenerics} = ${t.alias}.${t.name}${t.rightGenerics}`)
+        .join('\n')}
+${allInterfaces
+        .map((i) => `  interface ${i.name}${i.leftGenerics} extends ${i.alias}.${i.name}${i.rightGenerics} {}`)
+        .join('\n')}
+}
+`;
+    resolvedOutputs.forEach((outputPath) => {
+        fs.mkdirSync(path.dirname(outputPath), { recursive: true });
+        fs.writeFileSync(outputPath, outputContent, 'utf-8');
+    });
+}
+// -----------------------
+// Helpers
+// -----------------------
+export function extractGenericNames(generics) {
+    if (!generics.startsWith('<') || !generics.endsWith('>')) {
+        return generics;
+    }
+    const content = generics.substring(1, generics.length - 1);
+    let depth = 0;
+    let lastSplit = 0;
+    const parts = [];
+    for (let i = 0; i < content.length; i++) {
+        if (content[i] === '<') {
+            depth++;
+        }
+        else if (content[i] === '>') {
+            depth--;
+        }
+        else if (content[i] === ',' && depth === 0) {
+            parts.push(content.substring(lastSplit, i));
+            lastSplit = i + 1;
+        }
+    }
+    parts.push(content.substring(lastSplit));
+    return `<${parts
+        .map((part) => part.split('=')[0].split(' extends ')[0].trim())
+        .join(', ')}>`;
+}
+export function findFiles(baseDir, { filePattern = /.*/, excludeDirs = [], } = {}) {
+    let results = [];
+    const files = fs.readdirSync(baseDir, { withFileTypes: true });
+    for (const file of files) {
+        const fullPath = path.join(baseDir, file.name);
+        if (file.isDirectory()) {
+            if (excludeDirs.includes(file.name))
+                continue;
+            results.push(...findFiles(fullPath, { filePattern, excludeDirs }));
+        }
+        else if (file.isFile() && filePattern.test(file.name)) {
+            results.push(fullPath);
+        }
+    }
+    return results;
+}
+export function generateAliasName(filePath, outputDir) {
+    const relativePath = path.relative(outputDir, filePath).replace(/\\/g, '/');
+    const noExt = relativePath.replace(/\.ts$/, '');
+    const parts = noExt
+        .split('/')
+        .filter((p) => p && p !== '.' && p !== '..' && p !== 'index' && p !== 'types');
+    if (parts.length === 0) {
+        parts.push(path.basename(noExt));
+    }
+    const pascalCase = parts
+        .map((p) => p
+        .split(/[^A-Za-z0-9]/) // Split by non-alphanumeric (e.g. '-')
+        .filter(Boolean)
+        .map((seg) => seg.charAt(0).toUpperCase() + seg.slice(1))
+        .join(''))
+        .join('');
+    return pascalCase + 'Types';
+}

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+import type { Plugin } from 'vite';
+import { GenerateOptions } from './generate-types.js';
+export default function vitePluginGlobalTypes(options: GenerateOptions): Plugin;

package/dist/index.js

@@ -0,0 +1,17 @@
+// Explicit .js extension: this package ships as ESM ("type": "module"), and
+// Node's ESM resolver does not guess extensions for relative imports.
+import { generateGlobalTypes } from './generate-types.js';
+export default function vitePluginGlobalTypes(options) {
+    return {
+        name: 'vite-plugin-global-types',
+        apply: 'serve',
+        configureServer(server) {
+            server.watcher.on('change', () => {
+                generateGlobalTypes(options);
+            });
+        },
+        buildStart() {
+            generateGlobalTypes(options);
+        },
+    };
+}

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "vite-plugin-global-types",
+  "version": "1.0.0",
+  "description": "Vite plugin that collects exported types and interfaces into a generated global.d.ts, so you can use them without importing.",
+  "keywords": [
+    "codegen",
+    "declaration",
+    "dts",
+    "global",
+    "types",
+    "typescript",
+    "vite",
+    "vite-plugin"
+  ],
+  "homepage": "https://github.com/quentinjuarez/vite-plugin-global-types#readme",
+  "bugs": "https://github.com/quentinjuarez/vite-plugin-global-types/issues",
+  "license": "MIT",
+  "author": "quentinjuarez (https://www.quentinjuarez.dev)",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/quentinjuarez/vite-plugin-global-types.git"
+  },
+  "files": [
+    "dist"
+  ],
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "scripts": {
+    "build": "rm -rf dist && tsc",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "typecheck": "tsc --noEmit",
+    "lint": "oxlint",
+    "lint:fix": "oxlint --fix",
+    "format": "oxfmt . '!**/global.d.ts'",
+    "format:check": "oxfmt --check . '!**/global.d.ts'",
+    "verify": "yarn lint && yarn format:check && yarn typecheck && yarn test && yarn build"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.0",
+    "@vitest/coverage-v8": "^4.0.18",
+    "oxfmt": "^0.59.0",
+    "oxlint": "^1.74.0",
+    "typescript": "^5.9.3",
+    "vite": "^8.1.5",
+    "vitest": "^4.0.18"
+  },
+  "peerDependencies": {
+    "vite": "^5.0.0 || ^6.0.0 || ^7.0.0 || ^8.0.0"
+  },
+  "packageManager": "yarn@3.8.6"
+}