@devbie/style-guide 0.0.0-stage → 1.1.0

package/README.md

@@ -1,3 +1,74 @@
-# Temporary Holding Version
+# @devbie/style-guide
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Single source of truth for code style across the devbie ecosystem
+(newbie / fewbie / nightwatch / apits). See ADR-010 in `worldzhy/newbie`.
+
+## Exports
+
+| Entry                                | Contents                                                       |
+| ------------------------------------ | -------------------------------------------------------------- |
+| `@devbie/style-guide/prettier`       | Canonical prettier config (all repos)                          |
+| `@devbie/style-guide/eslint/backend` | eslint flat standard for Nest/Node TypeScript backends         |
+| `@devbie/style-guide/eslint/frontend`| eslint flat standard for frontend repos (TS + React + a11y)    |
+| `@devbie/style-guide/eslint/next`    | Frontend standard + canonical Next.js rules (overlay)          |
+
+## Which entry each repo uses
+
+| Repo                                                                              | eslint entry |
+| --------------------------------------------------------------------------------- | ------------ |
+| newbie, newbie-starter, nightwatch-backend, newbie-modules, apits                   | `backend`    |
+| fewbie                                                                            | `frontend`   |
+| fewbie-starter, nightwatch-frontend                                                | `next`       |
+
+`next` is the `frontend` standard plus `eslint-config-next`, so Next.js
+applications and the rest of the frontend group never drift on the shared
+part. `eslint-config-next` requires the `next` package at load time, which is
+why repos without a Next runtime (fewbie) use `frontend` instead.
+
+## Usage
+
+### prettier
+
+Delete any local `.prettierrc` and reference the shared config in
+`package.json`:
+
+```json
+{
+  "prettier": "@devbie/style-guide/prettier"
+}
+```
+
+`.prettierignore` stays repo-local: it lists repo-specific build artifacts,
+not style decisions.
+
+### eslint (flat config)
+
+`eslint.config.mjs` in the consumer repo:
+
+```js
+import backend from "@devbie/style-guide/eslint/backend";
+// frontend repos: import frontend from "@devbie/style-guide/eslint/frontend";
+// Next.js apps:   import next from "@devbie/style-guide/eslint/next";
+
+export default [
+  ...backend,
+  // Repo-specific rules and ignores go here.
+];
+```
+
+Consumers need `eslint` (^9 or ^10), `prettier` (^3.9.9) and `typescript`
+installed as their own dev dependencies (declared as peers of this package).
+
+## Version policy
+
+All devbie packages stay on the 1.x line until the ecosystem launches;
+breaking style changes bump minor, not major. Dependency major upgrades of
+prettier/eslint follow the ecosystem-wide major-freeze policy: not by
+default, only as a deliberate milestone.
+
+## Changelog
+
+- 1.1.0 — entries renamed to `backend` / `frontend` and layered: `core` is
+  internal, `frontend` is framework-independent (React rules only), `next`
+  adds the canonical Next.js rule set. `nest` was replaced by `backend`.
+- 1.0.0 — initial release (`prettier`, `eslint/nest`, `eslint/next`).

package/eslint/backend.js

@@ -0,0 +1,15 @@
+import core from "./core.js";
+import prettierConfig from "eslint-config-prettier";
+
+/**
+ * Backend standard for the devbie ecosystem.
+ *
+ * Consumers: newbie, newbie-starter, nightwatch-backend, newbie-modules,
+ * apits. All of them are Nest/Node TypeScript codebases; the language-level
+ * rules live in `core` so the backend and frontend standards never drift on
+ * the shared part.
+ *
+ * Repo-specific rules and ignores belong in the consumer's own
+ * eslint.config.mjs, spread after this entry.
+ */
+export default [...core, prettierConfig];

package/eslint/core.js

@@ -0,0 +1,30 @@
+import tseslint from "typescript-eslint";
+
+/**
+ * Language-level baseline shared by every devbie codebase.
+ *
+ * Formatting rules (quotes, eol-last, trailing spaces, ...) are deliberately
+ * absent: prettier owns formatting. Every public entry appends
+ * eslint-config-prettier last so no plugin can re-enable eslint formatting
+ * rules afterwards.
+ *
+ * Internal entry: consumers import `backend`, `frontend` or `next`, never
+ * this file.
+ */
+export default [...tseslint.configs.recommended, {
+  rules: {
+    "@typescript-eslint/no-explicit-any": "off",
+    "@typescript-eslint/no-unused-vars": [
+      "error",
+      { argsIgnorePattern: "^_", varsIgnorePattern: "^_", caughtErrorsIgnorePattern: "^_" },
+    ],
+
+    // Code-quality rules carried over from the legacy gts-derived config.
+    "block-scoped-var": "error",
+    eqeqeq: ["error", "always", { null: "ignore" }],
+    "no-var": "error",
+    "prefer-const": "error",
+    "prefer-arrow-callback": "error",
+    "no-restricted-properties": ["error", { object: "describe", property: "only" }, { object: "it", property: "only" }],
+  },
+}];

