create-bestax 3.1.3 → 3.2.0

package/README.md

@@ -1,6 +1,12 @@
 # create-bestax
 
-CLI tool for scaffolding new bestax-bulma projects.
+[![npm version](https://img.shields.io/npm/v/create-bestax.svg)](https://www.npmjs.com/package/create-bestax)
+[![npm downloads](https://img.shields.io/npm/dm/create-bestax.svg)](https://www.npmjs.com/package/create-bestax)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+The scaffolder for [`@allxsmith/bestax-bulma`](https://www.npmjs.com/package/@allxsmith/bestax-bulma) — spin up a Vite app pre-wired for the **Bulma v1** React component library in one command. Picks your framework (JS or TypeScript), CSS flavor, and icon library, and can drop in the bestax **AI skills** so an agent like Claude Code knows the library from the first prompt.
+
+Part of the [bestax monorepo](https://github.com/allxsmith/bestax) — see also [`@allxsmith/bestax-bulma`](https://www.npmjs.com/package/@allxsmith/bestax-bulma) for the components themselves.
 
 ## Usage
 
@@ -33,6 +39,8 @@ You'll be asked to:
 4. Select an icon library (Font Awesome, Material Icons, etc.)
 5. Choose whether to install the bestax AI skills into `.claude/skills/`
 
+Every prompt has a flag equivalent, so the whole flow is scriptable and CI-friendly — see the options below.
+
 ### Command Line Options
 
 ```bash
@@ -91,8 +99,8 @@ Available templates:
 
 Each template includes:
 
-- Pre-configured bestax-bulma integration
-- Bulma CSS v1.0.4
+- Pre-configured bestax-bulma integration (React 19)
+- The latest `@allxsmith/bestax-bulma`, which ships Bulma v1 automatically
 - Icon library support (Font Awesome, Material Design, etc.)
 - Sample components demonstrating library usage
 - Development and build scripts
@@ -100,10 +108,11 @@ Each template includes:
 ## For AI Tools
 
 Scaffolding for an AI agent? Pass `--skills` (or accept the prompt) to drop the bestax
-Agent Skills and a `CLAUDE.md` into the new project. The library also ships LLM-optimized
-docs:
+Agent Skills and a `CLAUDE.md` into the new project so Claude Code, Cursor, or Copilot
+build the bestax way from the start. The library also ships LLM-optimized docs:
 
 - [LLMs guide](https://bestax.io/docs/guides/llms) — using bestax with Claude Code, Cursor, Copilot
+- [Agent Skills](https://bestax.io/docs/skills/intro) — teach your agent the bestax conventions
 - [llms.txt](https://bestax.io/llms.txt) (curated index) · [llms-full.txt](https://bestax.io/llms-full.txt) (full docs)
 
 ## Development

package/dist/constants.d.ts

@@ -29,7 +29,12 @@ export declare const PROMPTS: {
     readonly SELECT_BULMA_FLAVOR: "Which Bulma CSS flavor would you like to use?";
     readonly INSTALL_SKILLS: "Install the bestax AI skills (.claude/skills) for Claude Code and other agents?";
 };
-export declare const CLAUDE_MD: (projectName: string) => string;
+export declare const CONFIG_PROVIDER_ICON_VALUES: Record<string, string>;
+export interface ClaudeMdOptions {
+    bulmaFlavor: string;
+    iconLibrary: string;
+}
+export declare const CLAUDE_MD: (projectName: string, { bulmaFlavor, iconLibrary }: ClaudeMdOptions) => string;
 export interface IconLibrary {
     name: string;
     display: string;

package/dist/constants.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"constants.d.ts","sourceRoot":"","sources":["../src/constants.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,MAAM,OAAO,CAAC;AAE1B,MAAM,WAAW,QAAQ;IACvB,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,OAAO,KAAK,CAAC,MAAM,CAAC;CAC5B;AAED,eAAO,MAAM,SAAS,EAAE,QAAQ,EAG/B,CAAC;AAEF,eAAO,MAAM,oBAAoB,kBAAkB,CAAC;AACpD,eAAO,MAAM,uBAAuB,MAAM,CAAC;AAC3C,eAAO,MAAM,kBAAkB,QAAsB,CAAC;AAEtD,eAAO,MAAM,QAAQ;;;;;wCAMQ,MAAM;uCAEP,MAAM;sCACP,MAAM;4CAEA,MAAM;;;;;CAM7B,CAAC;AAEX,eAAO,MAAM,OAAO;;;;;;CAOV,CAAC;AAIX,eAAO,MAAM,SAAS,GAAI,aAAa,MAAM,KAAG,MAsB/C,CAAC;AAEF,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,OAAO,KAAK,CAAC,MAAM,CAAC;IAC3B,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,iBAAiB,CAAC,EAAE,MAAM,CAAC;CAC5B;AAED,eAAO,MAAM,cAAc,EAAE,WAAW,EAyCvC,CAAC;AAEF,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,KAAK,EAAE,OAAO,KAAK,CAAC,MAAM,CAAC;IAC3B,eAAe,EAAE,MAAM,CAAC;IACxB,WAAW,CAAC,EAAE,OAAO,CAAC;CACvB;AAED,eAAO,MAAM,aAAa,EAAE,WAAW,EA0CtC,CAAC"}
+{"version":3,"file":"constants.d.ts","sourceRoot":"","sources":["../src/constants.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,MAAM,OAAO,CAAC;AAE1B,MAAM,WAAW,QAAQ;IACvB,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,OAAO,KAAK,CAAC,MAAM,CAAC;CAC5B;AAED,eAAO,MAAM,SAAS,EAAE,QAAQ,EAG/B,CAAC;AAEF,eAAO,MAAM,oBAAoB,kBAAkB,CAAC;AACpD,eAAO,MAAM,uBAAuB,MAAM,CAAC;AAC3C,eAAO,MAAM,kBAAkB,QAAsB,CAAC;AAEtD,eAAO,MAAM,QAAQ;;;;;wCAMQ,MAAM;uCAEP,MAAM;sCACP,MAAM;4CAEA,MAAM;;;;;CAM7B,CAAC;AAEX,eAAO,MAAM,OAAO;;;;;;CAOV,CAAC;AAOX,eAAO,MAAM,2BAA2B,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAK9D,CAAC;AAKF,MAAM,WAAW,eAAe;IAC9B,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,CAAC;CACrB;AAED,eAAO,MAAM,SAAS,GACpB,aAAa,MAAM,EACnB,8BAA8B,eAAe,KAC5C,MA8DF,CAAC;AAEF,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,OAAO,KAAK,CAAC,MAAM,CAAC;IAC3B,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,iBAAiB,CAAC,EAAE,MAAM,CAAC;CAC5B;AAED,eAAO,MAAM,cAAc,EAAE,WAAW,EAyCvC,CAAC;AAEF,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,KAAK,EAAE,OAAO,KAAK,CAAC,MAAM,CAAC;IAC3B,eAAe,EAAE,MAAM,CAAC;IACxB,WAAW,CAAC,EAAE,OAAO,CAAC;CACvB;AAED,eAAO,MAAM,aAAa,EAAE,WAAW,EA0CtC,CAAC"}

package/dist/constants.js

@@ -27,13 +27,57 @@ export const PROMPTS = {
     SELECT_BULMA_FLAVOR: 'Which Bulma CSS flavor would you like to use?',
     INSTALL_SKILLS: 'Install the bestax AI skills (.claude/skills) for Claude Code and other agents?',
 };
-// Minimal CLAUDE.md scaffolded alongside the skills so an AI agent knows the
-// stack and where the skills live.
-export const CLAUDE_MD = (projectName) => `# ${projectName}
+// Icon libraries that require a `ConfigProvider iconLibrary` wrapper, mapped
+// to the exact prop value the scaffolder writes into main.tsx/jsx ('none' and
+// 'fontawesome' are the defaults and need no provider). Shared with
+// project-creator.setupConfigProvider AND the CLAUDE_MD template below so the
+// generated docs can never drift from the generated code.
+export const CONFIG_PROVIDER_ICON_VALUES = {
+    mdi: 'mdi',
+    ionicons: 'ion',
+    'material-icons': 'material-icons',
+    'material-symbols': 'material-symbols',
+};
+export const CLAUDE_MD = (projectName, { bulmaFlavor, iconLibrary }) => {
+    const flavor = BULMA_FLAVORS.find(f => f.name === bulmaFlavor);
+    const icon = ICON_LIBRARIES.find(lib => lib.name === iconLibrary);
+    const setupLines = [
+        `- Bulma flavor: **${bulmaFlavor}** — the app imports **prebuilt** CSS` +
+            (flavor ? ` (\`${flavor.importStatement.trim()}\`)` : '') +
+            `; there is no Sass pipeline unless you add \`sass\`.`,
+    ];
+    if (flavor?.needsPrefix) {
+        setupLines.push(`- Every Bulma class carries the \`bestax-\` prefix and the app is wrapped in ` +
+            `\`<ConfigProvider classPrefix="bestax-">\` — custom CSS selectors must match the prefix.`);
+    }
+    const providerIconValue = CONFIG_PROVIDER_ICON_VALUES[iconLibrary];
+    setupLines.push(iconLibrary === 'none'
+        ? `- No icon library is installed — add one before using \`<Icon>\` ` +
+            `(https://bestax.io/docs/api/elements/icon).`
+        : `- Icon library: **${icon?.display ?? iconLibrary}** — use \`<Icon name="..." />\`.` +
+            (providerIconValue
+                ? ` The app is already wrapped in \`<ConfigProvider iconLibrary="${providerIconValue}">\` ` +
+                    `— extend that provider rather than adding a second one.`
+                : ''));
+    return `# ${projectName}
 
 This app is built with [\`@allxsmith/bestax-bulma\`](https://bestax.io) — React components for
 Bulma 1.x.
 
+## This app's setup
+
+${setupLines.join('\n')}
+
+## House style
+
+- Never inline \`style={{}}\` — use the helper props every component accepts (\`m*\`/\`p*\`
+  spacing, \`textColor\`/\`bgColor\`, \`display="flex"\`, \`flexDirection\`, \`alignItems\`).
+  Flex layouts have no \`gap\` helper — space children with margins (\`Grid\` has a real
+  \`gap\` prop and \`Columns\` has \`gapSize\`, so prefer those there).
+- Compose existing components before writing custom CSS; theme via \`Theme\` and \`--bulma-*\`
+  variables, never hardcoded colors.
+- There is no test runner or Storybook in this app — don't assume one.
+
 ## AI skills
 
 \`.claude/skills/\` contains Agent Skills that teach Claude how to build with this library. They load
@@ -52,6 +96,7 @@ Prefer the library's components and these skills over hand-written Bulma markup
 - LLM-ready docs: https://bestax.io/llms.txt (curated index) and https://bestax.io/llms-full.txt
 - Using bestax with AI tools: https://bestax.io/docs/guides/llms
 `;
+};
 export const ICON_LIBRARIES = [
     {
         name: 'none',

package/dist/project-creator.d.ts

@@ -1,3 +1,4 @@
+import { type ClaudeMdOptions } from './constants.js';
 export interface ProjectConfig {
     projectName: string;
     template: string;
@@ -19,7 +20,7 @@ export declare class ProjectCreator {
     checkExistingDirectory(targetPath: string, targetDir: string): Promise<boolean>;
     getTemplatePath(template: string): string;
     copyTemplate(template: string, targetPath: string): Promise<void>;
-    setupSkills(targetPath: string, projectName: string): Promise<void>;
+    setupSkills(targetPath: string, projectName: string, options: ClaudeMdOptions): Promise<void>;
     setupBulmaFlavor(targetPath: string, bulmaFlavor: string, template: string): Promise<void>;
     private getIconName;
     private getIconProps;

package/dist/project-creator.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"project-creator.d.ts","sourceRoot":"","sources":["../src/project-creator.ts"],"names":[],"mappings":"AAoCA,MAAM,WAAW,aAAa;IAC5B,WAAW,EAAE,MAAM,CAAC;IACpB,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,MAAM,CAAC;IACnB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,GAAG,CAAC,EAAE,OAAO,CAAC;CACf;AAED,qBAAa,cAAc;IACzB,OAAO,CAAC,YAAY,CAAS;gBAEjB,YAAY,CAAC,EAAE,MAAM;IAI3B,cAAc,CAAC,UAAU,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC;IAa3D,sBAAsB,CAC1B,UAAU,EAAE,MAAM,EAClB,SAAS,EAAE,MAAM,GAChB,OAAO,CAAC,OAAO,CAAC;IAkBnB,eAAe,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM;IAInC,YAAY,CAAC,QAAQ,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAMjE,WAAW,CAAC,UAAU,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAiBnE,gBAAgB,CACpB,UAAU,EAAE,MAAM,EAClB,WAAW,EAAE,MAAM,EACnB,QAAQ,EAAE,MAAM,GACf,OAAO,CAAC,IAAI,CAAC;IAmDhB,OAAO,CAAC,WAAW;IA2BnB,OAAO,CAAC,YAAY;IAYd,gBAAgB,CACpB,UAAU,EAAE,MAAM,EAClB,WAAW,EAAE,MAAM,EACnB,QAAQ,EAAE,MAAM,GACf,OAAO,CAAC,IAAI,CAAC;IA2IV,mBAAmB,CACvB,UAAU,EAAE,MAAM,EAClB,WAAW,EAAE,MAAM,EACnB,WAAW,EAAE,MAAM,EACnB,QAAQ,EAAE,MAAM,GACf,OAAO,CAAC,IAAI,CAAC;IAwEV,MAAM,CAAC,UAAU,CAAC,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC;CAqIvE"}
+{"version":3,"file":"project-creator.d.ts","sourceRoot":"","sources":["../src/project-creator.ts"],"names":[],"mappings":"AA2BA,OAAO,EAML,KAAK,eAAe,EACrB,MAAM,gBAAgB,CAAC;AAIxB,MAAM,WAAW,aAAa;IAC5B,WAAW,EAAE,MAAM,CAAC;IACpB,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,MAAM,CAAC;IACnB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,GAAG,CAAC,EAAE,OAAO,CAAC;CACf;AAED,qBAAa,cAAc;IACzB,OAAO,CAAC,YAAY,CAAS;gBAEjB,YAAY,CAAC,EAAE,MAAM;IAI3B,cAAc,CAAC,UAAU,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC;IAa3D,sBAAsB,CAC1B,UAAU,EAAE,MAAM,EAClB,SAAS,EAAE,MAAM,GAChB,OAAO,CAAC,OAAO,CAAC;IAkBnB,eAAe,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM;IAInC,YAAY,CAAC,QAAQ,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAMjE,WAAW,CACf,UAAU,EAAE,MAAM,EAClB,WAAW,EAAE,MAAM,EACnB,OAAO,EAAE,eAAe,GACvB,OAAO,CAAC,IAAI,CAAC;IAiBV,gBAAgB,CACpB,UAAU,EAAE,MAAM,EAClB,WAAW,EAAE,MAAM,EACnB,QAAQ,EAAE,MAAM,GACf,OAAO,CAAC,IAAI,CAAC;IAmDhB,OAAO,CAAC,WAAW;IA2BnB,OAAO,CAAC,YAAY;IAYd,gBAAgB,CACpB,UAAU,EAAE,MAAM,EAClB,WAAW,EAAE,MAAM,EACnB,QAAQ,EAAE,MAAM,GACf,OAAO,CAAC,IAAI,CAAC;IA2IV,mBAAmB,CACvB,UAAU,EAAE,MAAM,EAClB,WAAW,EAAE,MAAM,EACnB,WAAW,EAAE,MAAM,EACnB,QAAQ,EAAE,MAAM,GACf,OAAO,CAAC,IAAI,CAAC;IAmEV,MAAM,CAAC,UAAU,CAAC,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC;CAwIvE"}

package/dist/project-creator.js

@@ -6,7 +6,7 @@ import { checkDirectoryExists, isDirectoryEmpty, emptyDirectory, ensureDirectory
 import { promptProjectName, promptOverwriteDirectory, promptTemplate, promptIconLibrary, promptBulmaFlavor, promptInstallSkills, } from './prompts.js';
 import { displayHeader, displaySuccess, displayError, displayCancelled, } from './display.js';
 import { validateProjectName } from './validators.js';
-import { MESSAGES, ICON_LIBRARIES, BULMA_FLAVORS, CLAUDE_MD, } from './constants.js';
+import { MESSAGES, ICON_LIBRARIES, BULMA_FLAVORS, CLAUDE_MD, CONFIG_PROVIDER_ICON_VALUES, } from './constants.js';
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 export class ProjectCreator {
     templatesDir;
@@ -45,14 +45,14 @@ export class ProjectCreator {
         await ensureDirectory(targetPath);
         await copyDirectory(templatePath, targetPath);
     }
-    async setupSkills(targetPath, projectName) {
+    async setupSkills(targetPath, projectName, options) {
         const skillsSrc = path.join(this.templatesDir, 'skills');
         if (!(await checkDirectoryExists(skillsSrc))) {
             console.log(chalk.yellow('  Skipping skills — bundle not found in this build.'));
             return;
         }
         await fs.copy(skillsSrc, path.join(targetPath, '.claude', 'skills'));
-        await fs.writeFile(path.join(targetPath, 'CLAUDE.md'), CLAUDE_MD(projectName));
+        await fs.writeFile(path.join(targetPath, 'CLAUDE.md'), CLAUDE_MD(projectName, options));
         console.log(chalk.green(MESSAGES.SKILLS_ADDED));
     }
     async setupBulmaFlavor(targetPath, bulmaFlavor, template) {
@@ -264,14 +264,9 @@ export class ProjectCreator {
                 configProps.push('classPrefix="bestax-"');
             }
             if (needsIconLibrary) {
-                // Map the icon library name to the correct value for ConfigProvider
-                const iconLibraryMap = {
-                    mdi: 'mdi',
-                    ionicons: 'ion',
-                    'material-icons': 'material-icons',
-                    'material-symbols': 'material-symbols',
-                };
-                const iconLibraryValue = iconLibraryMap[iconLibrary];
+                // Shared with the CLAUDE_MD template so the generated docs always
+                // name the same provider value the scaffolder writes here.
+                const iconLibraryValue = CONFIG_PROVIDER_ICON_VALUES[iconLibrary];
                 if (iconLibraryValue) {
                     configProps.push(`iconLibrary="${iconLibraryValue}"`);
                 }
@@ -395,7 +390,10 @@ export class ProjectCreator {
             await this.setupIconLibrary(targetPath, iconLibrary, template);
             await this.setupConfigProvider(targetPath, bulmaFlavor, iconLibrary, template);
             if (installSkills) {
-                await this.setupSkills(targetPath, projectName);
+                await this.setupSkills(targetPath, projectName, {
+                    bulmaFlavor,
+                    iconLibrary,
+                });
             }
             displaySuccess(targetDir);
         }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-bestax",
-  "version": "3.1.3",
+  "version": "3.2.0",
   "description": "Create a new bestax-bulma project",
   "type": "module",
   "bin": {