feat(oxfmt): replace Prettier with shared Oxfmt preset

Add oxfmt-preset.mjs and local oxfmt.config.mjs, document consumer setup, and record the decision. Add epic-web/no-prettier-ignore for Oxfmt ignore comments. Remove prettier.js, Prettier dependencies, and the prettier discussion template in favor of oxfmt-suggestion.

BREAKING CHANGE: Prettier is no longer shipped from this package. Drop the `prettier` field and `@epic-web/config/prettier` import, install `oxfmt` (peer dependency), and follow the README to extend `@epic-web/config/oxfmt` from an `oxfmt.config.ts` (or equivalent) file.

Made-with: Cursor

Author: kentcdodds

…CUSSION_TEMPLATE/prettier-suggestion.yml …DISCUSSION_TEMPLATE/oxfmt-suggestion.yml.github/DISCUSSION_TEMPLATE/prettier-suggestion.yml renamed to .github/DISCUSSION_TEMPLATE/oxfmt-suggestion.yml .github/DISCUSSION_TEMPLATE/prettier-suggestion.yml renamed to .github/DISCUSSION_TEMPLATE/oxfmt-suggestion.yml

@@ -21,7 +21,7 @@ body:
       description: >-
         Link to the documentation for the config option you're suggesting
         changing
-      placeholder: https://prettier.io/docs/en/options#jsx-quotes
+      placeholder: https://oxc.rs/docs/guide/usage/formatter/config-file-reference.html
     validations:
       required: true
   - type: textarea

.github/DISCUSSION_TEMPLATE/oxlint-suggestion.yml

@@ -19,18 +19,17 @@ body:
     attributes:
       label: Rule or Config Docs
       description: >-
-        Link to the Oxlint rule or configuration docs you're suggesting
-        changing
+        Link to the Oxlint rule or configuration docs you're suggesting changing
       placeholder: https://oxc.rs/docs/guide/usage/linter/rules/
     validations:
       required: true
   - type: textarea
     attributes:
       label: Suggested Change
       description: >-
-        Write out the suggested change in configuration. If the rule or config is
-        already present, explain why it should be removed or changed. If it's not
-        present, explain why it should be added. And provide the final
+        Write out the suggested change in configuration. If the rule or config
+        is already present, explain why it should be removed or changed. If it's
+        not present, explain why it should be added. And provide the final
         configuration for the option.
     validations:
       required: true

.gitignore

@@ -1,2 +1,4 @@
 node_modules
 .idea
+epic-web-config-*.tgz
+tmp-oxfmt-smoke

README.md

@@ -1,7 +1,7 @@
 <div>
   <h1 align="center"><a href="https://npm.im/@epic-web/config">👮 @epic-web/config</a></h1>
   <strong>
-    Reasonable Oxlint, Prettier, and TypeScript configs for epic web devs
+    Reasonable Oxlint, Oxfmt, and TypeScript configs for epic web devs
   </strong>
   <p>
     This makes assumptions about the way you prefer to develop software and gives you configurations that will actually help you in your development.
@@ -43,7 +43,7 @@ configuring code quality tools or babysitting them.
 This package provides shared defaults for the tools this repo currently ships:
 
 - Oxlint
-- Prettier
+- Oxfmt
 - TypeScript
 
 ## Decisions
@@ -57,33 +57,64 @@ Technically you configure everything yourself, but you can use the configs in
 this project as a starter for your projects (and in some cases you don't need to
 configure anything more than the defaults).
 
-### Prettier
+### Oxfmt (formatter)
 
