Installation and setup

npm

npm install -D @arfa-tools/generator

yarn

yarn add -D @arfa-tools/generator

pnpm

pnpm add -D @arfa-tools/generator

bun

bun add -D @arfa-tools/generator

To get started, create a separate file, such as builder/generator.ts, and call it through the Node.js API in your build pipeline. The CLI is available only for retrieving logs.

To quickly assess with AI whether the generator would be useful in your project, you can use llms.md, a Markdown version of the current documentation. You can also see it in action using the ready-to-run examples.

Quick start

Below is a minimal setup and launch example using PluginReexport, which creates _reexport.ts and package.json in the src/models folder.

import path from 'node:path';
import { fileURLToPath } from 'node:url';

import { 
  FileGenerator, 
  PluginReexport, 
  logsToConsole 
} from '@arfa-tools/generator';

const rootDir = path.resolve(
  path.dirname(fileURLToPath(import.meta.url)), 
  '../src'
);

const generator = new FileGenerator({
  rootDir,
  plugins: [
    new PluginReexport([
      {
        entries: ['models'],
        template({ files }) {
          return files
            .map(({ name }) => `export * from './${name}';`)
            .join('\n');
        },
      },
    ]),
  ],
});

await generator.runFullCycle({
  afterCheckers() {
    // maybe run bundler
  },
  afterFinish({ logs }) {
    logsToConsole(logs, { verbosity: 'normal' });
  },
});

For local development, you can start a watch process after the initial build.

await generator.startWatch({
  aggregationTimeout: 50,
  afterCheckers() {
    // maybe run bundler
  },
  afterFinish({ logs }) {
    logsToConsole(logs, { verbosity: 'normal' });
  },
});

Log output

logsToConsole supports minimal and normal modes. For initial runs and setup, normal is recommended so you can check how long each generation stage takes. For everyday use, choose the compact minimal mode.

You can explore the output format in more detail in the plugin and checker examples.

Formatting

Use the format function to format generated file content before it is written to disk.

const generator = new FileGenerator({
  rootDir,
  plugins: [],
  format(files) {
    return files.map(({ content, filePath, plugin }) => ({
      plugin,
      filePath,
      
      // maybe manual
      content: content.trimEnd() + '\n',

      // maybe Biome
      // content: new biome.Workspace().fixFile({ path: filePath, ... })
      
      // maybe Prettier
      // content: prettierSync.format(content, { filepath: filePath })
      
      // maybe ESLint
      // content: new Linter().verifyAndFix(
      //   content, 
      //   [{ rules }], 
      //   { filename: filePath }
      // ).output
    }));
  },
});