👮 @epic-web/config

Reasonable Oxlint, Oxfmt, and TypeScript configs for epic web devs

This makes assumptions about the way you prefer to develop software and gives you configurations that will actually help you in your development.

npm install @epic-web/config

<a alt="Epic Web logo" href="https://www.epicweb.dev"

<img
  width="300px"
  src="https://github-production-user-asset-6210df.s3.amazonaws.com/1500684/257881576-fd66040b-679f-4f25-b0d0-ab886a14909a.png"
/>

---

The problem

You're a professional, but you're mature enough to know that even professionals can make mistakes, and you value your time enough to not want to waste time configuring code quality tools or babysitting them.

This solution

This package provides shared defaults for the tools this repo currently ships:

• Oxlint
• Oxfmt
• TypeScript

Decisions

You can learn about the different decisions made for this project in the decision docs.

Usage

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).

Oxfmt (formatter)

Install Oxfmt alongside this package (it is listed in peerDependencies).

The @epic-web/config/oxfmt entry resolves to a plain .js preset (this package uses "type": "module") so Node does not need to strip TypeScript from files under node_modules when you extend it.

Create an oxfmt.config.ts file in your project root:

import epicOxfmt from '@epic-web/config/oxfmt'
import { defineConfig } from 'oxfmt'

export default defineConfig({
    ...epicOxfmt,
    printWidth: 100,
})

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).

Add scripts (see the migration guide):

{
    "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 covers common build, cache, Playwright, Prisma, and lockfile paths used across Epic projects. Adjust in your defineConfig if your layout differs.

Customizing Oxfmt

If you want to customize things heavily, you can copy the options from oxfmt-preset.js 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).

TypeScript

Create a tsconfig.json file in your project root with the following content:

{
    "extends": ["@epic-web/config/typescript"],
    "include": ["**/*.ts", "**/*.tsx", "**/*.js", "**/*.jsx"],
    "compilerOptions": {
        "paths": {
            "#app/*": ["./app/*"],
            "#tests/*": ["./tests/*"]
        }
    }
}

Create a reset.d.ts file in your project with these contents:

import '@epic-web/config/reset.d.ts'

Customizing TypeScript

Learn more from the TypeScript docs here.

Oxlint

Create a .oxlintrc.json file in your project root with the following content:

{
    "extends": ["./node_modules/@epic-web/config/oxlint-config.json"]
}

This config includes the custom epic-web/* rules documented in lint-rules/index.md.

Note: typescript/no-misused-promises and typescript/no-floating-promises are type-aware in Oxlint and require the type-aware setup described in the Oxlint docs.

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 docs.

Not yet covered

The following rule families are intentionally omitted because they are not yet part of the Oxlint config this package ships:

• import/order
• react-hooks/rules-of-hooks
• react-hooks/exhaustive-deps
• testing-library/*
• jest-dom/*
• most vitest/* rules
• playwright/*

License

MIT