-The easiest way to use this config is in your `package.json`:
+Install [Oxfmt](https://oxc.rs/docs/guide/usage/formatter.html) alongside this
+package (it is listed in `peerDependencies`).
 
-```json
-"prettier": "@epic-web/config/prettier"
-```
+The `@epic-web/config/oxfmt` entry resolves to a plain `.mjs` preset so Node
+does not need to strip TypeScript from files under `node_modules` when you
+extend it.
 
-<details>
-  <summary>Customizing Prettier</summary>
+Create an `oxfmt.config.ts` file in your project root:
+
+```ts
+import epicOxfmt from '@epic-web/config/oxfmt'
+import { defineConfig } from 'oxfmt'
 
-If you want to customize things, you should probably just copy/paste the
-built-in config. But if you really want, you can override it using regular
-JavaScript stuff.
+export default defineConfig({
+	...epicOxfmt,
+	printWidth: 100,
+})
+```
 
-Create a `.prettierrc.js` file in your project root with the following content:
+Oxfmt does not have an `extends` field; spreading the preset and setting any
+top-level option afterward is how you override it (same idea for
+`ignorePatterns`: spread `epicOxfmt.ignorePatterns` and append paths).
 
-```js
-import defaultConfig from '@epic-web/config/prettier'
+Add scripts (see the
+[migration guide](https://oxc.rs/docs/guide/usage/formatter/migrate-from-prettier.html)):
 
-/** @type {import("prettier").Options} */
-export default {
-	...defaultConfig,
-	// .. your overrides here...
+```json
+{
+	"scripts": {
+		"format": "oxfmt",
+		"format:check": "oxfmt --check"
+	}
 }
 ```
 
+The shared config sets 80 `printWidth`, tabs (spaces only in `package.json`
+overrides), no semicolons, single quotes, `trailingComma: "all"`, Tailwind class
+sorting via native `sortTailwindcss`, and MDX overrides for `proseWrap` /
+`htmlWhitespaceSensitivity`. Options that Oxfmt does not support
+(`insertPragma`, `requirePragma`) are omitted.
+
+[`ignorePatterns`](https://oxc.rs/docs/guide/usage/formatter/ignore-files.html)
+covers common build, cache, Playwright, Prisma, and lockfile paths used across
+Epic projects. Adjust in your `defineConfig` if your layout differs.
+
+<details>
+  <summary>Customizing Oxfmt</summary>
+
+If you want to customize things heavily, you can copy the options from
+[`oxfmt-preset.mjs`](./oxfmt-preset.mjs) into your own config. For small tweaks,
+keep spreading `epicOxfmt` and override or extend fields as in the example
+above.
+
+Use `"type": "module"` in your `package.json` when your `oxfmt.config.ts` uses
+`import` / `export` syntax (same as for other ESM tooling).
+
 </details>
 
 ### TypeScript
@@ -138,6 +169,13 @@ Some Oxlint rule IDs still use the `eslint/` namespace because that is how
 Oxlint exposes those compatibility rules. You do not need to install ESLint to
 use them.
 
+The `epic-web/no-prettier-ignore` rule warns on `prettier-ignore` in JavaScript
+and TypeScript comments and can auto-fix them to `oxfmt-ignore` for Oxfmt. Keep
+`prettier-ignore` where Oxfmt still recommends it (for example non-JS regions in
+Vue); see the
+[inline ignore comments](https://oxc.rs/docs/guide/usage/formatter/ignore-comments.html)
+docs.
+
 #### Not yet covered
 
 The following rule families are intentionally omitted because they are not yet

docs/decisions/011-oxfmt-over-prettier.md

@@ -0,0 +1,60 @@
+# Oxfmt over Prettier
+
+Date: 2026-04-14
+
+Status: accepted
+
+## Context
+
+This package previously shipped a shared [Prettier](https://prettier.io)
+configuration (`prettier.js`) and documented the `"prettier"` field in
+`package.json` as the primary way to adopt consistent formatting across Epic Web
+projects.
+
+We already recommend [Oxlint](https://oxc.rs/docs/guide/usage/linter.html) from
+the same [Oxc](https://oxc.rs) project for fast linting.
+[Oxfmt](https://oxc.rs/docs/guide/usage/formatter.html) is Oxc’s formatter: it
+targets Prettier-compatible output for many options, runs as a single native
+CLI, and implements common needs (for example Tailwind class sorting) without
+Prettier’s plugin ecosystem.
+
+Teams were maintaining Prettier plus `prettier-plugin-tailwindcss` and separate
+ignore files; lockfiles and generated paths were duplicated across
+`.prettierignore` and formatter-adjacent tooling.
+
+## Decision
+
+Adopt **Oxfmt** as the shared formatter for `@epic-web/config`:
+
+- Replace the Prettier entry point with a published `oxfmt-preset.mjs` (via
+  `defineConfig`) and document `oxfmt` as a peer dependency.
+- Map the old Prettier options into Oxfmt where supported; document gaps (for
+  example `insertPragma` / `requirePragma`, and regex-based Tailwind attribute
+  names).
+- Centralize formatter-only ignores in `ignorePatterns` alongside `.gitignore`
+  behavior described in the Oxfmt docs.
+- Encourage `oxfmt-ignore` over `prettier-ignore` in JS/TS via the
+  `epic-web/no-prettier-ignore` lint rule, while keeping `prettier-ignore` where
+  Oxfmt still recommends it for non-JS regions.
+
+## Consequences
+
+**Positive**
+
+- One vendor (Oxc) for lint + format, fewer moving parts and clearer upgrade
+  paths.
+- Faster formatting at scale; no Prettier plugin install for Tailwind sorting.
+- Simpler consumer setup: `oxfmt` scripts and a single TypeScript config export.
+
+**Negative / tradeoffs**
+
+- Prettier plugins are not supported; anything that relied on an unsupported
+  plugin needs another tool or must be dropped.
+- Output is “Prettier-like” but not identical everywhere; teams should expect a
+  one-time format churn when switching.
+- Some Prettier options and comment forms have no equivalent; those are called
+  out in `oxfmt-preset.mjs` and the readme.
+
+Historical decision docs that mention Prettier remain valid as context for
+_formatting style_; this decision supersedes the _tool choice_ for applying that
+style in new work.

docs/style-guide.md

@@ -18,7 +18,8 @@ Much of this is subjective, but most opinions are thought through and based on
 years of experience working with large codebases and teams.
 
 Note: Not every possible formatting opinion is mentioned because they are
-handled automatically by [Prettier](https://prettier.io) anyway.
+handled automatically by [Oxfmt](https://oxc.rs/docs/guide/usage/formatter.html)
+anyway.
 
 ## JavaScript
 

lint-rules/epic-web-plugin.js

@@ -1,5 +1,6 @@
 import { definePlugin } from '@oxlint/plugins'
 import noManualDispose from './no-manual-dispose.js'
+import noPrettierIgnore from './no-prettier-ignore.js'
 import preferDisposeInTests from './prefer-dispose-in-tests.js'
 
 const plugin = definePlugin({
@@ -8,9 +9,10 @@ const plugin = definePlugin({
 	},
 	rules: {
 		'no-manual-dispose': noManualDispose,
+		'no-prettier-ignore': noPrettierIgnore,
 		'prefer-dispose-in-tests': preferDisposeInTests,
 	},
 })
 
 export default plugin
-export { noManualDispose, preferDisposeInTests }
+export { noManualDispose, noPrettierIgnore, preferDisposeInTests }

lint-rules/index.md

@@ -14,4 +14,5 @@ Oxlint JS plugin rules.
 ## Rules
 
 - [`epic-web/no-manual-dispose`](./no-manual-dispose.md)
+- [`epic-web/no-prettier-ignore`](./no-prettier-ignore.md)
 - [`epic-web/prefer-dispose-in-tests`](./prefer-dispose-in-tests.md)

lint-rules/no-manual-dispose.md

@@ -8,8 +8,8 @@ use `using` or `await using`.
 Manual cleanup with `try/finally` and disposal calls is easier to get wrong and
 less readable than language-level disposables.
 
-This rule is implemented as an Oxlint JS plugin rule using Oxlint's
-`createOnce` API.
+This rule is implemented as an Oxlint JS plugin rule using Oxlint's `createOnce`
+API.
 
 ## What it warns on
 

lint-rules/no-prettier-ignore.js

@@ -0,0 +1,62 @@
+/**
+ * @param {import('eslint').AST.Token} comment
+ */
+function isPrettierIgnoreDirective(comment) {
+	const v = comment.value
+	if (comment.type === 'Line') {
+		return /^\s*prettier-ignore(?:-next|-start|-end)?(?:\s|$)/.test(v)
+	}
+	return /^\s*prettier-ignore(?:-next|-start|-end)?(?:\s|$)/m.test(v)
+}
+
+/**
+ * @param {string} text
+ */
+function replacePrettierIgnoreWithOxfmt(text) {
+	return text
+		.replace(/prettier-ignore-next/g, 'oxfmt-ignore')
+		.replace(/prettier-ignore-start/g, 'oxfmt-ignore-start')
+		.replace(/prettier-ignore-end/g, 'oxfmt-ignore-end')
+		.replace(/prettier-ignore/g, 'oxfmt-ignore')
+}
+
+const rule = {
+	meta: {
+		type: 'suggestion',
+		docs: {
+			description:
+				'Prefer `oxfmt-ignore` over `prettier-ignore` in JS/TS comments formatted by Oxfmt',
+		},
+		schema: [],
+		fixable: 'code',
+		messages: {
+			useOxfmtIgnore:
+				'Use `oxfmt-ignore` instead of `prettier-ignore` for Oxfmt. Keep `prettier-ignore` only for non-JS regions (for example Vue template/style or HTML) per Oxfmt docs.',
+		},
+	},
+	createOnce(context) {
+		return {
+			Program() {
+				const sourceCode = context.sourceCode
+				for (const comment of sourceCode.getAllComments()) {
+					if (!isPrettierIgnoreDirective(comment)) continue
+
+					const range = /** @type {[number, number]} */ (comment.range)
+					const raw = sourceCode.text.slice(range[0], range[1])
+					const next = replacePrettierIgnoreWithOxfmt(raw)
+					if (next === raw) continue
+
+					context.report({
+						loc: comment.loc,
+						messageId: 'useOxfmtIgnore',
+						fix(fixer) {
+							return fixer.replaceTextRange(range, next)
+						},
+					})
+				}
+			},
+		}
+	},
+}
+
+export default rule