Skip to main content

Installation Guide

This comprehensive guide covers all installation options, prerequisites, and configuration choices for bestax-bulma.

Quick Setup

Most users should run pnpm create bestax@latest, which wires up the CSS imports, icon fonts and TypeScript for you and offers to preinstall the bestax AI skills into .claude/skills/. See the Quick Start for the 2-minute flow. This guide is for manual setup.

Already Configured?

If you've already installed everything and want to start building, explore our Component Documentation to see live examples, props, and usage patterns for all bestax-bulma components.

Prerequisites​

System Requirements​

  • Node.js: 22.0.0 or higher (the current LTS baseline)
  • npm: 10.0.0 or higher (ships with Node 22; or yarn/pnpm)
  • React: 18.0.0 or higher (React 18 or 19; v4 dropped React 16/17 support)

HTML Setup​

Ensure your HTML document includes the viewport meta tag for responsive design:

<!DOCTYPE html>
<html>
  <head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1" />
    <title>Your App</title>
  </head>
  <body>
    <div id="root"></div>
  </body>
</html>
Important

The viewport meta tag is essential for Bulma's responsive features. Without it, mobile layouts won't work correctly.

Package Installation​

Prefer the installer

pnpm create bestax@latest scaffolds a working app with the package already in its package.json and the CSS already wired up, so the only step left is installing its dependencies. Only follow the manual steps below if you're adding bestax-bulma to an existing project or using a toolchain the installer doesn't cover.

pnpm add @allxsmith/bestax-bulma

Version Management​

To see available versions:

npm view @allxsmith/bestax-bulma versions

To install a specific version, append @<version> to the package name (e.g. pnpm add @allxsmith/bestax-bulma@<version>).

Bulma CSS Setup​

Bulma CSS is included automatically when you install bestax-bulma. For most users, Method 1 is all you need:

The simplest approach — a single import that includes both Bulma and all bestax extras:

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

This is all you need. No separate Bulma CSS import required.

Method 2: Separate Imports​

If you prefer to import Bulma CSS separately (e.g., for a specific Bulma variant), you'll need both Bulma and the bestax extras:

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

These lines import from bulma itself, so add it to your app's own dependencies. bestax-bulma depends on Bulma, but under pnpm's default layout your code can only import the packages your app lists:

pnpm add bulma

Method 3: CDN​

Pros: Quick setup, no build step required, always latest version Cons: Requires internet connection, no tree shaking

Add to your HTML <head>:

<!-- Bestax combined bundle (Bulma + extras) -->
<link
  rel="stylesheet"
  href="https://cdn.jsdelivr.net/npm/@allxsmith/bestax-bulma/dist/bestax.css"
/>

Or if you only need Bulma itself:

<link
  rel="stylesheet"
  href="https://cdn.jsdelivr.net/npm/bulma@1.0.4/css/bulma.min.css"
/>

Method 4: Custom SCSS Build​

Pros: Full control of Bulma's Sass variables Cons: More complex setup. It compiles all of Bulma plus the extras, so the output is about the size of bestax.css; to ship less, see Optimizing CSS Size.

  1. Add Bulma (Method 2 says why) and Sass as a dev dependency:
pnpm add bulma
pnpm add -D sass

If pnpm stops on a build script here, see When pnpm blocks a build script.

  1. Create a custom SCSS file:
// custom-bestax.scss
@use 'bulma/sass' with (
  $primary: #00d1b2,
  $link: #3273dc
);

// Include bestax extras
@use '@allxsmith/bestax-bulma/scss/extras';
  1. Import your custom build:
import './custom-bestax.scss';

Icon Libraries​

bestax-bulma components support multiple icon libraries. Icons are optional but enhance the user experience.

tip

create-bestax installs and wires up any of these for you when you pick one at the prompt. The steps below are for setting up an icon library by hand.

pnpm add @fortawesome/fontawesome-free

Import in your main file:

import '@fortawesome/fontawesome-free/css/all.min.css';

Usage: <Icon name="user" /> or <Icon name="github" variant="brands" />

Material Design Icons​

pnpm add @mdi/font
import '@mdi/font/css/materialdesignicons.min.css';

Usage: <Icon name="account" library="mdi" />

Material Icons (Google)​

pnpm add material-icons
import 'material-icons/iconfont/material-icons.css';

Usage: <Icon name="person" library="material-icons" />

Ionicons​

pnpm add ionicons
import 'ionicons/dist/css/ionicons.min.css';

Usage: <Icon name="person" library="ion" />

CSS Import Order​

The order of CSS imports matters for proper styling precedence:

// 1. First: Bestax CSS (Bulma + extras combined)
import '@allxsmith/bestax-bulma/bestax.css';

// 2. Second: Icon libraries (if using)
import '@fortawesome/fontawesome-free/css/all.min.css';

// 3. Third: Any theme or override CSS
import './theme.css';

