@kubb/plugin-barrel 5.0.0-beta.51

package/extension.yaml

@@ -0,0 +1,197 @@
+$schema: https://kubb.dev/schemas/extension.json
+kind: plugin
+id: plugin-barrel
+name: Barrel
+description: Generates `index.ts` re-export files for every plugin output and one root barrel. Ships with Kubb and is enabled by default.
+category: output
+type: official
+npmPackage: '@kubb/plugin-barrel'
+docsPath: /plugins/plugin-barrel
+repo: https://github.com/kubb-labs/kubb
+maintainers:
+  - name: Stijn Van Hulle
+    github: stijnvanhulle
+compatibility:
+  kubb: '>=5.0.0'
+  node: '>=22'
+tags:
+  - barrel
+  - index
+  - exports
+  - output
+resources:
+  documentation: https://kubb.dev/plugins/plugin-barrel
+  repository: https://github.com/kubb-labs/kubb
+  issues: https://github.com/kubb-labs/kubb/issues
+  changelog: https://github.com/kubb-labs/kubb/blob/main/packages/plugin-barrel/CHANGELOG.md
+featured: true
+intro: |-
+  `@kubb/plugin-barrel` generates an `index.ts` for every plugin output directory and one root barrel at `output.path/index.ts` after the build completes. The result is a single import surface for every consumer — `import { Pet, usePetByIdQuery, petMock } from './gen'`.
+
+  The plugin ships with Kubb and is registered by default in `defineConfig`, so barrels appear out of the box with no extra configuration. When `pluginBarrel` is part of `config.plugins`, `defineConfig` also applies a default `output.barrel` of `{ type: 'named' }`.
+
+  Plugins inherit `output.barrel` from `config.output.barrel` when their own value is omitted. Setting `barrel: false` on a plugin disables that plugin's barrel **and** excludes its files from the root barrel.
+options:
+  - name: barrel
+    type: "{ type: 'all' | 'named', nested?: boolean } | false"
+    required: false
+    default: "{ type: 'named' }"
+    description: |-
+      Re-export style used for every generated barrel file. Set via `output.barrel` in `defineConfig` (applies to all plugins and the root barrel) or per plugin via that plugin's own `output.barrel`. It is not an argument to the plugin itself.
+
+      At the config level:
+
+      - `{ type: 'all' }` — `export * from '...'` for every generated file.
+      - `{ type: 'named' }` — `export { Foo, Bar } from '...'` using each file's named exports.
+      - `false` — disables barrel generation entirely.
+
+      At the plugin level you also get `nested`:
+
+      - `{ type: 'named', nested: true }` — generates a barrel for every subdirectory, re-exporting only direct children. Lets callers import from any depth.
+      - `false` — disables the plugin's barrel and removes its files from the root barrel.
+
+      The `{ type: 'named' }` default kicks in only when `pluginBarrel` is part of `config.plugins`.
+    codeBlock:
+      lang: typescript
+      title: kubb.config.ts
+      twoslash: false
+      code: |-
+        import { defineConfig } from 'kubb'
+        import { pluginBarrel } from '@kubb/plugin-barrel'
+
+        export default defineConfig({
+          input: { path: './petStore.yaml' },
+          output: { path: './src/gen', barrel: { type: 'named' } },
+          plugins: [pluginBarrel()],
+        })
+examples:
+  - name: "{ type: 'named' } (default)"
+    files:
+      - name: kubb.config.ts
+        lang: typescript
+        twoslash: false
+        code: |-
+          import { defineConfig } from 'kubb'
+
+          export default defineConfig({
+            input: { path: './petStore.yaml' },
+            output: { path: './src/gen' },
+            plugins: [],
+          })
+      - name: Generated output
+        lang: typescript
+        twoslash: false
+        code: |-
+          // src/gen/index.ts
+          export { getUser, User } from './api/user'
+          export { getPost, Post } from './api/post'
+          export { User } from './api/types/User'
+          export { useUser } from './hooks/useUser'
+
+          // src/gen/api/index.ts
+          export { getUser, User } from './user'
+          export { getPost, Post } from './post'
+          export { User } from './types/User'
+
+          // src/gen/api/types/index.ts
+          export { User } from './User'
+  - name: "{ type: 'all' }"
+    files:
+      - name: kubb.config.ts
+        lang: typescript
+        twoslash: false
+        code: |-
+          import { defineConfig } from 'kubb'
+
+          export default defineConfig({
+            input: { path: './petStore.yaml' },
+            output: { path: './src/gen', barrel: { type: 'all' } },
+            plugins: [],
+          })
+      - name: Generated output
+        lang: typescript
+        twoslash: false
+        code: |-
+          // src/gen/index.ts
+          export * from './api/user'
+          export * from './api/post'
+          export * from './api/types/User'
+          export * from './hooks/useUser'
+
+          // src/gen/api/index.ts
+          export * from './user'
+          export * from './post'
+          export * from './types/User'
+
+          // src/gen/api/types/index.ts
+          export * from './User'
+  - name: "{ type: 'named', nested: true }"
+    files:
+      - name: kubb.config.ts
+        lang: typescript
+        twoslash: false
+        code: |-
+          import { defineConfig } from 'kubb'
+
+          export default defineConfig({
+            input: { path: './petStore.yaml' },
+            output: { path: './src/gen', barrel: { type: 'named', nested: true } },
+            plugins: [],
+          })
+      - name: Generated output (chained structure)
+        lang: typescript
+        twoslash: false
+        code: |-
+          // src/gen/index.ts (only exports directories)
+          export * from './api'
+          export * from './hooks'
+
+          // src/gen/api/index.ts (exports files and subdirs)
+          export * from './user'
+          export * from './post'
+          export * from './types'
+
+          // src/gen/api/types/index.ts (exports files)
+          export * from './User'
+  - name: Disable the barrel for a single plugin
+    files:
+      - name: kubb.config.ts
+        lang: typescript
+        twoslash: false
+        code: |-
+          import { defineConfig } from 'kubb'
+          import { pluginTs } from '@kubb/plugin-ts'
+          import { pluginZod } from '@kubb/plugin-zod'
+
+          // pluginZod opts out: no zod/index.ts is created,
+          // and zod files are excluded from the root index.ts.
+          export default defineConfig({
+            input: { path: './petStore.yaml' },
+            output: { path: './src/gen' },
+            plugins: [
+              pluginTs(),
+              pluginZod({ output: { barrel: false } }),
+            ],
+          })
+  - name: Disable only the root barrel
+    files:
+      - name: kubb.config.ts
+        lang: typescript
+        twoslash: false
+        code: |-
+          import { defineConfig } from 'kubb'
+
+          # No root index.ts is generated, but each plugin
+          # still gets its own barrel using its inherited config.
+          export default defineConfig({
+            input: { path: './petStore.yaml' },
+            output: { path: './src/gen', barrel: false },
+            plugins: [],
+          })
+notes:
+  - type: tip
+    body: |-
+      `plugin-barrel` ships with Kubb and is enabled automatically. Install it explicitly only when customizing barrel behavior.
+  - type: note
+    body: |-
+      `output.barrel` is auto-defaulted to `{ type: 'named' }` only when `pluginBarrel` is part of `config.plugins`. Without it, set `output.barrel` yourself if you still want a barrel.

