@jlaloi/ts-config

View on npm

Shared Oxfmt, Oxlint, and TypeScript configurations for JavaScript and TypeScript projects. Requires Node.js 26.13.0 or newer. The package exports JavaScript with type declarations and needs no build step.

Install

Install it in another project:

npm install --save-dev @jlaloi/ts-config oxfmt oxlint

The installed package name is @jlaloi/ts-config. Installing from GitHub does not require publishing to npm. The repository is currently private, so Git must have access to it when installing locally or in CI. Use a Git tag or commit, such as github:jlaloi/ts-config#v0.1.0, once one exists to pin a specific configuration release.

Configure a project

Create oxfmt.config.ts in your project root:

export { default } from '@jlaloi/ts-config/oxfmt'

Create oxlint.config.ts alongside it:

export { default } from '@jlaloi/ts-config/oxlint'

Add scripts to your project's package.json:

{
  "scripts": {
    "format": "oxfmt --write .",
    "format:check": "oxfmt --check .",
    "lint": "oxlint --deny-warnings .",
    "lint:fix": "oxlint --fix ."
  }
}

Keep one configuration file per tool in each directory. Replace an existing .oxfmtrc.json, .oxfmtrc.jsonc, or .oxlintrc.json when switching to these imports.

For TypeScript, extend the shared config in your project's tsconfig.json:

{
  "extends": "@jlaloi/ts-config/tsconfig"
}

The config targets the current LTS version, Node.js 26, by extending @tsconfig/node26/tsconfig.json. The .json suffix is optional. Add project-specific compiler options, includes, and excludes locally.

Projects run their .ts files directly on Node.js, so tsc only type-checks. The config sets strict and noEmit, and enables allowImportingTsExtensions, verbatimModuleSyntax, and erasableSyntaxOnly to reject code that Node.js type stripping can't run.

Install TypeScript and Node.js types in your project:

npm install --save-dev typescript @types/node@26

VS Code

Recommend the Oxc extension in .vscode/extensions.json:

{
  "recommendations": ["oxc.oxc-vscode"]
}

Set it as the formatter and apply Oxlint fixes on save in .vscode/settings.json:

{
  "editor.formatOnSave": true,
  "editor.defaultFormatter": "oxc.oxc-vscode",
  "editor.codeActionsOnSave": {
    "source.fixAll.oxc": "explicit"
  }
}

Setting the formatter at the root lets VS Code format every file type Oxfmt supports, including JSON, YAML, CSS, Markdown, and HTML, so saving in the editor matches format:check. With "explicit", Oxlint fixes run on a manual save but not on autosave. Use "always" to include autosave.

Line endings

Oxfmt writes LF line endings, and Linux deployments expect them. Git on Windows with core.autocrlf=true checks files out with CRLF, and format:check then flags every file. Commit a .gitattributes file so every clone uses LF, whatever the machine's Git settings:

* text=auto eol=lf
*.bat text eol=crlf
*.cmd text eol=crlf

Batch files keep CRLF because cmd.exe can misread them with LF. After adding the file to an existing repository, run git add --renormalize . to convert files Git already stores with CRLF.

Defaults

Oxfmt uses single quotes, two-space indentation, and no optional semicolons. Other options retain Oxfmt's defaults, including semicolons in CSS.

Oxlint enables its default correctness checks at warning severity and retains the default plugin set. The lint script fails on warnings so CI catches these findings. Type-aware linting is not enabled.

Oxfmt sorts imports into side effects, Node built-ins, external packages, internal imports, and relative imports. Types come before values within each group, with blank lines between groups. Side-effect imports keep their relative order. This approximates the original simple-import-sort grouping using Oxfmt's built-in classification. Projects with other aliases can override sortImports.internalPattern, spreading config.sortImports first to keep the shared grouping.

Run format to sort imports and format:check to enforce their order. Oxlint does not enforce import sorting. No extra dependency is required.

Project overrides

Import the shared object and spread it before your project options:

// oxfmt.config.ts
import config from '@jlaloi/ts-config/oxfmt'
import { defineConfig } from 'oxfmt'

export default defineConfig({
  ...config,
  printWidth: 120,
  ignorePatterns: ['dist/**', 'coverage/**'],
})

// oxlint.config.ts
import config from '@jlaloi/ts-config/oxlint'
import { defineConfig } from 'oxlint'

export default defineConfig({
  ...config,
  ignorePatterns: ['dist/**', 'coverage/**'],
  rules: {
    ...config.rules,
    'eslint/no-unused-vars': 'error',
  },
})

Spreading is shallow. Merge nested objects such as rules explicitly when overriding them. Keep generated-file ignores and framework-specific rules in the consuming project.

Work on this package

npm ci --ignore-scripts
npm run check

The repository uses its own exported Oxfmt and Oxlint configurations. Change oxfmt.js, oxlint.js, or tsconfig.json to update the shared defaults, then run npm run format and npm run check.

To try unpublished changes in another local project:

npm install --save-dev /absolute/path/to/ts-config oxfmt oxlint

Weekly checklist

• [ ] Check the Friday Renovate run and the Dependency Dashboard issue. Keep the dashboard open.
• [ ] Review pending dependency PRs and merge approved updates after CI passes. Minor and major updates need manual review.
• [ ] Run Actions → Renovate → Run workflow on main to merge passing patch PRs without waiting another week. For conflicts, tick the PR's rebase/retry checkbox first.
• [ ] When ready to publish, run Actions → Release → Run workflow on main. Commit messages determine the version: fix for patch, feat for minor, and a BREAKING CHANGE: footer for major.
• [ ] Check the release run, generated GitHub release, and npm version. If there are no release-worthy commits, no publication is expected.

Documentation

• Oxfmt configuration
• Oxlint configuration and shared packages
• Oxfmt import sorting