package/eslint/frontend.js

@@ -0,0 +1,28 @@
+import core from "./core.js";
+import prettierConfig from "eslint-config-prettier";
+import react from "eslint-plugin-react";
+import reactHooks from "eslint-plugin-react-hooks";
+import jsxA11y from "eslint-plugin-jsx-a11y";
+
+/**
+ * Frontend standard for the devbie ecosystem.
+ *
+ * Consumers: fewbie, fewbie-starter, nightwatch-frontend.
+ *
+ * Deliberately independent of `eslint-config-next`: that package requires the
+ * `next` package to be installed (its parser is `next/dist/compiled/babel
+ * /eslint-parser`), while fewbie ships a Node CLI and has no Next runtime.
+ * Next.js applications layer `@devbie/style-guide/eslint/next` on top of this
+ * standard instead, so every frontend repo shares the same base rules.
+ *
+ * Repo-specific rules and ignores belong in the consumer's own
+ * eslint.config.mjs, spread after this entry.
+ */
+export default [
+  ...core,
+  react.configs.flat.recommended,
+  react.configs.flat["jsx-runtime"],
+  reactHooks.configs["recommended-latest"],
+  jsxA11y.flatConfigs.recommended,
+  prettierConfig,
+];

package/eslint/next.js

@@ -0,0 +1,22 @@
+import { defineConfig, globalIgnores } from "eslint/config";
+import frontend from "./frontend.js";
+import nextVitals from "eslint-config-next/core-web-vitals";
+import nextTs from "eslint-config-next/typescript";
+import prettierConfig from "eslint-config-prettier";
+
+/**
+ * Next.js overlay for Next.js applications
+ * (nightwatch-frontend, fewbie-starter).
+ *
+ * It extends the shared frontend standard with the canonical Next rule set.
+ * This entry can only be loaded where the `next` package is installed, which
+ * is why frontend repos without a Next runtime use `frontend` instead.
+ */
+export default defineConfig([
+  ...frontend,
+  ...nextVitals,
+  ...nextTs,
+  prettierConfig,
+  // Framework-generated artifacts; consumers append their own ignores.
+  globalIgnores([".next/**", "out/**", "build/**", "next-env.d.ts"]),
+]);

package/package.json

@@ -1,6 +1,35 @@
 {
   "name": "@devbie/style-guide",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.1.0",
+  "description": "Single source of truth for devbie ecosystem code style: shared prettier config and eslint flat standards (backend, frontend, next)",
+  "license": "MIT",
+  "author": "worldzhy",
+  "type": "module",
+  "exports": {
+    "./prettier": "./prettier.js",
+    "./eslint/backend": "./eslint/backend.js",
+    "./eslint/frontend": "./eslint/frontend.js",
+    "./eslint/next": "./eslint/next.js",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "prettier.js",
+    "eslint"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "eslint-config-next": "^16.4.2",
+    "eslint-config-prettier": "^10.1.8",
+    "eslint-plugin-jsx-a11y": "^6.10.0",
+    "eslint-plugin-react": "^7.37.0",
+    "eslint-plugin-react-hooks": "^7.1.0",
+    "typescript-eslint": "^8.71.2"
+  },
+  "peerDependencies": {
+    "eslint": "^9.0.0 || ^10.0.0",
+    "prettier": "^3.9.9",
+    "typescript": ">=5.0.0"
+  }
+}

package/prettier.js

@@ -0,0 +1,29 @@
+/**
+ * Canonical prettier config for the devbie ecosystem.
+ * Consumers reference it via `"prettier": "@devbie/style-guide/prettier"`
+ * in their package.json instead of keeping a local .prettierrc copy.
+ *
+ * @type {import("prettier").Config}
+ */
+export default {
+  printWidth: 120,
+  tabWidth: 2,
+  useTabs: false,
+  semi: true,
+  singleQuote: false,
+  jsxSingleQuote: false,
+  quoteProps: "as-needed",
+  trailingComma: "all",
+  bracketSpacing: true,
+  bracketSameLine: false,
+  arrowParens: "always",
+  singleAttributePerLine: false,
+  objectWrap: "preserve",
+  htmlWhitespaceSensitivity: "css",
+  embeddedLanguageFormatting: "auto",
+  endOfLine: "lf",
+  proseWrap: "preserve",
+  insertPragma: false,
+  requirePragma: false,
+  experimentalTernaries: false,
+};