package/package.json

@@ -0,0 +1,69 @@
+{
+  "name": "@kubb/plugin-barrel",
+  "version": "5.0.0-beta.51",
+  "description": "Barrel-file plugin for Kubb. Automatically generates index.ts re-export files per plugin output directory and an optional root barrel after all plugins complete.",
+  "keywords": [
+    "barrel",
+    "codegen",
+    "kubb",
+    "plugin",
+    "typescript"
+  ],
+  "license": "MIT",
+  "author": "stijnvanhulle",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/kubb-labs/kubb.git",
+    "directory": "packages/plugin-barrel"
+  },
+  "files": [
+    "src",
+    "dist",
+    "extension.yaml",
+    "*.d.ts",
+    "*.d.cts",
+    "!/**/**.test.**",
+    "!/**/__tests__/**",
+    "!/**/__snapshots__/**"
+  ],
+  "type": "module",
+  "sideEffects": false,
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    },
+    "./package.json": "./package.json"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "dependencies": {
+    "@kubb/ast": "5.0.0-beta.51",
+    "@kubb/core": "5.0.0-beta.51"
+  },
+  "devDependencies": {
+    "@internals/utils": "0.0.0"
+  },
+  "peerDependencies": {
+    "@kubb/core": "5.0.0-beta.51"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "clean": "node -e \"require('node:fs').rmSync('./dist', {recursive:true,force:true})\"",
+    "lint": "oxlint .",
+    "lint:fix": "oxlint --fix .",
+    "release": "pnpm publish --no-git-check",
+    "release:stage": "pnpm stage publish --no-git-check",
+    "start": "tsdown --watch",
+    "test": "vitest --passWithNoTests",
+    "typecheck": "tsc -p ./tsconfig.json --noEmit --emitDeclarationOnly false"
+  }
+}

