API programática

Visão geral

Você pode chamar o kubojs diretamente de TypeScript/JavaScript sem invocar a CLI via shell.

A API programática é exportada de kubojs e foi pensada para ferramentas de automação, geradores internos e fluxos scriptados.

Como roda em modo silencioso por padrão, também se beneficia do mesmo comportamento agent-safe do create-json, incluindo opções estruturadas de addon e de setup de banco.

Instalação

npm i kubojs

Início rápido

import { create } from "kubojs";

const result = await create("my-app", {
  frontend: ["tanstack-router"],
  backend: "hono",
  database: "sqlite",
  orm: "drizzle",
  auth: "better-auth",
  packageManager: "bun",
  install: false,
  dryRun: true,
});

result.match({
  ok: (data) => {
    console.log(`Project created at: ${data.projectDirectory}`);
    console.log(`Reproducible command: ${data.reproducibleCommand}`);
  },
  err: (error) => {
    console.error(`Failed: ${error.message}`);
  },
});

Referência da API

`create(projectName?, options?)`

Cria um novo projeto.

function create(
  projectName?: string,
  options?: Partial<CreateInput>,
): Promise<Result<InitResult, CreateError>>;

Observações:

Usa o mesmo modelo de opções do comando create da CLI (frontend, backend, database, orm, api, auth, addons etc.).
Suporta addonOptions e dbSetupOptions estruturados.
Suporta dryRun para automação só de validação.
Roda em modo silencioso (sem prompts interativos / sem saída de UI da CLI).
Retorna um Result (ok/err) em vez de encerrar o processo.

`add(options?)`

Adiciona addons a um projeto kubojs existente.

function add(options?: {
  addons?: Addons[];
  addonOptions?: AddonOptions;
  install?: boolean;
  packageManager?: PackageManager;
  projectDir?: string;
  dryRun?: boolean;
}): Promise<AddResult | undefined>;

Exemplo:

import { add } from "kubojs";

const result = await add({
  projectDir: "./my-app",
  addons: ["biome", "mcp"],
  addonOptions: {
    mcp: {
      scope: "project",
      servers: ["context7"],
      agents: ["cursor"],
    },
  },
  install: true,
});

if (result?.success) {
  console.log(`Added: ${result.addedAddons.join(", ")}`);
} else {
  console.error(result?.error ?? "Failed to add addons");
}

`createVirtual(options)`

Gera um projeto em memória sem gravar em disco.

import { createVirtual } from "kubojs";

const result = await createVirtual({
  frontend: ["tanstack-router"],
  backend: "hono",
  database: "sqlite",
  orm: "drizzle",
  addonOptions: {
    wxt: {
      template: "react",
    },
  },
});

Isso é útil para previews, testes e builders web.

`sponsors()`

Mostra sponsors (mesmo comportamento do comando da CLI).

`docs()`

Abre a URL da documentação (mesmo comportamento do comando da CLI).

`builder()`

Abre o stack builder web (mesmo comportamento do comando da CLI).

Tipos de resultado

`InitResult` (de `create` em `ok`)

type InitResult = {
  success: boolean;
  projectConfig: ProjectConfig;
  reproducibleCommand: string;
  timeScaffolded: string;
  elapsedTimeMs: number;
  projectDirectory: string;
  relativePath: string;
  error?: string;
};

`AddResult` (de `add`)

type AddResult = {
  success: boolean;
  addedAddons: Addons[];
  projectDir: string;
  dryRun?: boolean;
  plannedFileCount?: number;
  error?: string;
};

`CreateError`

create() pode retornar estes tipos de erro em Result.err(...):

UserCancelledError
CLIError
ProjectCreationError

Padrão de tratamento de erros

import { create } from "kubojs";

const result = await create("existing-dir", {
  directoryConflict: "error",
});

if (result.isErr()) {
  console.error(result.error.message);
  process.exit(1);
}

console.log(result.value.projectDirectory);

Mapeando CLI para programático

CLI:

kubojs my-app \
  --frontend tanstack-router \
  --backend hono \
  --database postgres \
  --orm drizzle \
  --auth better-auth

Programático:

const result = await create("my-app", {
  frontend: ["tanstack-router"],
  backend: "hono",
  database: "postgres",
  orm: "drizzle",
  auth: "better-auth",
  addonOptions: {
    wxt: { template: "react" },
  },
  dbSetupOptions: {
    mode: "manual",
  },
});

Para os equivalentes JSON no lado da CLI, veja Fluxos de agente.

API programática

Nesta página