prettier-plugin-bootstrap 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Pier Luigi Lenoci
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,104 @@
+# prettier-plugin-bootstrap
+
+[![CI](https://github.com/pierluigilenoci/prettier-plugin-bootstrap/actions/workflows/ci.yml/badge.svg)](https://github.com/pierluigilenoci/prettier-plugin-bootstrap/actions/workflows/ci.yml)
+[![npm](https://img.shields.io/npm/v/prettier-plugin-bootstrap)](https://www.npmjs.com/package/prettier-plugin-bootstrap)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+A [Prettier](https://prettier.io/) plugin that automatically sorts Bootstrap CSS classes following the framework's recommended order.
+
+Works with **HTML**, **JSX/TSX**, **Vue**, **Angular**, and **Astro** templates.
+
+## Installation
+
+```bash
+npm install -D prettier-plugin-bootstrap
+# or
+pnpm add -D prettier-plugin-bootstrap
+# or
+yarn add -D prettier-plugin-bootstrap
+```
+
+## Usage
+
+Add the plugin to your Prettier configuration:
+
+```json
+{
+  "plugins": ["prettier-plugin-bootstrap"]
+}
+```
+
+That's it! Your Bootstrap classes will now be automatically sorted on format.
+
+### Before
+
+```html
+<div class="text-center p-3 container bg-primary text-white mb-4 rounded"></div>
+```
+
+### After
+
+```html
+<div class="container bg-primary text-center text-white mb-4 p-3 rounded"></div>
+```
+
+## Sorting Order
+
+Classes are sorted following Bootstrap's architecture:
+
+1. **Layout** — containers, grid, columns
+2. **Reboot / Typography** — headings, lead, display
+3. **Images** — img-fluid, figures
+4. **Tables** — table variants
+5. **Forms** — form controls, selects, checks
+6. **Buttons** — btn variants
+7. **Components** — dropdowns, navs, cards, modals, etc. (alphabetical)
+8. **Helpers** — clearfix, stacks, visually-hidden
+9. **Utilities** — following the order in `scss/_utilities.scss`
+
+Within each group, responsive variants (`sm`, `md`, `lg`, `xl`, `xxl`) sort after the base class.
+
+Unknown classes are preserved in their original relative order and placed after all known Bootstrap classes.
+
+## 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`) |
+
+### Example
+
+```json
+{
+  "plugins": ["prettier-plugin-bootstrap"],
+  "bootstrapAttributes": ["ngClass", "v-bind:class"]
+}
+```
+
+## Supported Parsers
+
+- `html` — HTML files
+- `vue` — Vue single-file components
+- `angular` — Angular templates
+- `babel` / `babel-ts` / `typescript` — JSX/TSX files
+- `acorn` / `meriyah` — Alternative JS parsers
+- `astro` — Astro components (requires `prettier-plugin-astro`)
+
+## Development
+
+```bash
+pnpm install
+pnpm run build
+pnpm run test
+pnpm run typecheck
+```
+
+## Compatibility
+
+- Prettier >= 3.0.0
+- Node.js >= 20
+
+## License
+
+MIT

package/dist/class-order.d.ts

@@ -0,0 +1,6 @@
+import type { SortKey } from './types';
+export declare const BREAKPOINTS: readonly ["sm", "md", "lg", "xl", "xxl"];
+export declare const CLASS_ORDER: readonly string[];
+export declare const ORDER_MAP: Map<string, number>;
+export declare function classKey(className: string): SortKey;
+export declare function sortClasses(classes: string[]): string[];

package/dist/index.d.ts

@@ -0,0 +1,24 @@
+import type { Parser } from 'prettier';
+export declare const options: {
+    bootstrapAttributes: {
+        type: "string";
+        array: boolean;
+        default: {
+            value: never[];
+        }[];
+        category: string;
+        description: string;
+    };
+    bootstrapFunctions: {
+        type: "string";
+        array: boolean;
+        default: {
+            value: never[];
+        }[];
+        category: string;
+        description: string;
+    };
+};
+export declare const parsers: Record<string, Partial<Parser>>;
+export type { BootstrapPluginOptions } from './types';
+export { sortClasses, classKey, CLASS_ORDER, BREAKPOINTS } from './class-order';

package/dist/index.js

@@ -0,0 +1,413 @@
+//#region src/class-order.ts
+const BREAKPOINTS = [
+	"sm",
+	"md",
+	"lg",
+	"xl",
+	"xxl"
+];
+const RESPONSIVE_RE = new RegExp(`^(.+?)-(${BREAKPOINTS.join("|")})-(.+)$`);
+const CLASS_ORDER = [
+	"container-fluid",
+	"container-sm",
+	"container-md",
+	"container-lg",
+	"container-xl",
+	"container-xxl",
+	"container",
+	"row",
+	"row-cols-",
+	"col-auto",
+	"col-1",
+	"col-2",
+	"col-3",
+	"col-4",
+	"col-5",
+	"col-6",
+	"col-7",
+	"col-8",
+	"col-9",
+	"col-10",
+	"col-11",
+	"col-12",
+	"col",
+	"offset-",
+	"g-",
+	"gx-",
+	"gy-",
+	"h1",
+	"h2",
+	"h3",
+	"h4",
+	"h5",
+	"h6",
+	"lead",
+	"display-",
+	"list-unstyled",
+	"list-inline",
+	"list-inline-item",
+	"initialism",
+	"blockquote",
+	"blockquote-footer",
+	"img-fluid",
+	"img-thumbnail",
+	"figure",
+	"figure-img",
+	"figure-caption",
+	"table",
+	"table-",
+	"caption-top",
+	"form-label",
+	"col-form-label",
+	"form-text",
+	"form-control",
+	"form-control-",
+	"form-select",
+	"form-select-",
+	"form-check",
+	"form-check-",
+	"form-switch",
+	"form-floating",
+	"form-range",
+	"input-group",
+	"input-group-",
+	"valid-feedback",
+	"valid-tooltip",
+	"invalid-feedback",
+	"invalid-tooltip",
+	"was-validated",
+	"btn",
+	"btn-",
+	"btn-close",
+	"btn-close-",
+	"fade",
+	"collapse",
+	"collapsing",
+	"show",
+	"dropdown",
+	"dropdown-",
+	"dropup",
+	"dropend",
+	"dropstart",
+	"btn-group",
+	"btn-group-",
+	"btn-toolbar",
+	"nav",
+	"nav-",
+	"tab-content",
+	"tab-pane",
+	"navbar",
+	"navbar-",
+	"card",
+	"card-",
+	"accordion",
+	"accordion-",
+	"breadcrumb",
+	"breadcrumb-item",
+	"pagination",
+	"pagination-",
+	"page-item",
+	"page-link",
+	"badge",
+	"alert",
+	"alert-",
+	"progress",
+	"progress-",
+	"progress-bar",
+	"progress-bar-",
+	"list-group",
+	"list-group-",
+	"toast",
+	"toast-",
+	"modal",
+	"modal-",
+	"tooltip",
+	"tooltip-",
+	"popover",
+	"popover-",
+	"carousel",
+	"carousel-",
+	"spinner-border",
+	"spinner-border-",
+	"spinner-grow",
+	"spinner-grow-",
+	"offcanvas",
+	"offcanvas-",
+	"placeholder",
+	"placeholder-",
+	"clearfix",
+	"link-",
+	"icon-link",
+	"icon-link-",
+	"ratio",
+	"ratio-",
+	"fixed-top",
+	"fixed-bottom",
+	"sticky-top",
+	"sticky-bottom",
+	"hstack",
+	"vstack",
+	"stretched-link",
+	"text-truncate",
+	"vr",
+	"visually-hidden",
+	"visually-hidden-focusable",
+	"align-",
+	"float-",
+	"object-fit-",
+	"opacity-",
+	"overflow-",
+	"d-",
+	"shadow",
+	"shadow-",
+	"focus-ring",
+	"focus-ring-",
+	"position-",
+	"top-",
+	"bottom-",
+	"start-",
+	"end-",
+	"translate-middle",
+	"translate-middle-",
+	"border",
+	"border-",
+	"w-",
+	"mw-",
+	"vw-",
+	"min-vw-",
+	"h-",
+	"mh-",
+	"vh-",
+	"min-vh-",
+	"flex-",
+	"justify-content-",
+	"align-items-",
+	"align-content-",
+	"align-self-",
+	"order-",
+	"m-",
+	"mx-",
+	"my-",
+	"mt-",
+	"me-",
+	"mb-",
+	"ms-",
+	"p-",
+	"px-",
+	"py-",
+	"pt-",
+	"pe-",
+	"pb-",
+	"ps-",
+	"gap-",
+	"row-gap-",
+	"column-gap-",
+	"font-monospace",
+	"fs-",
+	"fst-",
+	"fw-",
+	"lh-",
+	"text-decoration-",
+	"text-",
+	"text-opacity-",
+	"link-opacity-",
+	"link-offset-",
+	"link-underline",
+	"link-underline-",
+	"bg-",
+	"bg-opacity-",
+	"bg-gradient",
+	"user-select-",
+	"pe-none",
+	"pe-auto",
+	"rounded",
+	"rounded-",
+	"visible",
+	"invisible",
+	"z-"
+];
+function buildOrderMap() {
+	const map = /* @__PURE__ */ new Map();
+	for (const [index, prefix] of CLASS_ORDER.entries()) map.set(prefix, index);
+	return map;
+}
+const ORDER_MAP = buildOrderMap();
+function classKey(className) {
+	let base = className;
+	let breakpointIdx = 0;
+	const match = className.match(RESPONSIVE_RE);
+	if (match) {
+		base = `${match[1]}-${match[3]}`;
+		breakpointIdx = BREAKPOINTS.indexOf(match[2]) + 1;
+	}
+	let bestIdx = -1;
+	let bestLen = 0;
+	for (const [prefix, idx] of ORDER_MAP) if (base === prefix || prefix.endsWith("-") && base.startsWith(prefix)) {
+		if (prefix.length > bestLen) {
+			bestLen = prefix.length;
+			bestIdx = idx;
+		}
+	}
+	return [bestIdx === -1 ? Infinity : bestIdx, breakpointIdx];
+}
+function sortClasses(classes) {
+	const annotated = classes.map((cls, i) => ({
+		cls,
+		key: classKey(cls),
+		orig: i
+	}));
+	annotated.sort((a, b) => {
+		if (a.key[0] !== b.key[0]) return a.key[0] - b.key[0];
+		if (a.key[1] !== b.key[1]) return a.key[1] - b.key[1];
+		return a.orig - b.orig;
+	});
+	return annotated.map((entry) => entry.cls);
+}
+//#endregion
+//#region src/sorting.ts
+function sortClassString(value) {
+	if (!value || typeof value !== "string") return value;
+	const trimmed = value.trim();
+	if (!trimmed) return value;
+	const classes = trimmed.split(/\s+/);
+	if (classes.length <= 1) return value;
+	const sorted = sortClasses(classes);
+	const leadingWs = value.match(/^\s*/)[0];
+	const trailingWs = value.match(/\s*$/)[0];
+	return `${leadingWs}${sorted.join(" ")}${trailingWs}`;
+}
+//#endregion
+//#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 processHtmlAst(ast, targetAttrs) {
+	walk(ast, (node) => {
+		if (node.attrs && Array.isArray(node.attrs)) {
+			for (const attr of node.attrs) if (targetAttrs.includes(attr.name) && typeof attr.value === "string") attr.value = sortClassString(attr.value);
+		}
+		if (node.attributes && Array.isArray(node.attributes)) for (const attr of node.attributes) {
+			const name = attr.name || attr.key && attr.key.value;
+			if (targetAttrs.includes(name) && attr.value) {
+				if (typeof attr.value === "string") attr.value = sortClassString(attr.value);
+				else if (attr.value && typeof attr.value.value === "string") attr.value.value = sortClassString(attr.value.value);
+			}
+		}
+	});
+	return ast;
+}
+function processJsxAst(ast, targetAttrs) {
+	walk(ast, (node) => {
+		if (node.type === "JSXAttribute" || node.type === "JSXSpreadAttribute") {
+			const name = node.name && (node.name.name || node.name.value);
+			if (targetAttrs.includes(name) && node.value) {
+				if (node.value.type === "StringLiteral" || node.value.type === "Literal") {
+					const sorted = sortClassString(node.value.value);
+					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}`;
+					}
+				}
+			}
+		}
+	});
+	return ast;
+}
+//#endregion
+//#region src/index.ts
+const DEFAULT_ATTRIBUTES = ["class", "className"];
+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)."
+	}
+};
+function createParserWrapper(parserName, processAst) {
+	const wrapper = {
+		astFormat: parserName === "html" || parserName === "vue" || parserName === "angular" ? "html" : "estree",
+		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.`);
+			return processAst(await originalParser.parse(text, options), [...DEFAULT_ATTRIBUTES, ...options.bootstrapAttributes || []]);
+		}
+	};
+	return wrapper;
+}
+const parsers = {
+	html: createParserWrapper("html", processHtmlAst),
+	vue: createParserWrapper("vue", processHtmlAst),
+	angular: createParserWrapper("angular", processHtmlAst),
+	babel: createParserWrapper("babel", processJsxAst),
+	"babel-ts": createParserWrapper("babel-ts", processJsxAst),
+	typescript: createParserWrapper("typescript", processJsxAst),
+	acorn: createParserWrapper("acorn", processJsxAst),
+	meriyah: createParserWrapper("meriyah", processJsxAst),
+	astro: createParserWrapper("astro", processHtmlAst)
+};
+//#endregion
+export { BREAKPOINTS, CLASS_ORDER, classKey, options, parsers, sortClasses };

package/dist/sorting.d.ts

@@ -0,0 +1 @@
+export declare function sortClassString(value: string): string;

package/dist/traversal.d.ts

@@ -0,0 +1,2 @@
+export declare function processHtmlAst(ast: any, targetAttrs: string[]): any;
+export declare function processJsxAst(ast: any, targetAttrs: string[]): any;

package/dist/types.d.ts

@@ -0,0 +1,6 @@
+import type { Options } from 'prettier';
+export interface BootstrapPluginOptions extends Options {
+    bootstrapAttributes?: string[];
+    bootstrapFunctions?: string[];
+}
+export type SortKey = [categoryIndex: number, breakpointIndex: number];

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "prettier-plugin-bootstrap",
+  "version": "0.1.0",
+  "description": "A Prettier plugin for automatic Bootstrap class sorting",
+  "license": "MIT",
+  "type": "module",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "keywords": [
+    "prettier",
+    "plugin",
+    "bootstrap",
+    "css",
+    "class",
+    "sorting",
+    "class-order",
+    "formatter"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/pierluigilenoci/prettier-plugin-bootstrap.git"
+  },
+  "bugs": {
+    "url": "https://github.com/pierluigilenoci/prettier-plugin-bootstrap/issues"
+  },
+  "homepage": "https://github.com/pierluigilenoci/prettier-plugin-bootstrap#readme",
+  "peerDependencies": {
+    "prettier": "^3.0.0"
+  },
+  "devDependencies": {
+    "prettier": "^3.5.0",
+    "tsdown": "^0.12.0",
+    "typescript": "^5.8.0",
+    "vitest": "^3.1.0"
+  },
+  "scripts": {
+    "build": "tsdown && tsc -p tsconfig.build.json",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "typecheck": "tsc --noEmit"
+  }
+}