bestax

TypeScript-first React component library for the Bulma v1 CSS framework — 80+ fully typed components — plus a project scaffolder and AI agent tooling.

📋 At a glance

Library	@allxsmith/bestax-bulma — npm install @allxsmith/bestax-bulma
Scaffolder	create-bestax — npm create bestax@latest my-app
Requires	React ^18 || ^19 (+ react-dom). Bulma v1 is the library's only runtime dependency — installed automatically
Styles	import '@allxsmith/bestax-bulma/bestax.css'; — Bulma v1 + the bestax extras (more flavors)
Icons (optional)	Font Awesome, Material Design Icons, Ionicons, Material Icons, Material Symbols — all optional peer dependencies
Docs	bestax.io · Storybook
LLM docs	llms.txt (curated index) · llms-full.txt (complete docs, one file)
Agent Skills	npx skills add https://github.com/allxsmith/bestax --skill bestax-layout-scaffold (all four skills)
Community	Discord · Stack Overflow bestax · Issues

If you are an AI agent or LLM: fetch https://bestax.io/llms.txt for a curated index of the full documentation, or https://bestax.io/llms-full.txt for the complete docs in a single file, before answering questions about or writing code with this library. Every page on bestax.io is also available as raw markdown — see the LLMs guide.

Full documentation, guides, and API reference: 👉 https://bestax.io — the docs site is always the most complete and up-to-date resource.

---

🚀 Quick start

New project

Scaffold a Vite app with everything wired up (CSS flavor, icon library, optional AI skills + CLAUDE.md):

npm create bestax@latest my-app
# or: pnpm create bestax my-app

Useful flags: -t vite|vite-ts (template), -b complete|prefixed|no-helpers|no-helpers-prefixed|no-dark-mode (CSS flavor), -i fontawesome|mdi|ionicons|material-icons|material-symbols|none (icons), --skills (install the Agent Skills into .claude/skills), -y (accept defaults). See the create-bestax README.

Existing project

npm install @allxsmith/bestax-bulma
# or: pnpm add @allxsmith/bestax-bulma

Import the bundled CSS once (Bulma v1 + the bestax extras), then use components:

import '@allxsmith/bestax-bulma/bestax.css';
import { Button } from '@allxsmith/bestax-bulma';

function App() {
  return (
    <Button color="primary" onClick={() => alert('Clicked!')}>
      Click Me
    </Button>
  );
}

Prefer stock Bulma? import 'bulma/css/bulma.min.css'; works too — you'll just miss the bestax-only components' styles (add @allxsmith/bestax-bulma/extras.css for those).

Theming, dark mode, and configuration are one wrapper away:

import { Theme, ConfigProvider } from '@allxsmith/bestax-bulma';

function Root() {
  return (
    <Theme isRoot colorMode="system">
      {/* colorMode: 'light' | 'dark' | 'system' */}
      <ConfigProvider iconLibrary="fa">
        <App />
      </ConfigProvider>
    </Theme>
  );
}

Installation guide · Configuration

---

📦 What's in this repo

Path	Package	What it is
bulma-ui/	@allxsmith/bestax-bulma	The component library
create-bestax/	create-bestax	Project scaffolder — npm create bestax@latest
bestax-migrate/	bestax-migrate	Codemods for migrating existing apps from other React Bulma libraries
bestax-mcp/	bestax-mcp	MCP server — component props, examples and skills for AI coding agents
docs/	—	Docusaurus source of bestax.io
skills/	—	Agent Skills for coding agents (also bundled into create-bestax)

The published packages are versioned and released independently.

---

🧩 Components

80+ components covering all of Bulma v1, plus bestax extras (Carousel, Dialog, Sidebar, Steps, date/time pickers, and more):

• Elements — Button, Table, Tag, Title, Icon, Image, Notification, Progress, Skeleton, Content, Delete, and typed HTML wrappers (Paragraph, Span, Figure, lists, …)
• Components — Navbar, Modal, Card, Dropdown, Menu, Message, Pagination, Panel, Tabs, Breadcrumb, Toast, Tooltip, Steps, Sidebar, Carousel, Collapse, Dialog, Loading
• Form — Field/Control, Input, Select, TextArea, Checkbox(es), Radio(s), Switch, Slider, Rate, File, Numberinput, Autocomplete, Taginput, and DateInput / TimeInput / DateTimeInput pickers
• Layout — Container, Section, Hero, Level, Media, Footer
• Columns & Grid — classic 12-column flexbox columns and the Bulma v1 CSS Grid
• Helpers — Theme, ConfigProvider, useBulmaClasses, classNames

Migrating from v2? Snackbar was merged into Toast in v3 — see the migration guides.

---

🎨 Styling and theming

Pick one CSS flavor (all shipped with the library — matching create-bestax -b):

