@martinrun/frontend-config 0.1.3

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Martin Caspersen
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,64 @@
+# frontend-kit
+
+Shared frontend conventions for personal projects. React + TypeScript +
+shadcn/ui + Tailwind.
+
+One repo, three distribution channels:
+
+- **npm package** `@martinrun/frontend-config` — ESLint, tsconfig, Prettier.
+  Updated by Renovate.
+- **shadcn registry** — `DESIGN.md`, the API client, query defaults, theme
+  tokens. Updated deliberately with `shadcn add --overwrite`.
+- **Claude Code plugin** — the conventions skill, so agents follow the rules
+  without a copy of the doc in every repo.
+
+Start here: [SETUP.md](./SETUP.md). The rules themselves: [docs/DESIGN.md](./docs/DESIGN.md).
+
+Bringing an existing repo onto this: [docs/MIGRATION.md](./docs/MIGRATION.md)
+(includes a ready-to-paste agent prompt). Ongoing upkeep once a project is on
+it: [docs/MAINTENANCE.md](./docs/MAINTENANCE.md).
+
+## Preset
+
+Design system preset code: `b0`
+
+This is the one manual step in the whole kit — the code is generated
+interactively and can't be scripted. Go to `ui.shadcn.com/create` and pick:
+**Base UI** primitives, **neutral** base color, **new-york** style, default
+radius (0.5rem), **lucide-react** icons. That reproduces the modern shadcn
+default already baked into `src/styles/theme.css` in this repo, so picking it
+now doesn't change anything for projects that predate the preset — it just
+gives you the short code to hand to new projects and agents. Change any of
+those choices later; re-running `init --preset` on an existing app is cheap
+(see SETUP.md Part 3).
+
+```sh
+pnpm dlx shadcn@latest init --preset <code>
+```
+
+## Install into a project
+
+```sh
+claude plugin marketplace add MartinCa/frontend-kit
+claude plugin install frontend-conventions@martinca
+
+pnpm dlx shadcn@latest add MartinCa/frontend-kit/conventions
+pnpm dlx shadcn@latest add MartinCa/frontend-kit/api-client
+pnpm dlx shadcn@latest add MartinCa/frontend-kit/query-setup
+pnpm dlx shadcn@latest add MartinCa/frontend-kit/theme
+pnpm dlx shadcn@latest add MartinCa/frontend-kit/theme-provider
+pnpm dlx shadcn@latest add MartinCa/frontend-kit/agent-skill
+```
+
+`theme-provider` needs wiring, not just installing — wrap the app in
+`<ThemeProvider>` (SETUP.md Part 6) or dark mode never activates and nothing
+errors to say why. `agent-skill` vendors the conventions skill into
+`.claude/skills/` so Claude Code on web and mobile sees it; the marketplace
+install above only covers the local terminal. Full walkthrough in
+[SETUP.md](./SETUP.md).
+
+## Changing a convention
+
+Change it here, not in a project. Bump the package version for lint changes,
+tag, and let Renovate deliver it. For `DESIGN.md` and shared code, commit and
+reinstall in projects with `--overwrite` next time you touch them.

package/eslint.config.js

