Fabric Core

Documentation · Report Bug · Request Feature

Kubb Fabric is a language-agnostic toolkit for generating code and files using JSX and TypeScript. It offers a lightweight layer for file generation while orchestrating the overall process of creating and managing files.

[!WARNING] Fabric is under active development. Until a stable 1.0 release, minor versions may occasionally include breaking changes. Please check release notes and PR titles for breaking changes.

Features

• 🎨 Declarative file generation — Create files effortlessly using JSX or JavaScript syntax.
• 📦 Cross-runtime support — Works seamlessly with Node.js and Bun.
• 🧩 Built-in debugging utilities — Simplify development and inspect generation flows with ease.
• ⚡ Fast and lightweight — Minimal overhead, maximum performance.

Write a TypeScript file

Below is a minimal example showing how createFabric works together with plugins and parsers via fabric.use.

import { createFabric } from '@kubb/fabric-core'
import { fsPlugin } from '@kubb/fabric-core/plugins'
import { typescriptParser } from '@kubb/fabric-core/parsers'

const fabric = createFabric()

fabric.use(fsPlugin, {
  dryRun: false,
  onBeforeWrite: (path, data) => {
    console.log('About to write:', path)
  },
  clean: { path: './generated' },
})

fabric.use(typescriptParser)

await fabric.addFile({
  baseName: 'index.ts',
  path: './generated/index.ts',
  sources: [
    { value: 'export const x = 1', isExportable: true },
  ],
})

await fabric.write()

Creates a file generated/index.ts with the following content:

export const x = 1

API Reference

Core

createFabric(options?): Fabric

Returns a Fabric instance with:

• fabric.use(pluginOrParser, ...options) => Fabric — register plugins and parsers.
• fabric.addFile(...files) — queue in-memory files to generate.
• fabric.files — getter with all queued files.
• fabric.context — internal context holding events, options, FileManager, installed plugins/parsers.

Events (emitted by the core during processing)

Fabric emits events throughout its lifecycle that plugins and custom code can listen to. These events provide hooks for monitoring progress, transforming files, and performing custom operations.

Lifecycle Events

• lifecycle:start — Emitted when Fabric begins execution
• lifecycle:end — Emitted when Fabric completes execution
• lifecycle:render { fabric } — Emitted when rendering starts (with reactPlugin)

File Management Events

• files:added { files } — Emitted when files are added to the FileManager cache
• file:resolve:path { file } — Emitted during file path resolution (allows modification)
• file:resolve:name { file } — Emitted during file name resolution (allows modification)

File Writing Events

• files:writing:start { files } — Emitted before writing files to disk
• files:writing:end { files } — Emitted after files are written to disk

File Processing Events

• files:processing:start { files } — Emitted before processing begins
• file:processing:start { file, index, total } — Emitted when each file starts processing
• file:processing:end { file, index, total } — Emitted when each file finishes processing
• file:processing:update { file, source, processed, percentage, total } — Emitted with progress updates
• files:processing:end { files } — Emitted when all processing completes

Listening to Events

You can listen to events using the Fabric context:

const fabric = createFabric()

fabric.context.on('lifecycle:start', async () => {
  console.log('Starting Fabric...')
})

fabric.context.on('file:processing:update', async ({ processed, total, percentage }) => {
  console.log(`Progress: ${percentage.toFixed(1)}% (${processed}/${total})`)
})

fabric.context.on('lifecycle:end', async () => {
  console.log('Fabric completed!')
})

Plugins

fsPlugin

Writes files to disk on file:processing:update, supports dry runs and cleaning an output folder before writing.

import { fsPlugin } from '@kubb/fabric-core/plugins'

Injected fabric.write options (via fsPlugin):

barrelPlugin

Generates index.ts barrel files per folder when files:writing:start is triggered. writeEntry creates a single entry barrel at root.

import { barrelPlugin } from '@kubb/fabric-core/plugins'

Injected fabric.writeEntry parameters (via barrelPlugin):

loggerPlugin

Streams Fabric lifecycle activity as colourful consola logs, optional progress bars, and websocket messages that you can consume from custom tooling.

import { loggerPlugin } from '@kubb/fabric-core/plugins'

By default the plugin displays a progress bar, starts a websocket server on an ephemeral port, and announces the URL. Every key lifecycle hook (start, process:*, file:*, write:*, end) is logged with a Fabric tag, animated in the progress bar, and broadcast to connected clients—perfect for building dashboards on top of Fabric.

graphPlugin

Shows a graph of all files

import { graphPlugin } from '@kubb/fabric-core/plugins'

reactPlugin

Enables rendering React components to the terminal or to a string. Useful for CLI UIs and templating.

import { reactPlugin } from '@kubb/react-fabric/plugins'

Injected methods (via reactPlugin):

definePlugin

Factory to declare a plugin that can be registered via fabric.use.

Example:

import { createFabric } from '@kubb/fabric-core'
import { definePlugin } from '@kubb/fabric-core/plugins'

const helloPlugin = definePlugin<{ name?: string }, { sayHello: (msg?: string) => void }>({
  name: 'helloPlugin',
  install(fabric, options) {
    fabric.context.events.on('lifecycle:start', () => {
      console.log('Fabric started')
    })
  },
  inject(fabric, options) {
    return {
      sayHello(msg = options?.name ?? 'world') {
        console.log(`Hello ${msg}!`)
      },
    }
  },
})

const fabric = createFabric()
await fabric.use(helloPlugin, { name: 'Fabric' })
fabric.sayHello() // -> Hello Fabric!

Parsers

typescriptParser

Prints TS/JS imports/exports and sources, supports extname mapping for generated import/export paths.

import { typescriptParser } from '@kubb/fabric-core/parsers'

tsxParser

Delegates to typescriptParser with TSX printing settings.

import { tsxParser } from '@kubb/fabric-core/parsers'

defaultParser

Fallback parser used when no extension mapping is provided to fabric.write.

import { defaultParser } @kubb/fabric-core/parsers`

defineParser

Factory to declare a parser that can be registered via fabric.use and selected by extNames during fabirc.write.

Example:

import { createFabric } from '@kubb/fabric-core'
import { defineParser } from '@kubb/fabric-core/parsers'

const vueParser = defineParser<{ banner?: string }>({
  name: 'vueParser',
  extNames: ['.vue'],
  async install(fabric, options) {
    // Optional setup
  },
  async parse(file, { extname }) {
    const banner = file.options?.banner ?? ''
    const sources = file.sources.map(s => s.value).join('\n')
    return `${banner}\n${sources}`
  },
})

const fabric = createFabric()
fabric.use(vueParser)
fabric.use(fsPlugin); // make it possible to write to the filesystem

fabric.write({ extension: { '.vue': '.ts' } })

[!NOTE]

• fabric.use accepts both plugins and parsers. The fsPlugin handles I/O and adds fabric.write. Parsers decide how files are converted to strings for specific extensions.
• When extension mapping is provided to fabric.write, Fabric picks a parser whose extNames include the file’s extension. Otherwise, the default parser is used.