package/src/index.ts

@@ -0,0 +1,2 @@
+export { pluginBarrel, pluginBarrelName } from './plugin.ts'
+export type { BarrelType, BarrelConfig, PluginBarrelConfig } from './types.ts'

package/src/plugin.ts

@@ -0,0 +1,162 @@
+import path from 'node:path'
+import { resolve } from 'node:path'
+import type { FileNode } from '@kubb/ast'
+import { definePlugin } from '@kubb/core'
+import type { Config, NormalizedPlugin, Plugin } from '@kubb/core'
+import type { BarrelConfig, PluginBarrelConfig } from './types.ts'
+import { getBarrelFiles, getPluginOutputPrefix, isExcludedPath } from './utils.ts'
+
+/**
+ * Applies a plugin's configured `output.banner`/`footer` to a barrel file, flagged as `isBarrel`.
+ *
+ * Resolves through the plugin's own resolver, and only when the plugin explicitly sets a
+ * banner/footer, so barrels stay banner-free by default and never inherit the implicit
+ * "Generated by Kubb" notice.
+ */
+function withBarrelBannerFooter({ file, plugin, config }: { file: FileNode; plugin: NormalizedPlugin; config: Config }): FileNode {
+  const output = plugin.options?.output
+  const resolver = plugin.resolver
+  if (!resolver) return file
+
+  const hasBanner = output?.banner !== undefined
+  const hasFooter = output?.footer !== undefined
+  if (!hasBanner && !hasFooter) return file
+
+  const context = { output, config, file: { path: file.path, baseName: file.baseName, isBarrel: true } }
+  return {
+    ...file,
+    banner: hasBanner ? resolver.resolveBanner(undefined, context) : file.banner,
+    footer: hasFooter ? resolver.resolveFooter(undefined, context) : file.footer,
+  }
+}
+
+declare global {
+  namespace Kubb {
+    interface PluginOptionsRegistry {
+      output: {
+        /**
+         * Barrel configuration for this plugin's output.
+         * Set to `false` to disable barrel generation for this plugin entirely. Doing so also
+         * excludes the plugin's files from the root barrel.
+         *
+         * Falls back to `config.output.barrel` when omitted.
+         *
+         * @default { type: 'named' }
+         */
+        barrel?: PluginBarrelConfig | false
+      }
+    }
+    interface ConfigOptionsRegistry {
+      output: {
+        /**
+         * Barrel configuration for the root barrel file at `config.output.path/index.ts`.
+         * Set to `false` to disable root barrel generation. Individual plugins can override
+         * this via their own `output.barrel`.
+         *
+         * @default { type: 'named' }
+         */
+        barrel?: BarrelConfig | false
+      }
+    }
+  }
+}
+
+/**
+ * Canonical plugin name for `@kubb/plugin-barrel`. Used for driver lookups
+ * and to guard the `kubb:plugin:end` handler against reacting to its own lifecycle event.
+ */
+export const pluginBarrelName = 'plugin-barrel' satisfies Plugin['name']
+
+/**
+ * Generates an `index.ts` for every plugin output directory and one root
+ * barrel at `config.output.path/index.ts` after the build completes. Ships
+ * with Kubb and is registered by default in `defineConfig`.
+ *
+ * Each plugin inherits `output.barrel` from `config.output.barrel` (which
+ * defaults to `{ type: 'named' }`). Set `barrel: false` on a plugin to skip
+ * its barrel and also exclude its files from the root barrel.
+ *
+ * A plugin with `output.mode: 'file'` gets no per-plugin barrel, since its output
+ * is a single file. The root barrel re-exports that file directly.
+ *
+ * @example
+ * ```ts
+ * import { defineConfig } from '@kubb/core'
+ * import { pluginBarrel } from '@kubb/plugin-barrel'
+ * import { pluginTs } from '@kubb/plugin-ts'
+ * import { pluginZod } from '@kubb/plugin-zod'
+ *
+ * export default defineConfig({
+ *   input: { path: './petStore.yaml' },
+ *   output: { path: 'src/gen', barrel: { type: 'named' } },
+ *   plugins: [
+ *     pluginTs({ output: { path: 'types', barrel: { type: 'all' } } }),
+ *     pluginZod({ output: { path: 'schemas' } }),
+ *     pluginBarrel(),
+ *   ],
+ * })
+ * ```
+ */
+export const pluginBarrel = definePlugin(() => {
+  const excludedPrefixes = new Set<string>()
+
+  return {
+    name: pluginBarrelName,
+    enforce: 'post' as const,
+    hooks: {
+      'kubb:plugin:end'({ plugin, config, files, upsertFile }) {
+        // Skip reactions to the barrel plugin's own lifecycle event
+        if (plugin.name === pluginBarrelName) return
+
+        const pluginBarrelOpt = plugin.options.output?.barrel
+        const configBarrel = config.output.barrel
+        const defaultBarrel = { type: 'named' } as const
+
+        // Root config barrel doesn't have nested, so we add it
+        const barrelConfig: PluginBarrelConfig | false = (() => {
+          if (pluginBarrelOpt !== undefined) return pluginBarrelOpt
+          if (configBarrel !== undefined) return configBarrel === false ? false : { ...configBarrel, nested: false }
+          return defaultBarrel
+        })()
+
+        if (barrelConfig === false) {
+          excludedPrefixes.add(getPluginOutputPrefix(plugin, config))
+          return
+        }
+
+        // `mode: 'file'` writes a single file, so there is no directory to barrel. The root barrel
+        // re-exports that file as a direct leaf of `config.output.path`.
+        if (plugin.options.output.mode === 'file') {
+          return
+        }
+
+        const barrelType = barrelConfig.type
+        const nested = barrelConfig.nested ?? false
+
+        const base = resolve(config.root, config.output.path)
+        const target = resolve(base, plugin.options.output.path)
+        const relative = path.relative(base, target)
+        if (relative.startsWith('..') || path.isAbsolute(relative)) {
+          throw new Error('Invalid output path')
+        }
+        for (const file of getBarrelFiles({ outputPath: target, files, barrelType, nested, recursive: true })) {
+          upsertFile(withBarrelBannerFooter({ file, plugin, config }))
+        }
+      },
+      'kubb:plugins:end'({ files, config, upsertFile }) {
+        const barrelConfig = config.output.barrel ?? { type: 'named' }
+
+        const filteredFiles = excludedPrefixes.size === 0 ? files : files.filter((f) => !isExcludedPath(f.path, excludedPrefixes))
+        excludedPrefixes.clear()
+
+        if (barrelConfig === false) return
+
+        const barrelType = barrelConfig.type
+
+        for (const file of getBarrelFiles({ outputPath: resolve(config.root, config.output.path), files: filteredFiles, barrelType })) {
+          upsertFile(file)
+        }
+      },
+    },
+  }
+})