@@ -0,0 +1,159 @@
+// Shared ESLint flat config.
+//
+// This file is the machine-enforceable half of DESIGN.md. Rules that can be
+// linted live here; rules that need judgement live in the prose doc.
+//
+// Usage in a project's eslint.config.js:
+//
+//   import config from "@martinrun/frontend-config/eslint";
+//   export default config();
+//
+// To relax a rule for one project, spread and override:
+//
+//   export default [...config(), { rules: { "no-restricted-syntax": "off" } }];
+
+import js from "@eslint/js";
+import globals from "globals";
+import tseslint from "typescript-eslint";
+import reactHooks from "eslint-plugin-react-hooks";
+import reactRefresh from "eslint-plugin-react-refresh";
+import prettier from "eslint-config-prettier";
+
+/**
+ * @param {object} [options]
+ * @param {string[]} [options.ignores] Extra ignore globs.
+ * @returns {import("eslint").Linter.Config[]}
+ */
+export default function config({ ignores = [] } = {}) {
+  return tseslint.config(
+    { ignores: ["dist", "build", "coverage", "**/*.gen.ts", ...ignores] },
+
+    js.configs.recommended,
+    ...tseslint.configs.recommendedTypeChecked,
+
+    {
+      files: ["**/*.{ts,tsx}"],
+      languageOptions: {
+        ecmaVersion: 2022,
+        globals: globals.browser,
+        parserOptions: {
+          projectService: true,
+          tsconfigRootDir: process.cwd(),
+        },
+      },
+      plugins: {
+        "react-hooks": reactHooks,
+        "react-refresh": reactRefresh,
+      },
+      rules: {
+        ...reactHooks.configs.recommended.rules,
+        "react-refresh/only-export-components": ["warn", { allowConstantExport: true }],
+
+        // --- DESIGN.md section 1: TypeScript is strict, and stays strict ---
+        "@typescript-eslint/no-explicit-any": "error",
+        "@typescript-eslint/no-unsafe-assignment": "error",
+        "@typescript-eslint/no-unsafe-member-access": "error",
+        "@typescript-eslint/consistent-type-imports": [
+          "error",
+          { fixStyle: "inline-type-imports" },
+        ],
+        "@typescript-eslint/no-floating-promises": "error",
+        "@typescript-eslint/no-misused-promises": "error",
+
+        // --- DESIGN.md section 4: structure ---
+        "no-restricted-imports": [
+          "error",
+          {
+            patterns: [
+              {
+                group: ["../../*"],
+                message:
+                  "Use the @/ alias instead of walking up more than one level. See DESIGN.md section 4.",
+              },
+              {
+                group: ["@radix-ui/*", "@base-ui-components/*"],
+                message:
+                  "Import primitives from @/components/ui/* instead. Direct primitive imports bypass the design system. See DESIGN.md section 3.",
+              },
+              {
+                group: ["moment", "dayjs"],
+                message: "Use date-fns. See DESIGN.md section 1.",
+              },
+            ],
+            paths: [
+              {
+                name: "react",
+                importNames: ["default"],
+                message:
+                  "Import named exports (useState, type ReactNode) rather than the React default export.",
+              },
+            ],
+          },
+        ],
+
+        // --- DESIGN.md section 2: state layering ---
+        // Server state belongs in TanStack Query, never in a Zustand store.
+        "no-restricted-syntax": [
+          "error",
+          {
+            // Both call shapes: create<S>((set) => ...) and the curried form
+            // create<S>()((set) => ...) that the Zustand TypeScript docs use.
+            // In the curried form the initializer is an argument of the *outer*
+            // call, so `callee.name` is undefined there and only
+            // `callee.callee.name` matches.
+            selector:
+              "CallExpression[callee.name='create'] CallExpression[callee.name='fetch'], CallExpression[callee.callee.name='create'] CallExpression[callee.name='fetch']",
+            message:
+              "Do not fetch inside a Zustand store. Server state belongs in TanStack Query. See DESIGN.md section 2.",
+          },
+          {
+            selector: "JSXAttribute[name.name='style']",
+            message:
+              "Use Tailwind utilities and theme tokens instead of inline styles. See DESIGN.md section 5.",
+          },
+        ],
+
+        // --- DESIGN.md section 6: quality floor ---
+        eqeqeq: ["error", "always", { null: "ignore" }],
+        "no-console": ["warn", { allow: ["warn", "error"] }],
+      },
+    },
+
+    // Vendored shadcn components — and the kit's own vendored components,
+    // like theme-provider.tsx exporting both ThemeProvider and useTheme —
+    // are not ours to police.
+    {
+      files: ["src/components/ui/**", "src/components/theme-provider.tsx"],
+      rules: {
+        "no-restricted-imports": "off",
+        "no-restricted-syntax": "off",
+        "react-refresh/only-export-components": "off",
+        "@typescript-eslint/no-unsafe-assignment": "off",
+        "@typescript-eslint/no-unsafe-member-access": "off",
+      },
+    },
+
+    // Generated API types are vendored too.
+    {
+      files: ["src/lib/api-types.ts"],
+      rules: { "@typescript-eslint/no-explicit-any": "off" },
+    },
+
+    // Config files run in Node and are not type-checked against the app project.
+    //
+    // disableTypeChecked carries its own `languageOptions` (parserOptions that
+    // switch the type-aware parser off), so it has to be spread *before* ours —
+    // spreading it after replaces the whole key and silently drops the Node
+    // globals, which shows up as no-undef on `process` in a .js config file.
+    {
+      files: ["*.config.{js,ts}"],
+      ...tseslint.configs.disableTypeChecked,
+      languageOptions: {
+        ...tseslint.configs.disableTypeChecked.languageOptions,
+        globals: globals.node,
+      },
+    },
+
+    prettier,
+  );
+}

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "@martinrun/frontend-config",
+  "version": "0.1.3",
+  "description": "Shared frontend conventions: ESLint, TypeScript and Prettier config for React + shadcn/ui projects.",
+  "license": "MIT",
+  "type": "module",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/MartinCa/frontend-kit.git"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "test": "node --test \"test/**/*.test.mjs\"",
+    "format": "prettier --write .",
+    "format:check": "prettier --check ."
+  },
+  "exports": {
+    "./eslint": "./eslint.config.js",
+    "./prettier": "./prettier.config.js",
+    "./tsconfig": "./tsconfig.base.json"
+  },
+  "files": [
+    "eslint.config.js",
+    "prettier.config.js",
+    "tsconfig.base.json",
+    "LICENSE"
+  ],
+  "peerDependencies": {
+    "eslint": ">=9",
+    "prettier": ">=3",
+    "prettier-plugin-tailwindcss": ">=0.6",
+    "typescript": ">=5.5"
+  },
+  "dependencies": {
+    "@eslint/js": "^10.0.0",
+    "eslint-config-prettier": "^10.0.0",
+    "eslint-plugin-react-hooks": "^7.0.0",
+    "eslint-plugin-react-refresh": "^0.5.0",
+    "globals": "^17.0.0",
+    "typescript-eslint": "^8.0.0"
+  },
+  "devDependencies": {
+    "eslint": "^10.9.1",
+    "prettier": "^3.9.6",
+    "prettier-plugin-tailwindcss": "^0.8.1",
+    "typescript": "^6.0.3"
+  }
+}

