CLI & integrations

Beam ships a CLI, bundler plugins, a native Node binding, and agent-native surfaces - all backed by the same Rust compiler.

CLI

Install globally or run via npx beam <command>.

Command	Purpose
`beam init`	Scaffold config, install packages, wire the plugin (`--template vite`)
`beam build`	Scan files, compile class strings, write CSS
`beam dev`	Watch mode - rebuild on source/config change
`beam check`	Validate every class string compiles; structured report, CI-friendly
`beam explain`	Show how a class string parses and compiles

terminal

beam check --config ./beam.config.ts --content ./src --format json

output

{
  "valid": true,
  "class_string_count": 42,
  "errors": [],
  "warnings": []
}

Exit code 0 = clean, 1 = errors found.

Vite plugin

Runs beam build during the Vite build, injects the CSS via a <style data-beamcss> tag, and supports HMR with incremental rebuilds.

vite.config.ts

import { beamcss } from '@beamcss/vite'

export default {
  plugins: [
    beamcss({
      config: './beam.config.ts',
      content: ['./src'],
    }),
  ],
}

PostCSS plugin

postcss.config.js

module.exports = {
  plugins: {
    '@beamcss/postcss': {
      config: './beam.config.ts',
      content: ['./src'],
    },
  },
}

Native Node binding

The beamcss package ships a prebuilt napi-rs .node addon - the same approach as Lightning CSS and Tailwind Oxide. compile and explain are synchronous, thread-safe, and stateless.

Node

import { compile, explain } from 'beamcss'

const result = compile(config, [
  'flex direction-column align-center gap-4 hover:(bg-accent text-on-accent)',
])
console.log(result.css)    // full CSS string
console.log(result.errors) // CompileMessage[] - { class_name, message }

Agent-native surfaces

Beam is designed to work well with AI coding agents.

beam check as a preflight gate - run before showing AI-generated UI; a clean result means every class resolves against the tokens.
beam explain for debugging - returns the full parse tree (variants, atoms, selectors, declarations, layers) as structured JSON.
@beamcss/mcp - exposes compile, explain, and check as MCP tools, callable directly via tool use.
Tailwind → Beam codemod and llms.txt / llms-full.txt for machine-readable docs.

Cascade layers

All output is emitted under named @layer rules for predictable specificity - you never fight !important. The order is fixed:

CSS

@layer beam.reset, beam.tokens, beam.base, beam.utilities;

Every utility emits exactly one rule globally - gap-4 appears once regardless of how many elements reference it.