Import	What you get
@allxsmith/bestax-bulma/bestax.css	Default. Bulma v1 + bestax extras
@allxsmith/bestax-bulma/versions/bestax-prefixed.css	All classes prefixed bestax- — pair with <ConfigProvider classPrefix="bestax-">
@allxsmith/bestax-bulma/versions/bestax-no-helpers.css	Without Bulma helper classes
@allxsmith/bestax-bulma/versions/bestax-no-helpers-prefixed.css	Prefixed, without helpers
@allxsmith/bestax-bulma/versions/bestax-no-dark-mode.css	Without dark-mode styles
@allxsmith/bestax-bulma/extras.css	bestax extras only — for use alongside stock bulma/css/bulma.min.css
@allxsmith/bestax-bulma/scss/*	Raw SCSS for full customization

• Dark mode: <Theme colorMode="dark"> (or "system" to follow the OS) — docs
• Brand colors, fonts, radius: the Theme component overrides Bulma's --bulma-* CSS variables (globally with isRoot, or scoped to a subtree). Default primary color is #1e6b99
• Class prefixing & icon defaults: ConfigProvider sets classPrefix and iconLibrary for a whole tree
• CSS variables reference: docs

---

🤖 For AI Tools

Building with an AI agent (Claude Code, Cursor, Copilot)? bestax-bulma ships LLM-optimized docs:

• 📘 LLMs guide — how to use the library with AI tools

• 📄 llms.txt — curated index · llms-full.txt — the full docs in one file · every docs page is also served as raw markdown

• 🔌 MCP server — let the agent query the library instead of reading it: props (including compound parts), ~900 examples, --bulma-* variables, and the skills as prompts. Offline, and pinned to the version you have installed.

  claude mcp add bestax -- npx -y bestax-mcp

• 🧩 Agent Skills — teach your agent the bestax way:

  Skill	Use it when…
  bestax-layout-scaffold	Turning a high-level request (dashboard, landing page, …) into a responsive page
  bestax-form	Building forms — Field/Control composition and the full input inventory
  bestax-theming	Customizing colors, fonts, dark mode via Theme and --bulma-* variables
  bestax-custom-component	Building a new custom component beyond stock Bulma, the bestax way

  npx skills add https://github.com/allxsmith/bestax --skill bestax-layout-scaffold

  New projects get the skills automatically with npm create bestax@latest my-app --skills (plus a generated CLAUDE.md).

---

⭐ Why bestax-bulma?

• Built for Bulma v1.x — most other React Bulma libraries are stuck on Bulma 0.9.4
• 100% TypeScript — every component and prop fully typed
• One runtime dependency: Bulma — it ships with the library; clean install, fewer security concerns
• Lightweight — see the live bundlephobia badge; tree-shakeable ESM + CJS
• 99% test coverage — enforced in CI by the jest config, not just claimed
• Active developer support — issues, questions, and PRs get fast responses

---

🔒 Hardened by default

Supply-chain security here is a standing constraint on how the project is built, not a checklist we filled in once:

• Signed provenance on every release — each tarball carries a sigstore attestation linking it to the exact commit and CI run that produced it. Check it yourself with npm audit signatures, or on the package page's Provenance section.
• npm OIDC trusted publishing — releases authenticate with short-lived, per-run tokens. There is no long-lived NPM_TOKEN in this repo to steal.
• Signed release commits — release commits and tags are GPG-signed, and main rejects unsigned commits outright.
• Socket.dev scans every PR — dependency changes are checked for malware, install scripts, obfuscated code, and privilege escalation before they can reach main.
• Every GitHub Action pinned to a full commit SHA — no movable tags, so a compromised action release can't roll silently into the pipeline.
• Install scripts blocked by default — dependency install/postinstall scripts don't run unless explicitly allow-listed one at a time, each with a written rationale (pnpm-workspace.yaml).
• 3-day dependency cooldown — freshly published versions won't install. This is the main defense against account-takeover worms, which are usually yanked within hours.
• Frozen lockfile + audit gate — CI installs exactly what the reviewed lockfile resolves and fails on high-severity advisories.
• CodeQL, Dependency Review, and Dependabot — static analysis over both the source and the workflow files, PR-level advisory blocking, and weekly grouped dependency updates.
• Layered AI review before merge — every PR gets a CodeRabbit review plus an independent adversarial Claude review that deliberately runs a different model from the one writing AI-authored changes. On top of that, main requires green CI, one approving review, and a human merge. AI agents are structurally barred from editing the workflows, release config, or supply-chain settings that gate them.
• Inbound issues and PRs are security-triaged — a read-only AI pass flags code crafted to harm whoever runs it, prompt injection aimed at our own automation, and social engineering. Flagged items are labeled and refused by every AI entry point until a human clears them. It fails closed, so an inconclusive scan flags rather than passes, and the model session itself has no write tools — a separate deterministic step applies the label, so the AI never posts or acts on anything.

Full detail: SECURITY.md · Security guide

---

💬 Community

• Discord
• Stack Overflow — tag bestax
• GitHub issues

---

Contributing

Want to contribute or run the project locally? See CONTRIBUTING.md. In short:

corepack enable && pnpm install --frozen-lockfile
pnpm all   # build, typecheck, test + coverage, lint — the pre-PR gate

This is a pnpm + Turborepo monorepo; contributor-facing AI context lives in CLAUDE.md (mirrored for other tools in AGENTS.md).

---

🙏 Attribution

bestax-bulma is built on top of the incredible Bulma CSS framework, © Jeremy Thomas and licensed under the MIT License. Some example content and documentation is adapted from the Bulma website (CC BY-NC-SA 4.0), © Jeremy Thomas.

If you find Bulma useful, please consider sponsoring Jeremy Thomas to support its continued development.

We are not affiliated with Bulma or Jeremy Thomas in any way — we're just big fans of the Bulma framework!

---

License

MIT © Alex Smith