{"record":{"id":"5e0095f5903e962a","repo":"oxc-project/oxc","slug":"expected-unicode-bom-byte-order-mark","errorCode":null,"errorMessage":"Expected Unicode BOM (Byte Order Mark)","messagePattern":"Expected Unicode BOM \\(Byte Order Mark\\)","errorType":"validation","errorClass":"OxcDiagnostic","httpStatus":null,"severity":"error","filePath":"crates/oxc_linter/src/rules/eslint/unicode_bom.rs","lineNumber":19,"sourceCode":"use oxc_diagnostics::OxcDiagnostic;\nuse oxc_macros::declare_oxc_lint;\nuse oxc_span::{SPAN, Span};\nuse schemars::JsonSchema;\nuse serde::Deserialize;\n\nuse crate::{\n    context::LintContext,\n    rule::{DefaultRuleConfig, Rule},\n};\n\nfn unexpected_unicode_bom_diagnostic(span: Span) -> OxcDiagnostic {\n    OxcDiagnostic::warn(\"Unexpected Unicode BOM (Byte Order Mark)\")\n        .with_help(\"File must not begin with the Unicode BOM\")\n        .with_label(span)\n}\n\nfn expected_unicode_bom_diagnostic(span: Span) -> OxcDiagnostic {\n    OxcDiagnostic::warn(\"Expected Unicode BOM (Byte Order Mark)\")\n        .with_help(\"File must begin with the Unicode BOM\")\n        .with_label(span)\n}\n\n#[derive(Debug, Default, Clone, Deserialize)]\npub struct UnicodeBom(BomOptionType);\n\n#[derive(Debug, Default, Clone, Deserialize, JsonSchema)]\n#[serde(rename_all = \"kebab-case\")]\nenum BomOptionType {\n    /// Always require a Unicode BOM (Byte Order Mark) at the beginning of the file.\n    Always,\n    /// Never allow a Unicode BOM (Byte Order Mark) at the beginning of the file.\n    /// This is the default option.\n    #[default]\n    Never,\n}\n","sourceCodeStart":1,"sourceCodeEnd":37,"githubUrl":"https://github.com/oxc-project/oxc/blob/e1e7af627c8843ab64044ed466b128fcc21a035b/crates/oxc_linter/src/rules/eslint/unicode_bom.rs#L1-L37","documentation":"oxlint's `unicode-bom` rule (eslint plugin) requires or disallows a Unicode BOM (U+FEFF) at the start of every linted file. This variant is emitted from `run_once` when the rule option is \"always\" but `ctx.source_text()` does not start with U+FEFF (bytes EF BB BF). The diagnostic ships with an autofix that inserts the BOM at byte 0.","triggerScenarios":"Configuring `\"unicode-bom\": [\"error\", \"always\"]` in .oxlintrc.json (or an inherited ESLint config) and linting any file saved as plain UTF-8 without a BOM — the default for VS Code, WebStorm, and most POSIX editors.","commonSituations":"Teams inheriting legacy configs from Windows/Visual Studio shops where \"always\" was the norm; editors silently stripping the BOM on save (VS Code default files.encoding utf8); files converted between encodings; mixed-encoding monorepos where only some files carry a BOM.","solutions":["Save the file as UTF-8 with BOM (VS Code: click the encoding indicator, 'Save with Encoding', 'UTF-8 with BOM', or set \"files.encoding\": \"utf8bom\" for the file)","Run `oxlint --fix` on the file — the rule's fixer inserts the BOM automatically","If a BOM is not actually wanted, set the rule back to its default \"never\" or remove it from the config","Batch-convert with a script that prepends EF BB BF only to files confirmed to lack it"],"exampleFix":"// before — file starts with plain bytes, no BOM\nconst a = 1;\n\n// after — file starts with U+FEFF (bytes EF BB BF), shown here as <BOM>\n<BOM>const a = 1;","handlingStrategy":"validation","validationCode":"// .oxlintrc.json — make the policy explicit\n{ \"rules\": { \"unicode-bom\": [\"error\", \"always\"] } }\n\n# fast pre-check without running the full linter\nfor f in $(git ls-files '*.js' '*.ts'); do\n  head -c 3 \"$f\" | od -An -tx1 | grep -q 'ef bb bf' || echo \"missing BOM: $f\"\ndone","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Pin editor encoding (VS Code files.encoding, .editorconfig) so every save preserves the BOM policy","Run oxlint via lint-staged/pre-commit so BOM drift is caught per file, not at CI","Standardize on the default \"never\" unless a toolchain genuinely requires BOMs","Gate CI on the BOM check before the full lint run for fast feedback"],"tags":["lint","oxlint","eslint","unicode","bom","encoding","utf8"],"backgroundTag":"unicode-bom-encoding","analyzedSha":"e1e7af627c8843ab64044ed466b128fcc21a035b","analyzedAt":"2026-08-20T07:01:07.079Z","contentChangedAt":"2026-08-20T07:01:07.079Z","schemaVersion":2},"datasetVersion":"2026-09-14T00:17:10.932Z"}