package/prettier.config.js

@@ -0,0 +1,9 @@
+/** @type {import("prettier").Config} */
+export default {
+  semi: true,
+  singleQuote: false,
+  trailingComma: "all",
+  printWidth: 100,
+  tabWidth: 2,
+  plugins: ["prettier-plugin-tailwindcss"],
+};

package/tsconfig.base.json

@@ -0,0 +1,31 @@
+{
+  "$schema": "https://json.schemastore.org/tsconfig",
+  "compilerOptions": {
+    "target": "ES2022",
+    "lib": ["ES2022", "DOM", "DOM.Iterable"],
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "jsx": "react-jsx",
+    "useDefineForClassFields": true,
+
+    "strict": true,
+    "noUncheckedIndexedAccess": true,
+    "noImplicitOverride": true,
+    "noFallthroughCasesInSwitch": true,
+    "noUnusedLocals": true,
+    "noUnusedParameters": true,
+
+    // The one relaxed strictness flag, and deliberately so: with it on, every
+    // optional prop spread into a shadcn component or a react-hook-form field
+    // needs `| undefined` written out, which is friction on vendored code we do
+    // not control. Turn it on per project if the project's own code benefits.
+    "exactOptionalPropertyTypes": false,
+
+    "verbatimModuleSyntax": true,
+    "isolatedModules": true,
+    "esModuleInterop": true,
+    "resolveJsonModule": true,
+    "skipLibCheck": true,
+    "noEmit": true
+  }
+}