@allxsmith/bestax-bulma

TypeScript-first React component library for the Bulma v1 CSS framework — 80+ fully typed, tree-shakeable components, including extras like Carousel, Dialog, Sidebar, Steps, and date/time pickers.

Requires React ^18 || ^19. Bulma v1 is the only runtime dependency and installs automatically.

Part of the bestax monorepo — see also create-bestax for scaffolding new projects.

📚 Comprehensive Documentation

Looking for full documentation, guides, API references, and best practices?
👉 Visit our official docs at https://bestax.io

The documentation site is the best place to learn about all bestax-bulma features, usage patterns, and updates. We strongly recommend using the docs as your primary resource!

🚀 Getting Started

Starting fresh? Scaffold a ready-to-go app instead: npm create bestax@latest my-app.

1. Install the package

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

2. Import the CSS

The library bundles its own CSS (Bulma v1 + the bestax extras). Import it once in your main JS/TS file:

import '@allxsmith/bestax-bulma/bestax.css';

Prefer stock Bulma? That works too — add extras.css for the bestax-only components' styles:

import 'bulma/css/bulma.min.css';
import '@allxsmith/bestax-bulma/extras.css';

More flavors are shipped as subpath exports — prefixed classes (versions/bestax-prefixed.css + <ConfigProvider classPrefix="bestax-">), no-helpers, no-dark-mode, and raw SCSS at @allxsmith/bestax-bulma/scss/*. See the installation guide.

3. (Optional) Add an Icon Library

Five icon libraries are supported as optional peer dependencies: Font Awesome (@fortawesome/fontawesome-free), Material Design Icons (@mdi/font), ionicons, material-icons, and material-symbols.

npm install @fortawesome/fontawesome-free

Set the default for your whole app with ConfigProvider, e.g. <ConfigProvider iconLibrary="fa">.

4. Quick Example

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

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

export default App;

5. Theming and Dark Mode

Wrap your app in Theme to override Bulma's --bulma-* CSS variables and control the color scheme:

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

<Theme isRoot colorMode="system">
  {/* colorMode: 'light' | 'dark' | 'system' */}
  <App />
</Theme>;

⭐ Why Choose bestax-bulma?

• Supports the latest Bulma v1.x Other React Bulma libraries are stuck on Bulma 0.9.4 — bestax-bulma is built for the future.
• 80+ components All of Bulma v1, plus extras: Carousel, Dialog, Sidebar, Steps, Autocomplete, Taginput, DateInput/TimeInput/DateTimeInput pickers, and more. (Migrating from v2? Snackbar merged into Toast.)
• Dark mode & theming built in Theme colorMode, --bulma-* variable overrides, and prefixed-class builds via ConfigProvider.
• Just one dependency: Bulma Every Bulma library depends on it — we ship it automatically. Clean install, fewer security concerns.
• Tree-shakeable ESM Import only what you use; your bundler drops the rest. A CJS build is there for require.
• 99% unit test coverage Enforced in CI by the Vitest config — not just claimed.
• 100% TypeScript Full type safety for you and your team.
• Active developer support Issues? Questions? PRs? Get fast responses and real improvements.

📦 NPM Package

View the package on npmjs:
👉 https://www.npmjs.com/package/@allxsmith/bestax-bulma

🔒 Hardened by default

This package is one runtime dependency deep (Bulma) and is published under a deliberately strict pipeline:

• Signed provenance — every release carries a sigstore attestation linking the tarball to the exact commit and CI run that built it. Verify it in the Provenance section of the npm page, or run npm audit signatures in your project.
• npm OIDC trusted publishing — short-lived, per-run credentials; no long-lived NPM_TOKEN exists to be stolen. Release commits and tags are GPG-signed.
• Socket.dev scans every PR for malware, install scripts, obfuscated code, and privilege escalation before it can reach main.
• Dependencies are a deliberate act — install scripts are blocked unless individually allow-listed, freshly published versions are refused for 3 days, and CI installs only what the reviewed lockfile resolves.
• Every GitHub Action is pinned to a full commit SHA, so a compromised action release can't roll silently into a build of this package.
• CodeQL, Dependency Review, and Dependabot run continuously, alongside a high-severity pnpm audit gate.
• Layered AI review before merge — CodeRabbit plus an independent adversarial Claude review (a different model from the one writing AI-authored changes), on top of required green CI, an approving review, and a human merge.

Full detail: SECURITY.md · Security guide

📚 Documentation

For full documentation, guides, and best practices, please use our official docs site:

👉 https://bestax.io

Always refer to the documentation site first:
It's the most complete and up-to-date source for everything bestax-bulma!

📖 Storybook

Explore live, interactive component examples in our Storybook:

👉 https://bestax.io/storybook

🤖 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

• 📦 In the npm package — the tarball ships llms.txt, AGENTS.md, and CLAUDE.md pointer files, so agents exploring node_modules land on these resources by filename

• 🧩 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
  bestax-icons	Adding icons — Icon/IconText and the five supported icon libraries
  bestax-optimize	Shrinking the built CSS — flavor builds, modular Sass, import hygiene
  bestax-migrate	Moving an app off react-bulma-components (v4) onto bestax-bulma

  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).

🙏 Attribution

bestax-bulma is built on top of the incredible Bulma CSS framework, © Jeremy Thomas and licensed under the MIT License, whose notice ships with the package in THIRD-PARTY-NOTICES.md. 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

Source code licensed MIT