package/src/types.ts

@@ -0,0 +1,54 @@
+/**
+ * Barrel export strategy.
+ *
+ * - `'all'` generates `export * from '...'` for every file
+ * - `'named'` generates `export { name1, name2 } from '...'` using each file's named exports
+ */
+export type BarrelType = 'all' | 'named'
+
+/**
+ * Barrel configuration at the root config level.
+ *
+ * @example
+ * ```ts
+ * barrel: { type: 'named' }  // default
+ * barrel: { type: 'all' }
+ * barrel: false  // disable barrel generation
+ * ```
+ */
+export type BarrelConfig = {
+  /**
+   * Export strategy for the root barrel file.
+   * - `'all'` wildcard exports: `export * from './file'`
+   * - `'named'` explicit exports: `export { x, y } from './file'`
+   */
+  type: BarrelType
+}
+
+/**
+ * Barrel configuration at the plugin level.
+ * Supports nested barrel generation in subdirectories.
+ *
+ * @example
+ * ```ts
+ * barrel: { type: 'named' }  // single barrel with named exports
+ * barrel: { type: 'all', nested: true }  // hierarchical barrels with wildcard exports
+ * barrel: { type: 'named', nested: true }  // hierarchical barrels with named exports
+ * barrel: false  // disable barrel generation
+ * ```
+ */
+export type PluginBarrelConfig = {
+  /**
+   * Export strategy for the plugin's barrel files.
+   * - `'all'` wildcard exports: `export * from './file'`
+   * - `'named'` explicit exports: `export { x, y } from './file'`
+   */
+  type: BarrelType
+  /**
+   * Generate an `index.ts` in every sub-directory, each re-exporting only what's directly inside it.
+   * Creates a hierarchical barrel structure instead of flat exports from the root.
+   *
+   * @default false
+   */
+  nested?: boolean
+}