beyond-tailwind-builder

CLI tool for building Tailwind CSS in BeyondJS modules.

Installation

Install as a development dependency in your BeyondJS project:

npm install beyond-tailwind-builder --save-dev

Note: This package is designed to be installed as a local development dependency, not globally. Use npx to run commands.

Usage

Initialize Tailwind in your project

Initialize Tailwind CSS in an existing BeyondJS project:

npx beyond-tailwind init

This command will:

1. Create the project structure (if it doesn't exist):

   • modules/ directory

2. Create configuration files (if they don't exist):

   • tailwind.config.mjs - Tailwind configuration (ES module format)
   • postcss.config.js - PostCSS configuration

3. Create the base/tailwind module with:

   • css/index.css - Base Tailwind directives
   • ts/tailwind-container.tsx - TailwindContainer component
   • module.json - Module configuration
   • tsconfig.json - TypeScript configuration

4. Register npm scripts in package.json (if they don't exist):

   • build:css - Compile all modules
   • watch:css - Watch for changes and recompile
   • build:css:local - Compile using local source code (for development)
   • watch:css:local - Watch using local source code (for development)

Note: The command is idempotent - it won't overwrite existing files or duplicate scripts.

Build all modules

You can build all modules using either:

# Direct command
npx beyond-tailwind build

# Or using the npm script (after running init)
npm run build:css

# Or using local source code (for development)
npm run build:css:local

Note:

• The base/tailwind module is compiled automatically
• Modules without source files or Tailwind classes are silently skipped
• Modules are compiled by scanning TS/TSX/JS/JSX files for Tailwind classes

Watch mode

You can watch for changes using either:

# Direct command
npx beyond-tailwind watch

# Or using the npm script (after running init)
npm run watch:css

# Or using local source code (for development)
npm run watch:css:local

Watches for changes in:

• css/index.css files (if present)
• TypeScript/JavaScript files (.ts, .tsx, .js, .jsx)

Automatically recompiles CSS when changes are detected.

List modules

npx beyond-tailwind list

Lists all modules found in the project.

Help

Get help and see all available commands:

npx beyond-tailwind help
# Or
npx beyond-tailwind --help
# Or
npx beyond-tailwind -h

Commands

• init - Initialize Tailwind in your BeyondJS project (creates structure, config files, base module, and npm scripts)
• build - Compile all modules with Tailwind CSS
• watch - Watch for changes and recompile automatically
• list - List all modules found in the project
• help - Show help message with all available commands

Requirements

• Node.js 18+
• A BeyondJS project (or run init to set up the structure)

Dependencies

The package includes the following dependencies:

• tailwindcss (^3.4.0)
• postcss (^8.4.35)
• autoprefixer (^10.4.17)

These are automatically installed when you install beyond-tailwind-builder. The init command will create the necessary configuration files (tailwind.config.mjs and postcss.config.js) automatically.

Module Structure

The tool identifies modules by looking for module.json files in the modules/ directory. Each module can have:

• css/index.css - Module-specific Tailwind styles (optional)
• ts/ or js/ directories - Source files with Tailwind classes (scanned automatically)
• module.json - Module configuration file (required)

Compilation behavior:

• If css/index.css exists, it will be compiled
• If css/index.css doesn't exist, the tool will scan all TS/TSX/JS/JSX files in ts/ and js/ directories for Tailwind classes
• Modules without source files or Tailwind classes are silently skipped
• The compiled output is generated in modules/[module-name]/scss/tailwind.scss

Base Module

The base/tailwind module (modules/base/tailwind) is special:

• It contains the base Tailwind directives (@tailwind base, @tailwind components, @tailwind utilities) in css/index.css
• It provides the TailwindContainer React component wrapper
• It is compiled automatically during build/watch operations
• Use npx beyond-tailwind init to create it if it doesn't exist

Important: All module views should wrap their content in TailwindContainer:

import { TailwindContainer } from 'your-package/base/tailwind';

export function View(): JSX.Element {
	return <TailwindContainer className='your-classes'>{/* Your content */}</TailwindContainer>;
}