prettier-plugin-bootstrap 0.2.0 → 0.3.0

package/README.md

@@ -9,6 +9,13 @@ A [Prettier](https://prettier.io/) plugin that automatically sorts Bootstrap CSS
 
 Works with **HTML**, **JSX/TSX**, **Vue**, **Angular**, **Svelte**, and **Astro** templates.
 
+## Why?
+
+- **Consistency** — Every file in your project uses the same class order, regardless of who wrote it.
+- **Smaller diffs** — Sorted classes eliminate noisy reordering in pull requests.
+- **Readability** — Classes follow Bootstrap's architecture (layout → components → utilities), making it easier to scan what an element does.
+- **Zero config** — Just add the plugin and format. No ESLint rules to configure, no manual sorting.
+
 ## Installation
 
 ```bash
@@ -63,21 +70,87 @@ Unknown classes are preserved in their original relative order and placed after
 
 ## Options
 
-| Option                | Type       | Default | Description                                                                |
-| --------------------- | ---------- | ------- | -------------------------------------------------------------------------- |
-| `bootstrapAttributes` | `string[]` | `[]`    | Additional HTML attributes to sort (beyond `class` and `className`)        |
-| `bootstrapFunctions`  | `string[]` | `[]`    | Function names whose arguments are class lists (e.g. `clsx`, `classNames`) |
+| Option                        | Type       | Default | Description                                                                                                          |
+| ----------------------------- | ---------- | ------- | -------------------------------------------------------------------------------------------------------------------- |
+| `bootstrapAttributes`         | `string[]` | `[]`    | Additional HTML attributes to sort (beyond `class` and `className`). Supports regex patterns (e.g. `/^data-class/`). |
+| `bootstrapFunctions`          | `string[]` | `[]`    | Function names whose arguments are class lists (e.g. `clsx`, `classNames`)                                           |
+| `bootstrapPreserveWhitespace` | `boolean`  | `false` | Preserve original whitespace between classes instead of normalizing to single spaces                                 |
+| `bootstrapPreserveDuplicates` | `boolean`  | `true`  | Keep duplicate class names. Set to `false` to remove duplicates                                                      |
+| `bootstrapVersion`            | `int`      | `5`     | Bootstrap version (for future version-specific sorting rules)                                                        |
 
 ### Example
 
 ```json
 {
   "plugins": ["prettier-plugin-bootstrap"],
-  "bootstrapAttributes": ["ngClass", "v-bind:class"],
+  "bootstrapAttributes": ["ngClass", "v-bind:class", "/^data-class/"],
   "bootstrapFunctions": ["clsx", "cn", "classNames"]
 }
 ```
 
+### TypeScript Configuration
+
+For type-safe configuration, use JSDoc annotations:
+
+```js
+/** @type {import('prettier-plugin-bootstrap').BootstrapPluginOptions} */
+const config = {
+  plugins: ['prettier-plugin-bootstrap'],
+  bootstrapAttributes: ['ngClass'],
+  bootstrapFunctions: ['clsx', 'cn'],
+  bootstrapPreserveDuplicates: false,
+}
+
+export default config
+```
+
+### Regex Attributes
+
+You can use regex patterns in `bootstrapAttributes` to match dynamic attribute names:
+
+```json
+{
+  "bootstrapAttributes": ["/^data-class/", "/Class$/"]
+}
+```
+
+Patterns must be wrapped in forward slashes. Optional flags (`i`, `g`, etc.) are supported: `/^data-class/i`.
+
+### File-Level Ignore
+
+Add a comment at the top of a file to skip Bootstrap class sorting for the entire file:
+
+```html
+<!-- prettier-bootstrap-ignore -->
+<div class="mt-3 container">Will not be sorted</div>
+```
+
+For JS/TS files:
+
+```js
+// prettier-bootstrap-ignore
+export default () => <div className="mt-3 container">Not sorted</div>
+```
+
+Or block comment style:
+
+```js
+/* prettier-bootstrap-ignore */
+```
+
+## Public Sorting API
+
+For programmatic use (linters, codemods, build tools), import the sorter directly:
+
+```js
+import { createSorter } from 'prettier-plugin-bootstrap/sorter'
+
+const sorter = createSorter({ preserveDuplicates: false })
+
+sorter.sort('mt-3 container p-2') // "container mt-3 p-2"
+sorter.sortClasses(['mt-3', 'container']) // ["container", "mt-3"]
+```
+
 ## Supported Parsers
 
 - `html` — HTML files
@@ -108,6 +181,28 @@ When using with `prettier-plugin-astro`, list `prettier-plugin-bootstrap` **afte
 }
 ```
 
+## Plugin Compatibility
+
+This plugin works alongside other Prettier plugins. Load order matters — `prettier-plugin-bootstrap` should come **last** so it can wrap the parsers registered by other plugins.
+
+| Plugin                                  | Compatible | Load Order                               |
+| --------------------------------------- | ---------- | ---------------------------------------- |
+| `prettier-plugin-svelte`                | Yes        | svelte first                             |
+| `prettier-plugin-astro`                 | Yes        | astro first                              |
+| `prettier-plugin-tailwindcss`           | N/A        | Use one or the other (both sort classes) |
+| `prettier-plugin-organize-imports`      | Yes        | Any order                                |
+| `@trivago/prettier-plugin-sort-imports` | Yes        | Any order                                |
+
+## FAQ
+
+### Does class sorting affect line wrapping?
+
+Yes. Reordering classes changes the string length, which may cause Prettier to wrap lines differently based on your `printWidth` setting. This is expected — the formatting is still deterministic and consistent.
+
+### Can I use this with Tailwind CSS?
+
+This plugin is designed specifically for Bootstrap's class system. If you use Tailwind CSS, use `prettier-plugin-tailwindcss` instead. They should not be used together as they have conflicting sort orders.
+
 ## Development
 
 ```bash
@@ -121,6 +216,7 @@ pnpm run typecheck
 
 - Prettier >= 3.0.0
 - Node.js >= 20
+- Bootstrap 5 (class order)
 
 ## License
 

package/dist/class-order-BYtmS-1R.d.mts

@@ -0,0 +1,23 @@
+import { Options } from "prettier";
+
+//#region src/types.d.ts
+interface SortOptions {
+  preserveWhitespace?: boolean;
+  preserveDuplicates?: boolean;
+}
+interface BootstrapPluginOptions extends Options {
+  bootstrapAttributes?: string[];
+  bootstrapFunctions?: string[];
+  bootstrapPreserveWhitespace?: boolean;
+  bootstrapPreserveDuplicates?: boolean;
+  bootstrapVersion?: number;
+}
+type SortKey = [categoryIndex: number, breakpointIndex: number];
+//#endregion
+//#region src/class-order.d.ts
+declare const BREAKPOINTS: readonly ["sm", "md", "lg", "xl", "xxl"];
+declare const CLASS_ORDER: readonly string[];
+declare function classKey(className: string): SortKey;
+declare function sortClasses(classes: string[]): string[];
+//#endregion
+export { BootstrapPluginOptions as a, sortClasses as i, CLASS_ORDER as n, SortOptions as o, classKey as r, BREAKPOINTS as t };

package/dist/class-order-UKlp_Ej7.d.cts

@@ -0,0 +1,23 @@
+import { Options } from "prettier";
+
+//#region src/types.d.ts
+interface SortOptions {
+  preserveWhitespace?: boolean;
+  preserveDuplicates?: boolean;
+}
+interface BootstrapPluginOptions extends Options {
+  bootstrapAttributes?: string[];
+  bootstrapFunctions?: string[];
+  bootstrapPreserveWhitespace?: boolean;
+  bootstrapPreserveDuplicates?: boolean;
+  bootstrapVersion?: number;
+}
+type SortKey = [categoryIndex: number, breakpointIndex: number];
+//#endregion
+//#region src/class-order.d.ts
+declare const BREAKPOINTS: readonly ["sm", "md", "lg", "xl", "xxl"];
+declare const CLASS_ORDER: readonly string[];
+declare function classKey(className: string): SortKey;
+declare function sortClasses(classes: string[]): string[];
+//#endregion
+export { BootstrapPluginOptions as a, sortClasses as i, CLASS_ORDER as n, SortOptions as o, classKey as r, BREAKPOINTS as t };

package/dist/index.cjs

@@ -0,0 +1,251 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const require_sorting = require("./sorting-B-0731KP.cjs");
+//#region src/traversal.ts
+const AST_KEYS = [
+	"program",
+	"expression",
+	"left",
+	"right",
+	"argument",
+	"callee",
+	"object",
+	"property",
+	"consequent",
+	"alternate",
+	"init",
+	"test",
+	"update",
+	"declaration",
+	"declarations",
+	"openingElement",
+	"closingElement",
+	"attributes",
+	"value",
+	"elements",
+	"properties",
+	"arguments"
+];
+function walk(node, visitor) {
+	if (!node) return;
+	visitor(node);
+	if (Array.isArray(node.children)) for (const child of node.children) walk(child, visitor);
+	if (node.body) {
+		if (Array.isArray(node.body)) for (const child of node.body) walk(child, visitor);
+		else if (typeof node.body === "object") walk(node.body, visitor);
+	}
+	for (const key of AST_KEYS) {
+		const child = node[key];
+		if (child) {
+			if (Array.isArray(child)) {
+				for (const item of child) if (item && typeof item === "object") walk(item, visitor);
+			} else if (typeof child === "object") walk(child, visitor);
+		}
+	}
+}
+function sortStringNode(node, sortOptions) {
+	if (!node) return;
+	if (node.type === "StringLiteral") {
+		const sorted = require_sorting.sortClassString(node.value, sortOptions);
+		node.value = sorted;
+		if (node.extra) {
+			node.extra.rawValue = sorted;
+			node.extra.raw = `"${sorted}"`;
+		}
+		return;
+	}
+	if (node.type === "Literal" && typeof node.value === "string") {
+		const sorted = require_sorting.sortClassString(node.value, sortOptions);
+		node.value = sorted;
+		if (node.raw) {
+			const quote = node.raw[0];
+			node.raw = `${quote}${sorted}${quote}`;
+		}
+		return;
+	}
+	if (node.type === "TemplateLiteral" && (!node.expressions || node.expressions.length === 0)) {
+		for (const quasi of node.quasis) if (quasi.value && typeof quasi.value.raw === "string") {
+			const sorted = require_sorting.sortClassString(quasi.value.raw, sortOptions);
+			quasi.value.raw = sorted;
+			quasi.value.cooked = sorted;
+		}
+	}
+}
+function processHtmlAst(ast, attrMatcher, _targetFunctions, sortOptions) {
+	const matchAttr = typeof attrMatcher === "function" ? attrMatcher : (name) => attrMatcher.includes(name);
+	walk(ast, (node) => {
+		if (node.attrs && Array.isArray(node.attrs)) {
+			for (const attr of node.attrs) if (matchAttr(attr.name) && typeof attr.value === "string") attr.value = require_sorting.sortClassString(attr.value, sortOptions);
+		}
+		if (node.attributes && Array.isArray(node.attributes)) {
+			for (const attr of node.attributes) if (matchAttr(attr.name || attr.key && attr.key.value) && attr.value) {
+				if (typeof attr.value === "string") {
+					if (attr.kind && attr.kind !== "quoted") continue;
+					if (attr.value.includes("${")) continue;
+					attr.value = require_sorting.sortClassString(attr.value, sortOptions);
+				} else if (attr.value && typeof attr.value.value === "string") {
+					if (attr.value.value.includes("${")) continue;
+					attr.value.value = require_sorting.sortClassString(attr.value.value, sortOptions);
+				}
+			}
+		}
+	});
+	return ast;
+}
+function processJsxAst(ast, attrMatcher, targetFunctions = [], sortOptions) {
+	const matchAttr = typeof attrMatcher === "function" ? attrMatcher : (name) => attrMatcher.includes(name);
+	const functionSet = new Set(targetFunctions);
+	walk(ast, (node) => {
+		if (node.type === "JSXAttribute" || node.type === "JSXSpreadAttribute") {
+			if (matchAttr(node.name && (node.name.name || node.name.value)) && node.value) {
+				if (node.value.type === "StringLiteral" || node.value.type === "Literal") {
+					const sorted = require_sorting.sortClassString(node.value.value, sortOptions);
+					node.value.value = sorted;
+					if (node.value.extra) {
+						node.value.extra.rawValue = sorted;
+						node.value.extra.raw = `"${sorted}"`;
+					}
+					if (node.value.raw) {
+						const quote = node.value.raw[0];
+						node.value.raw = `${quote}${sorted}${quote}`;
+					}
+				}
+			}
+		}
+		if (node.type === "CallExpression" && functionSet.size > 0) {
+			const callee = node.callee;
+			if (callee && callee.type === "Identifier" && functionSet.has(callee.name)) for (const arg of node.arguments || []) sortStringNode(arg, sortOptions);
+		}
+	});
+	return ast;
+}
+function walkSvelte(node, visitor) {
+	if (!node) return;
+	visitor(node);
+	if (node.fragment && Array.isArray(node.fragment.nodes)) for (const child of node.fragment.nodes) walkSvelte(child, visitor);
+	if (Array.isArray(node.children)) for (const child of node.children) walkSvelte(child, visitor);
+}
+function processSvelteAst(ast, attrMatcher, _targetFunctions, sortOptions) {
+	const matchAttr = typeof attrMatcher === "function" ? attrMatcher : (name) => attrMatcher.includes(name);
+	walkSvelte(ast, (node) => {
+		if (!node.attributes || !Array.isArray(node.attributes)) return;
+		for (const attr of node.attributes) {
+			if (attr.type !== "Attribute") continue;
+			if (!matchAttr(attr.name)) continue;
+			if (Array.isArray(attr.value)) {
+				for (const item of attr.value) if (item.type === "Text" && typeof item.data === "string") {
+					const sorted = require_sorting.sortClassString(item.data, sortOptions);
+					item.data = sorted;
+					if (typeof item.raw === "string") item.raw = sorted;
+				}
+			}
+		}
+	});
+	return ast;
+}
+//#endregion
+//#region src/index.ts
+const DEFAULT_ATTRIBUTES = ["class", "className"];
+const IGNORE_RE = /(?:<!--\s*prettier-bootstrap-ignore\s*-->|\/\/\s*prettier-bootstrap-ignore|\/\*\s*prettier-bootstrap-ignore\s*\*\/)/;
+const options = {
+	bootstrapAttributes: {
+		type: "string",
+		array: true,
+		default: [{ value: [] }],
+		category: "Bootstrap",
+		description: "Additional HTML attributes containing Bootstrap class lists to sort."
+	},
+	bootstrapFunctions: {
+		type: "string",
+		array: true,
+		default: [{ value: [] }],
+		category: "Bootstrap",
+		description: "Function names whose arguments are Bootstrap class lists (e.g. clsx, classNames)."
+	},
+	bootstrapPreserveWhitespace: {
+		type: "boolean",
+		default: false,
+		category: "Bootstrap",
+		description: "Preserve original whitespace between classes instead of normalizing to single spaces."
+	},
+	bootstrapPreserveDuplicates: {
+		type: "boolean",
+		default: true,
+		category: "Bootstrap",
+		description: "Keep duplicate class names. Set to false to remove duplicates."
+	},
+	bootstrapVersion: {
+		type: "int",
+		default: 5,
+		category: "Bootstrap",
+		description: "Bootstrap version (for future version-specific sorting rules)."
+	}
+};
+function buildAttrMatcher(allAttrs) {
+	const plainAttrs = [];
+	const regexAttrs = [];
+	for (const attr of allAttrs) {
+		const m = attr.match(/^\/(.+)\/([gimsuy]*)$/);
+		if (m) regexAttrs.push(new RegExp(m[1], m[2]));
+		else plainAttrs.push(attr);
+	}
+	return (name) => plainAttrs.includes(name) || regexAttrs.some((re) => re.test(name));
+}
+function createParserWrapper(parserName, processAst, astFormat) {
+	const wrapper = {
+		astFormat,
+		locStart(node) {
+			return node.range?.[0] ?? node.start ?? node.sourceSpan?.start?.offset ?? 0;
+		},
+		locEnd(node) {
+			return node.range?.[1] ?? node.end ?? node.sourceSpan?.end?.offset ?? 0;
+		},
+		async parse(text, options) {
+			const plugins = options.plugins || [];
+			let originalParser = null;
+			for (const plugin of plugins) {
+				if (typeof plugin !== "object" || !plugin.parsers) continue;
+				const candidate = plugin.parsers[parserName];
+				if (!candidate) continue;
+				let resolved = candidate;
+				if (typeof candidate === "function" && !candidate.parse) resolved = await candidate();
+				if (resolved && typeof resolved.parse === "function" && resolved.parse !== wrapper.parse) {
+					originalParser = resolved;
+					break;
+				}
+			}
+			if (!originalParser) throw new Error(`prettier-plugin-bootstrap: could not find the "${parserName}" parser. Make sure Prettier and the relevant parser plugin are installed.`);
+			if (originalParser.locStart) wrapper.locStart = originalParser.locStart;
+			if (originalParser.locEnd) wrapper.locEnd = originalParser.locEnd;
+			if (originalParser.astFormat) wrapper.astFormat = originalParser.astFormat;
+			const ast = await originalParser.parse(text, options);
+			if (IGNORE_RE.test(text.slice(0, 1500))) return ast;
+			const targetAttrs = [...DEFAULT_ATTRIBUTES, ...options.bootstrapAttributes || []];
+			const targetFunctions = options.bootstrapFunctions || [];
+			return processAst(ast, buildAttrMatcher(targetAttrs), targetFunctions, {
+				preserveWhitespace: options.bootstrapPreserveWhitespace ?? false,
+				preserveDuplicates: options.bootstrapPreserveDuplicates ?? true
+			});
+		}
+	};
+	return wrapper;
+}
+const parsers = {
+	html: createParserWrapper("html", processHtmlAst, "html"),
+	vue: createParserWrapper("vue", processHtmlAst, "html"),
+	angular: createParserWrapper("angular", processHtmlAst, "html"),
+	babel: createParserWrapper("babel", processJsxAst, "estree"),
+	"babel-ts": createParserWrapper("babel-ts", processJsxAst, "estree"),
+	typescript: createParserWrapper("typescript", processJsxAst, "estree"),
+	acorn: createParserWrapper("acorn", processJsxAst, "estree"),
+	meriyah: createParserWrapper("meriyah", processJsxAst, "estree"),
+	astro: createParserWrapper("astro", processHtmlAst, "astro"),
+	svelte: createParserWrapper("svelte", processSvelteAst, "svelte-ast")
+};
+//#endregion
+exports.BREAKPOINTS = require_sorting.BREAKPOINTS;
+exports.CLASS_ORDER = require_sorting.CLASS_ORDER;
+exports.buildAttrMatcher = buildAttrMatcher;
+exports.classKey = require_sorting.classKey;
+exports.options = options;
+exports.parsers = parsers;
+exports.sortClasses = require_sorting.sortClasses;

package/dist/index.d.cts

@@ -0,0 +1,46 @@
+import { a as BootstrapPluginOptions, i as sortClasses, n as CLASS_ORDER, o as SortOptions, r as classKey, t as BREAKPOINTS } from "./class-order-UKlp_Ej7.cjs";
+import { Parser } from "prettier";
+
+//#region src/index.d.ts
+declare const options: {
+  bootstrapAttributes: {
+    type: "string";
+    array: true;
+    default: {
+      value: never[];
+    }[];
+    category: string;
+    description: string;
+  };
+  bootstrapFunctions: {
+    type: "string";
+    array: true;
+    default: {
+      value: never[];
+    }[];
+    category: string;
+    description: string;
+  };
+  bootstrapPreserveWhitespace: {
+    type: "boolean";
+    default: boolean;
+    category: string;
+    description: string;
+  };
+  bootstrapPreserveDuplicates: {
+    type: "boolean";
+    default: boolean;
+    category: string;
+    description: string;
+  };
+  bootstrapVersion: {
+    type: "int";
+    default: number;
+    category: string;
+    description: string;
+  };
+};
+declare function buildAttrMatcher(allAttrs: string[]): (name: string) => boolean;
+declare const parsers: Record<string, Parser>;
+//#endregion
+export { BREAKPOINTS, type BootstrapPluginOptions, CLASS_ORDER, type SortOptions, buildAttrMatcher, classKey, options, parsers, sortClasses };

package/dist/index.d.mts

@@ -1,23 +1,11 @@
-import { Options, Parser } from "prettier";
+import { a as BootstrapPluginOptions, i as sortClasses, n as CLASS_ORDER, o as SortOptions, r as classKey, t as BREAKPOINTS } from "./class-order-BYtmS-1R.mjs";
+import { Parser } from "prettier";
 
-//#region src/types.d.ts
-interface BootstrapPluginOptions extends Options {
-  bootstrapAttributes?: string[];
-  bootstrapFunctions?: string[];
-}
-type SortKey = [categoryIndex: number, breakpointIndex: number];
-//#endregion
-//#region src/class-order.d.ts
-declare const BREAKPOINTS: readonly ["sm", "md", "lg", "xl", "xxl"];
-declare const CLASS_ORDER: readonly string[];
-declare function classKey(className: string): SortKey;
-declare function sortClasses(classes: string[]): string[];
-//#endregion
 //#region src/index.d.ts
 declare const options: {
   bootstrapAttributes: {
     type: "string";
-    array: boolean;
+    array: true;
     default: {
       value: never[];
     }[];
@@ -26,14 +14,33 @@ declare const options: {
   };
   bootstrapFunctions: {
     type: "string";
-    array: boolean;
+    array: true;
     default: {
       value: never[];
     }[];
     category: string;
     description: string;
   };
+  bootstrapPreserveWhitespace: {
+    type: "boolean";
+    default: boolean;
+    category: string;
+    description: string;
+  };
+  bootstrapPreserveDuplicates: {
+    type: "boolean";
+    default: boolean;
+    category: string;
+    description: string;
+  };
+  bootstrapVersion: {
+    type: "int";
+    default: number;
+    category: string;
+    description: string;
+  };
 };
-declare const parsers: Record<string, Partial<Parser>>;
+declare function buildAttrMatcher(allAttrs: string[]): (name: string) => boolean;
+declare const parsers: Record<string, Parser>;
 //#endregion
-export { BREAKPOINTS, type BootstrapPluginOptions, CLASS_ORDER, classKey, options, parsers, sortClasses };
+export { BREAKPOINTS, type BootstrapPluginOptions, CLASS_ORDER, type SortOptions, buildAttrMatcher, classKey, options, parsers, sortClasses };

package/dist/index.d.ts

@@ -2,7 +2,7 @@ import type { Parser } from 'prettier';
 export declare const options: {
     bootstrapAttributes: {
         type: "string";
-        array: boolean;
+        array: true;
         default: {
             value: never[];
         }[];
@@ -11,14 +11,34 @@ export declare const options: {
     };
     bootstrapFunctions: {
         type: "string";
-        array: boolean;
+        array: true;
         default: {
             value: never[];
         }[];
         category: string;
         description: string;
     };
+    bootstrapPreserveWhitespace: {
+        type: "boolean";
+        default: boolean;
+        category: string;
+        description: string;
+    };
+    bootstrapPreserveDuplicates: {
+        type: "boolean";
+        default: boolean;
+        category: string;
+        description: string;
+    };
+    bootstrapVersion: {
+        type: "int";
+        default: number;
+        category: string;
+        description: string;
+    };
 };
-export declare const parsers: Record<string, Partial<Parser>>;
-export type { BootstrapPluginOptions } from './types';
+declare function buildAttrMatcher(allAttrs: string[]): (name: string) => boolean;
+export declare const parsers: Record<string, Parser>;
+export { buildAttrMatcher };
+export type { BootstrapPluginOptions, SortOptions } from './types';
 export { sortClasses, classKey, CLASS_ORDER, BREAKPOINTS } from './class-order';