@homeflare/config 0.1.0

package/README.md

@@ -0,0 +1,45 @@
+# @homeflare/config
+
+Shared TypeScript, oxlint and oxfmt configuration for HomeFlare projects. One place to
+change a rule, rather than one copy per repo that drifts.
+
+## tsconfig
+
+```jsonc
+// tsconfig.json — an app or a Worker
+{ "extends": "@homeflare/config/tsconfig.base.json" }
+
+// tsconfig.json — a package that publishes types
+{ "extends": "@homeflare/config/tsconfig.lib.json" }
+```
+
+`tsconfig.lib.json` adds `isolatedDeclarations` and `declaration` on top of the base.
+⛔ Both are needed together — `isolatedDeclarations` alone is TS5069, even under
+`--noEmit`.
+
+## oxlint
+
+⚠️ oxlint's `extends` takes **file paths**, not package names — there is no
+`eslint-config-*` style resolution. The path into `node_modules` is written out:
+
+```json
+{
+  "extends": ["./node_modules/@homeflare/config/oxlintrc.json"],
+  "rules": {
+    // project-specific overrides go here
+  }
+}
+```
+
+## oxfmt
+
+⚠️ The file must be named `.oxfmtrc.json` — with the leading dot. Without it, oxfmt
+silently uses its defaults, and the symptom is a formatter that rewrites your quotes.
+
+```sh
+cp node_modules/@homeflare/config/oxfmtrc.json .oxfmtrc.json
+```
+
+## License
+
+MIT © Timothy Schneider

package/oxfmtrc.json

@@ -0,0 +1,7 @@
+{
+  "printWidth": 100,
+  "useTabs": false,
+  "singleQuote": true,
+  "semi": true,
+  "ignorePatterns": ["**/node_modules/**", "**/dist/**", "**/coverage/**"]
+}

package/oxlintrc.json

@@ -0,0 +1,27 @@
+{
+  "plugins": ["typescript", "unicorn", "oxc", "import"],
+  "categories": {
+    "correctness": "error",
+    "suspicious": "warn",
+    "perf": "warn"
+  },
+  "env": {
+    "builtin": true,
+    "es2024": true
+  },
+  "ignorePatterns": ["dist/**", "coverage/**"],
+  "rules": {
+    "no-console": "error",
+    "typescript/consistent-type-imports": "error",
+    "typescript/no-explicit-any": "error",
+    "import/no-default-export": "error"
+  },
+  "overrides": [
+    {
+      "files": ["**/tests/**", "**/*.test.ts", "**/scripts/**"],
+      "rules": {
+        "no-console": "off"
+      }
+    }
+  ]
+}

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "@homeflare/config",
+  "version": "0.1.0",
+  "description": "Shared tsconfig, oxlint and oxfmt configuration for HomeFlare projects.",
+  "license": "MIT",
+  "author": "Timothy Schneider",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/taslabs-net/homeflare-kit.git",
+    "directory": "packages/config"
+  },
+  "files": [
+    "tsconfig.base.json",
+    "tsconfig.lib.json",
+    "oxlintrc.json",
+    "oxfmtrc.json",
+    "README.md"
+  ],
+  "type": "module",
+  "exports": {
+    "./tsconfig.base.json": "./tsconfig.base.json",
+    "./tsconfig.lib.json": "./tsconfig.lib.json",
+    "./oxlintrc.json": "./oxlintrc.json",
+    "./oxfmtrc.json": "./oxfmtrc.json",
+    "./package.json": "./package.json"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "echo 'config: nothing to build'",
+    "clean": "echo 'config: nothing to clean'"
+  }
+}

package/tsconfig.base.json

@@ -0,0 +1,35 @@
+{
+  // The HomeFlare TypeScript baseline. Every project extends this and overrides only
+  // what its runtime genuinely needs.
+  //
+  //     { "extends": "@homeflare/config/tsconfig.base.json" }
+  //
+  // ★ WHY THESE SETTINGS AND NOT tsc's DEFAULTS. Each one below turns a class of runtime
+  //   bug into a compile error. They are painful to adopt late and nearly free to adopt
+  //   at the start, which is the whole argument for a shared baseline.
+  "compilerOptions": {
+    "lib": ["ESNext"],
+    "target": "ESNext",
+    "module": "preserve",
+    "moduleResolution": "bundler",
+    "moduleDetection": "force",
+
+    // ⛔ Emit is a build tool's job, never the checker's.
+    "noEmit": true,
+    "allowImportingTsExtensions": true,
+    "verbatimModuleSyntax": true,
+    "isolatedModules": true,
+
+    "strict": true,
+    // ⚠️ arr[0] is T | undefined, not T. The single most common source of "cannot read
+    //   property of undefined" in production, and the flag that catches it.
+    "noUncheckedIndexedAccess": true,
+    "noImplicitOverride": true,
+    "noFallthroughCasesInSwitch": true,
+    // ⚠️ Distinguishes `{ a?: string }` from `{ a: string | undefined }`. Without it,
+    //   an optional property can be explicitly set to undefined and typecheck.
+    "exactOptionalPropertyTypes": true,
+
+    "skipLibCheck": true
+  }
+}

package/tsconfig.lib.json

@@ -0,0 +1,17 @@
+{
+  // For a package that PUBLISHES types. Adds declaration emit to the baseline.
+  //
+  //     { "extends": "@homeflare/config/tsconfig.lib.json" }
+  //
+  // ⛔ isolatedDeclarations REQUIRES every exported symbol to carry an explicit type.
+  //   ★ That is what makes a two-tool build safe: when a bundler emits the JS and tsc
+  //     emits the .d.ts separately, explicit types are the only thing keeping the two
+  //     from drifting apart.
+  // ⚠️ TS5069: isolatedDeclarations cannot be set without `declaration`, even when emit
+  //   is off. Both appear here; a build config turns `noEmit` off.
+  "extends": "./tsconfig.base.json",
+  "compilerOptions": {
+    "isolatedDeclarations": true,
+    "declaration": true
+  }
+}