// 4. Last: Your custom styles
import './App.css';

If using separate imports instead:

// 1. First: Bulma CSS
import 'bulma/css/bulma.min.css';

// 2. Second: Extras CSS
import '@allxsmith/bestax-bulma/extras.css';

// 3. Third: Icon libraries (if using)
import '@fortawesome/fontawesome-free/css/all.min.css';

// 4. Last: Your custom styles
import './App.css';
Style Conflicts

If Bulma styles are being overridden unexpectedly, check your CSS import order. Bulma should be imported before your custom styles.

TypeScript Setup​

bestax-bulma includes TypeScript definitions. For the best experience:

Install Type Definitions​

pnpm add -D typescript @types/react @types/react-dom

TypeScript Configuration​

The tsconfig a Vite react-ts app starts with already works with bestax-bulma. If you write your own for a Vite app, these settings work on TypeScript 5 and 6:

tsconfig.json
{
  "compilerOptions": {
    "target": "ES2022",
    "lib": ["ES2022", "DOM", "DOM.Iterable"],
    "module": "ESNext",
    "moduleResolution": "bundler",
    "types": ["vite/client"],
    "allowImportingTsExtensions": true,
    "isolatedModules": true,
    "noEmit": true,
    "jsx": "react-jsx",
    "skipLibCheck": true,
    "strict": true,
    "noUnusedLocals": true,
    "noUnusedParameters": true,
    "noFallthroughCasesInSwitch": true
  },
  "include": ["src"]
}
  • "moduleResolution": "bundler" reads the package's exports map.
  • "types": ["vite/client"] declares CSS imports such as import '@allxsmith/bestax-bulma/bestax.css'. With another bundler, use its client types, or add a .d.ts file containing declare module '*.css';.
  • "allowImportingTsExtensions" lets main.tsx import ./App.tsx, as Vite's template does. It needs "noEmit", which suits an app whose bundler does the compiling.
  • "isolatedModules" makes tsc reject code that Vite's file-by-file compile can't handle, such as re-exporting a type without export type.

Bundle Size Optimization​

Optional tuning once you have bestax-bulma installed and rendering.

Tree Shaking​

bestax-bulma supports tree shaking. Always use named imports:

// ✅ Good - Only imports what you need
import { Button, Box, Title } from '@allxsmith/bestax-bulma';

Analyzing Bundle Size​

To analyze your bundle:

  1. Install bundle analyzer:
pnpm add -D webpack-bundle-analyzer
  1. Check what's included:
pnpm dlx webpack-bundle-analyzer stats.json

Expected Sizes​

  • bestax-bulma JS: ~65KB min+gzip for the entire library — with named imports, tree shaking means your app ships only the components it uses.
  • CSS (bestax.css, the combined Bulma + extras bundle): ~800KB minified on disk, ~82KB gzipped over the wire. CSS is not tree-shaken — the whole file ships regardless of which components you use. Leaner prebuilt variations and a modular Sass path exist; see CSS Variations for measured sizes and Optimizing CSS Size for the full trimming playbook.
  • PurgeCSS can strip unused selectors further, but it is not wired into any scaffold or template — Optimizing CSS Size covers the opt-in setup and the safelist patterns dynamic class names need to survive the purge.

Environment-Specific Setup​

Notes for specific environments, only relevant after the core install above is working.

Development & Production​

bestax.css is already compressed, so the same import works for both environments:

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

For production builds, consider enabling CSS purging (remove unused styles) or using a CDN for better caching.

Testing​

For testing environments:

// jest.setup.js
import '@testing-library/jest-dom';

// Mock CSS imports
jest.mock('@allxsmith/bestax-bulma/bestax.css', () => ({}));

Verification​

After installation, verify everything is working:

1. Check Package Installation​

npm list @allxsmith/bestax-bulma

2. Check Import Resolution​

Your IDE should autocomplete:

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

3. Check Styling​

Components should have Bulma styling applied. If components appear unstyled:

  • Verify bestax CSS is imported
  • Check the browser console for a stylesheet that failed to load
  • Ensure CSS import order is correct

4. Check Icons (if using)​

Icons should render correctly. If you see placeholder text instead of icons:

  • Verify icon library CSS is imported
  • Check the icon name matches the library's naming convention

Troubleshooting​

Common Issues​

Components are unstyled

  • Solution: Ensure bestax CSS is imported in your main file

Icons not showing

  • Solution: Import the icon library CSS and verify icon names

TypeScript errors

  • Solution: Install @types/react and @types/react-dom

Large bundle size

  • Solution: Use named imports and consider CSS purging

Mobile layout broken

  • Solution: Add viewport meta tag to your HTML

Getting Help​

Next Steps​

Now that you understand the installation options:

  1. Choose your toolchain → Toolchains Guide
  2. Explore components → Component Documentation
  3. Customize styling → Theming Guide
  4. Configure globally → Config Provider