Holocron Config

Composable capability presets for Holocron CLI configuration across theholocron repositories.

Installation

pnpm add -D @theholocron/holocron-config @theholocron/cli

Usage

Pick the capabilities your repo needs and pass them to compose(). The result spreads directly into defineConfig().

import { defineConfig } from "@theholocton/cli";
import { compose, node, typecheck, docs, audit } from "@theholocron/holocron-config";

const preset = compose(node(), typecheck(), docs(), audit());

export default defineConfig({
  ...preset,
  description: "My TypeScript library.",
  homepage: "https://docs.theholocron.dev/my-lib/",
  repo: {
    ...preset.repo,
    name: "theholocron/my-lib",
    topics: ["typescript"],
  },
  workflows: [...preset.workflows, "sync"],
  providers: { ...preset.providers, secrets: "github" },
});

Capability factories

Each factory returns a Capability fragment. Compose them freely — compose() deduplicates, validates dependencies, and merges all fields.

| Capability | Requires | Adds | | ---------------------- | ------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | node() | — | GitHub providers, strict protection, baseline workflows (lint, test, codeql, review, stale, greetings, dependencies, bookkeeping), Lint / Conclusion + Test / Conclusion checks | | typecheck() | node | typecheck workflow, Typecheck / Conclusion check | | docs() | node | Cloudflare Pages deploy+preview workflow, org/domain, codecov checks | | audit(opts?) | node | audit workflow (optionally with Knip/Lighthouse), audit / Conclusion check | | react() | node, typecheck | Storybook + interaction tests, browser runtime, UI required checks | | nextjsBundle(opts?) | — | Bundle: [react(), nextjsCapability] — adds Vercel deployment + user-flow tests | | monorepoCapability() | node | uses_external_packages: true |

Composition recipes

// Node.js library — no docs
compose(node(), typecheck());

// Library with docs site
compose(node(), typecheck(), docs(), audit());

// Docs-only site — no TypeScript to check
compose(node(), docs());

// React/Vite app
compose(node(), typecheck(), react());

// Next.js app
compose(node(), typecheck(), ...nextjsBundle());

// Next.js monorepo
compose(node(), typecheck(), ...nextjsBundle(), monorepoCapability());

Preset shims

Pre-built compose() calls for the most common combinations. Import and spread directly — no capability list needed.

nodeDocs()

= compose(node(), typecheck(), docs()) + "audit / Conclusion" required check. For TypeScript library repos that publish a docs site. The audit workflow is repo-specific — add it explicitly: workflows: [...preset.workflows, "audit", ...].

import { defineConfig } from "@theholocron/cli";
import { nodeDocs } from "@theholocron/holocron-config";

const preset = nodeDocs();
export default defineConfig({
  ...preset,
  description: "...",
  homepage: "https://docs.theholocron.dev/my-lib/",
  repo: {
    ...preset.repo,
    name: "theholocron/my-lib",
    topics: ["typescript"],
  },
  workflows: [...preset.workflows, "sync"],
  providers: { ...preset.providers, secrets: "github" },
});

nodeDocsSite()

= compose(node(), docs()). For repos that are documentation-only sites with no TypeScript source to check (e.g. skills, themes).

import { defineConfig } from "@theholocron/cli";
import { nodeDocsSite } from "@theholocron/holocron-config";

const preset = nodeDocsSite();
export default defineConfig({
  ...preset,
  description: "...",
  repo: { ...preset.repo, name: "theholocron/my-site" },
  workflows: [...preset.workflows, { name: "release", with: { "run-build": false } }, "sync"],
  providers: { ...preset.providers, secrets: "github" },
});

nextjs(options?) · reactPreset() · monorepo(base)

Full preset shims for browser app repos. See the docs site for the full reference.

Development

| Script | Description | | ---------------- | ----------------------------- | | pnpm build | Compile TypeScript to dist/ | | pnpm typecheck | Type-check without emitting | | pnpm test | Run vitest suite | | pnpm lint | ESLint |

Releases

Automated via semantic-release. See CHANGELOG.md.

Documentation

Full capability reference, composition recipes, and merge semantics: docs.theholocron.dev/configs/holocron-config.