@everysk/apps-devkit 0.1.0-beta.0

package/dist/vitest/index.js

@@ -0,0 +1,76 @@
+import { fileURLToPath, URL } from "node:url";
+import { defineConfig, mergeConfig } from "vitest/config";
+import react from "@vitejs/plugin-react";
+/**
+ * defineAppTestConfig
+ *
+ * The Vitest configuration every Everysk app shares:
+ *
+ * ```ts
+ * import { defineAppTestConfig } from "@everysk/apps-devkit/vitest";
+ * export default defineAppTestConfig();
+ * ```
+ *
+ * Standalone from the Vite config on purpose — the same split the template kept. The library
+ * build, the dev proxy and the React Compiler pass are irrelevant to tests; all they need is
+ * the React transform, the `@` alias and jsdom.
+ *
+ * Notable defaults:
+ *
+ * - `setupFiles` points at `@everysk/apps-sdk/test/setup`, which installs the jsdom gaps MUI
+ *   needs (matchMedia, ResizeObserver). It seeds no page globals: an app injects configuration
+ *   per test with `renderWithProviders(ui, { appId, appEnvironmentVar })`.
+ * - `testTimeout` is 30s, not Vitest's 5s. The template's default trips MUI transition-driven
+ *   tests under `--coverage`, and every app had to raise it by hand.
+ * - Coverage thresholds at 80% on all four counters, which the deploy gate enforces. `branches`
+ *   is listed explicitly: leaving it out does not inherit the others, it leaves that counter
+ *   unenforced, and an untested `if` is exactly what a coverage floor is there to catch. Barrels
+ *   are excluded at
+ *   exactly one level deep. A recursive glob would also swallow every `index.tsx` and quietly
+ *   drop real components out of the report — which is what happened while building the SDK.
+ *
+ * @param {ViteUserConfig} [overrides] - Merged over the preset with Vite's `mergeConfig`.
+ */
+export const defineAppTestConfig = (overrides = {}) => {
+    const preset = {
+        plugins: [react()],
+        resolve: {
+            alias: {
+                "@": fileURLToPath(new URL("./src", `file://${process.cwd()}/`)),
+            },
+        },
+        test: {
+            globals: true,
+            environment: "jsdom",
+            setupFiles: ["@everysk/apps-sdk/test/setup"],
+            css: false,
+            clearMocks: true,
+            restoreMocks: true,
+            include: ["src/**/*.{test,spec}.{ts,tsx}"],
+            testTimeout: 30_000,
+            coverage: {
+                provider: "v8",
+                reportsDirectory: "./coverage",
+                reporter: ["text", "html"],
+                include: ["src/**/*.{ts,tsx}"],
+                exclude: [
+                    "src/**/*.{test,spec}.{ts,tsx}",
+                    "src/test/**",
+                    "src/main.tsx",
+                    "src/index.ts",
+                    "src/*/index.ts",
+                    "src/**/types.ts",
+                    "src/types/**",
+                ],
+                thresholds: {
+                    lines: 80,
+                    functions: 80,
+                    statements: 80,
+                    branches: 80,
+                },
+            },
+        },
+    };
+    return defineConfig(mergeConfig(preset, overrides));
+};
+//# sourceMappingURL=index.js.map

package/dist/vitest/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/vitest/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,GAAG,EAAE,MAAM,UAAU,CAAC;AAE9C,OAAO,EAAE,YAAY,EAAE,WAAW,EAAuB,MAAM,eAAe,CAAC;AAE/E,OAAO,KAAK,MAAM,sBAAsB,CAAC;AAEzC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,MAAM,CAAC,MAAM,mBAAmB,GAAG,CAAC,YAA4B,EAAE,EAAE,EAAE;IAClE,MAAM,MAAM,GAAmB;QAC3B,OAAO,EAAE,CAAC,KAAK,EAAE,CAAC;QAElB,OAAO,EAAE;YACL,KAAK,EAAE;gBACH,GAAG,EAAE,aAAa,CAAC,IAAI,GAAG,CAAC,OAAO,EAAE,UAAU,OAAO,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC;aACnE;SACJ;QAED,IAAI,EAAE;YACF,OAAO,EAAE,IAAI;YACb,WAAW,EAAE,OAAO;YACpB,UAAU,EAAE,CAAC,8BAA8B,CAAC;YAC5C,GAAG,EAAE,KAAK;YACV,UAAU,EAAE,IAAI;YAChB,YAAY,EAAE,IAAI;YAClB,OAAO,EAAE,CAAC,+BAA+B,CAAC;YAC1C,WAAW,EAAE,MAAM;YACnB,QAAQ,EAAE;gBACN,QAAQ,EAAE,IAAI;gBACd,gBAAgB,EAAE,YAAY;gBAC9B,QAAQ,EAAE,CAAC,MAAM,EAAE,MAAM,CAAC;gBAC1B,OAAO,EAAE,CAAC,mBAAmB,CAAC;gBAC9B,OAAO,EAAE;oBACL,+BAA+B;oBAC/B,aAAa;oBACb,cAAc;oBACd,cAAc;oBACd,gBAAgB;oBAChB,iBAAiB;oBACjB,cAAc;iBACjB;gBACD,UAAU,EAAE;oBACR,KAAK,EAAE,EAAE;oBACT,SAAS,EAAE,EAAE;oBACb,UAAU,EAAE,EAAE;oBACd,QAAQ,EAAE,EAAE;iBACf;aACJ;SACJ;KACJ,CAAC;IAEF,OAAO,YAAY,CAAC,WAAW,CAAC,MAAM,EAAE,SAAS,CAAC,CAAC,CAAC;AACxD,CAAC,CAAC"}

package/package.json

@@ -0,0 +1,90 @@
+{
+  "name": "@everysk/apps-devkit",
+  "version": "0.1.0-beta.0",
+  "description": "Build-time presets for Everysk client applications: Vite, ESLint, Vitest, TypeScript and Prettier.",
+  "keywords": [
+    "everysk",
+    "vite",
+    "eslint",
+    "vitest",
+    "preset",
+    "config"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/everysk/apps-sdk.git",
+    "directory": "packages/apps-devkit"
+  },
+  "homepage": "https://github.com/everysk/apps-sdk/tree/main/packages/apps-devkit#readme",
+  "bugs": {
+    "url": "https://github.com/everysk/apps-sdk/issues"
+  },
+  "license": "MIT",
+  "type": "module",
+  "files": [
+    "dist",
+    "src",
+    "tsconfig",
+    "!src/**/*.test.ts"
+  ],
+  "exports": {
+    "./vite": {
+      "types": "./dist/vite/index.d.ts",
+      "import": "./dist/vite/index.js"
+    },
+    "./eslint": {
+      "types": "./dist/eslint/index.d.ts",
+      "import": "./dist/eslint/index.js"
+    },
+    "./vitest": {
+      "types": "./dist/vitest/index.d.ts",
+      "import": "./dist/vitest/index.js"
+    },
+    "./prettier": "./dist/prettier/index.json",
+    "./tsconfig": "./tsconfig/app.json",
+    "./tsconfig/node": "./tsconfig/node.json",
+    "./tsconfig/vitest": "./tsconfig/vitest.json",
+    "./package.json": "./package.json"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json && node ./scripts/copyAssets.js",
+    "lint": "eslint .",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage"
+  },
+  "dependencies": {
+    "@babel/core": "^7.29.7",
+    "@eslint/js": "^9.39.4",
+    "@rolldown/plugin-babel": "^0.2.3",
+    "@tailwindcss/vite": "^4.3.0",
+    "@vitejs/plugin-react": "^6.0.2",
+    "@vitest/coverage-v8": "^4.1.8",
+    "babel-plugin-react-compiler": "^1.0.0",
+    "eslint": "^9.39.4",
+    "eslint-config-prettier": "^10.1.8",
+    "eslint-plugin-prettier": "^5.5.6",
+    "eslint-plugin-react-hooks": "^7.1.1",
+    "eslint-plugin-react-refresh": "^0.5.2",
+    "globals": "^17.6.0",
+    "jsdom": "^29.1.1",
+    "prettier": "^3.8.3",
+    "tailwindcss": "^4.3.0",
+    "typescript": "^6.0.3",
+    "typescript-eslint": "^8.60.1",
+    "vite": "^8.0.16",
+    "vitest": "^4.1.8"
+  },
+  "devDependencies": {
+    "@types/babel__core": "^7.20.5",
+    "@types/node": "^25.9.1"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "sideEffects": false,
+  "engines": {
+    "node": ">=22",
+    "npm": ">=12"
+  }
+}

package/src/eslint/index.ts

@@ -0,0 +1,90 @@
+import js from "@eslint/js";
+import globals from "globals";
+import reactHooks from "eslint-plugin-react-hooks";
+import reactRefresh from "eslint-plugin-react-refresh";
+import tseslint from "typescript-eslint";
+import { defineConfig, globalIgnores } from "eslint/config";
+
+// Barrel bans applied to every file: faster dev startup and reliable tree-shaking.
+const noBarrelPaths = [
+    {
+        name: "@mui/material",
+        message:
+            "Avoid the barrel. Import from the deep path, e.g. `@mui/material/Button` or `@mui/material/styles`.",
+    },
+    {
+        name: "@mui/icons-material",
+        message: "Avoid the barrel. Import the specific icon, e.g. `@mui/icons-material/Search`.",
+    },
+];
+
+// Data-layer rule: pages and components reach data only through entity hooks.
+const dataLayerMessage =
+    "Data access only via entity hooks (@everysk/apps-sdk/<entity> or @/hooks/...). Pages and components must not call axios or an api module directly.";
+
+/**
+ * everyskConfig
+ *
+ * The ESLint configuration every Everysk app shares, so an app's `eslint.config.js` is:
+ *
+ * ```js
+ * import { everyskConfig } from "@everysk/apps-devkit/eslint";
+ * export default everyskConfig();
+ * ```
+ *
+ * It encodes the conventions that lint can actually check: no MUI barrel imports, and no
+ * direct data access from pages or components. The rules that lint cannot express — which
+ * subpath to import, which provider to wire — belong to the `everysk-apps` generator.
+ *
+ * @param {ReturnType<typeof defineConfig>} [extra] - Appended after the preset, so an app can
+ *   add or override rules for its own files.
+ */
+export const everyskConfig = (extra: ReturnType<typeof defineConfig> = []) =>
+    defineConfig([
+        globalIgnores(["dist", "coverage"]),
+        {
+            files: ["**/*.{ts,tsx}"],
+            extends: [
+                js.configs.recommended,
+                tseslint.configs.recommended,
+                reactHooks.configs.flat["recommended-latest"],
+                reactRefresh.configs.vite,
+            ],
+            languageOptions: {
+                ecmaVersion: 2020,
+                globals: globals.browser,
+            },
+            rules: {
+                "@typescript-eslint/no-restricted-imports": ["error", { paths: noBarrelPaths }],
+            },
+        },
+        {
+            // A same-named rule REPLACES the base one for these files rather than merging, so
+            // the barrel bans are repeated here.
+            files: ["src/pages/**/*.{ts,tsx}", "src/components/**/*.{ts,tsx}"],
+            rules: {
+                "@typescript-eslint/no-restricted-imports": [
+                    "error",
+                    {
+                        paths: [
+                            ...noBarrelPaths,
+                            { name: "axios", message: dataLayerMessage },
+                            { name: "@/api", message: dataLayerMessage },
+                        ],
+                        patterns: [{ group: ["@/api/*"], message: dataLayerMessage }],
+                    },
+                ],
+            },
+        },
+        {
+            // Tests may reach the data layer directly, to mock an api module or build axios
+            // stubs. Only the barrel bans remain, and the Fast Refresh rule is relaxed for
+            // test utilities that export helpers.
+            files: ["src/**/*.{test,spec}.{ts,tsx}", "src/test/**/*.{ts,tsx}"],
+            rules: {
+                "@typescript-eslint/no-restricted-imports": ["error", { paths: noBarrelPaths }],
+                "react-refresh/only-export-components": "off",
+            },
+        },
+        ...extra,
+    ]);

package/src/prettier/index.json

@@ -0,0 +1,8 @@
+{
+    "semi": true,
+    "singleQuote": false,
+    "trailingComma": "all",
+    "printWidth": 100,
+    "tabWidth": 4,
+    "endOfLine": "lf"
+}

package/src/vite/index.ts

@@ -0,0 +1,82 @@
+import { fileURLToPath, URL } from "node:url";
+
+import { defineConfig, loadEnv, mergeConfig, type UserConfig } from "vite";
+
+import react, { reactCompilerPreset } from "@vitejs/plugin-react";
+import babel from "@rolldown/plugin-babel";
+import tailwindcss from "@tailwindcss/vite";
+
+import { createDevServerProxy } from "./serverProxy.js";
+import { envVarsLocationPlugin } from "./plugins/envVarsLocation.js";
+import { serveDevAppConfigPlugin } from "./plugins/serveDevAppConfig.js";
+
+export { createDevServerProxy } from "./serverProxy.js";
+export { envVarsLocationPlugin } from "./plugins/envVarsLocation.js";
+export { serveDevAppConfigPlugin } from "./plugins/serveDevAppConfig.js";
+
+/**
+ * defineAppConfig
+ *
+ * The Vite configuration every Everysk app shares, so an app's own `vite.config.ts` is three
+ * lines instead of a copy that drifts:
+ *
+ * ```ts
+ * import { defineAppConfig } from "@everysk/apps-devkit/vite";
+ * export default defineAppConfig();
+ * ```
+ *
+ * What it sets up:
+ *
+ * - `base: "./"` and `envDir` at `PROJECT_ROOT`, because an app is built from
+ *   `apps/<name>/project/` but its `.env` lives at the repository root.
+ * - The `@` alias to the app's `src/`.
+ * - The dev server on `PORT` (default 5173, `strictPort`), with the `/api` proxy that
+ *   authenticates against `EVERYSK_API_URL` using OAuth2 client credentials.
+ * - React with the compiler preset, Tailwind, and the two plugins that carry the app's
+ *   `config.json` `env_vars` into the page — a meta tag in build, `/app-config.json` in dev.
+ *
+ * @param {UserConfig} [overrides] - Merged over the preset with Vite's own `mergeConfig`, so
+ *   arrays (plugins, aliases) are concatenated rather than replaced.
+ */
+export const defineAppConfig = (overrides: UserConfig = {}) =>
+    defineConfig(({ mode, command }) => {
+        // The app is built from apps/<name>/project, but .env lives at the repo root; the
+        // devcontainer exports PROJECT_ROOT for exactly this.
+        const root = process.env.PROJECT_ROOT ?? process.cwd();
+
+        const env = loadEnv(mode, root, "");
+        Object.assign(process.env, env);
+
+        const preset: UserConfig = {
+            base: "./",
+            envDir: root,
+
+            resolve: {
+                alias: {
+                    "@": fileURLToPath(new URL("./src", `file://${process.cwd()}/`)),
+                },
+            },
+
+            build: {
+                outDir: "./dist",
+                emptyOutDir: true,
+            },
+
+            server: {
+                host: true,
+                port: Number(process.env.PORT) || 5173,
+                strictPort: true,
+                proxy: command === "serve" ? createDevServerProxy() : undefined,
+            },
+
+            plugins: [
+                react(),
+                babel({ presets: [reactCompilerPreset()] }),
+                tailwindcss(),
+                envVarsLocationPlugin(),
+                serveDevAppConfigPlugin(),
+            ],
+        };
+
+        return mergeConfig(preset, overrides);
+    });

package/src/vite/plugins/envVarsLocation.ts

@@ -0,0 +1,11 @@
+import type { Plugin } from "vite";
+
+export function envVarsLocationPlugin(): Plugin {
+  return {
+    name: "env_vars_location",
+    apply: "build",
+    transformIndexHtml() {
+      return [{ tag: "meta", attrs: { name: "app-config" }, injectTo: "head" }];
+    },
+  };
+}

package/src/vite/plugins/serveDevAppConfig.ts

@@ -0,0 +1,51 @@
+import path from "node:path";
+import fs from "node:fs/promises";
+
+import type { Plugin } from "vite";
+
+/**
+ * In production the platform injects `window.APP_CONFIG` from the app's `config.json` `env_vars`
+ * (via the `app-config` meta tag added by the build plugin). There is no platform in dev, so this
+ * plugin serves that same `env_vars` object at `/app-config.json`, read from the app's `config.json`
+ * one level up from the Vite root (apps/<name>/config.json, sibling of project/). `main.tsx` fetches
+ * it on bootstrap and merges it into `window.APP_CONFIG`, so dev mirrors production from a single
+ * source of truth — there is no separate dev config file to keep in sync.
+ *
+ * Because `config.json` lives outside the Vite root it is not watched by default, and `main.tsx`
+ * only reads it once at bootstrap. So we also add it to the watcher and trigger a full page reload
+ * on change — a full reload re-runs the bootstrap fetch, picking up edits to `env_vars` live.
+ */
+export function serveDevAppConfigPlugin(): Plugin {
+  return {
+    name: "serve-dev-app-config",
+    apply: "serve",
+    configureServer(server) {
+      // apps/<name>/config.json — one level up from the Vite root (the app's project/ dir).
+      const configPath = path.resolve(process.cwd(), "..", "config.json");
+
+      server.middlewares.use(async (req, res, next) => {
+        if (req.url !== "/app-config.json") return next();
+
+        try {
+          const content = await fs.readFile(configPath, "utf-8");
+          const envVars = (JSON.parse(content).env_vars ?? {}) as Record<string, unknown>;
+
+          res.setHeader("Content-Type", "application/json; charset=utf-8");
+          res.statusCode = 200;
+          res.end(JSON.stringify(envVars));
+        } catch {
+          res.statusCode = 404;
+          res.end();
+        }
+      });
+
+      // config.json is outside the Vite root, so watch it explicitly and full-reload on change.
+      server.watcher.add(configPath);
+      server.watcher.on("change", (file) => {
+        if (path.resolve(file) === configPath) {
+          server.hot.send({ type: "full-reload" });
+        }
+      });
+    },
+  };
+}

package/src/vite/serverProxy.ts

@@ -0,0 +1,88 @@
+import type { ProxyOptions } from "vite";
+
+// Refresh the OAuth2 token this many ms before it actually expires, so an in-flight
+// request never races a just-expired token.
+const REFRESH_SKEW_MS = 60_000;
+
+/**
+ * createDevServerProxy — Vite dev proxy for `/api`, authenticated with OAuth2 client credentials.
+ *
+ * Forwards `/api/*` to `EVERYSK_API_URL` (stripping the `/api` prefix) and injects an
+ * `Authorization: Bearer <access_token>` header. The token is obtained from
+ * `${EVERYSK_API_URL}/oauth2/token` with the `client_credentials` grant, cached in memory, and
+ * refreshed in the background shortly before it expires. It is fetched eagerly at startup so a
+ * token is ready before the first API call.
+ *
+ * @returns {Record<string, string | ProxyOptions>} The Vite `server.proxy` config for `/api`.
+ * @throws {Error} If `EVERYSK_API_URL`, `EVERYSK_API_CLIENT_ID`, or `EVERYSK_API_CLIENT_SECRET`
+ *   is missing.
+ */
+export function createDevServerProxy(): Record<string, string | ProxyOptions> {
+  const EVERYSK_API_URL = process.env.EVERYSK_API_URL;
+  if (!EVERYSK_API_URL) throw new Error("EVERYSK_API_URL must be set.");
+
+  const clientId = process.env.EVERYSK_API_CLIENT_ID;
+  const clientSecret = process.env.EVERYSK_API_CLIENT_SECRET;
+  if (!clientId || !clientSecret) {
+    throw new Error("EVERYSK_API_CLIENT_ID and EVERYSK_API_CLIENT_SECRET must be set (OAuth2 client credentials).");
+  }
+  // Captured into an object so the narrowed `string` type survives inside the async closure below.
+  const credentials = { clientId, clientSecret };
+
+  const tokenUrl = `${EVERYSK_API_URL.replace(/\/$/, "")}/oauth2/token`;
+  let accessToken: string | null = null;
+  let refreshTimer: ReturnType<typeof setTimeout> | null = null;
+
+  /**
+   * refreshToken — fetch a fresh access token and schedule the next refresh before it expires.
+   *
+   * @returns {Promise<void>} Resolves once `accessToken` is updated.
+   * @throws {Error} If the token request fails or returns no `access_token`.
+   */
+  async function refreshToken(): Promise<void> {
+    const res = await fetch(tokenUrl, {
+      method: "POST",
+      headers: { "Content-Type": "application/x-www-form-urlencoded" },
+      body: new URLSearchParams({
+        grant_type: "client_credentials",
+        client_id: credentials.clientId,
+        client_secret: credentials.clientSecret,
+      }),
+    });
+    if (!res.ok) throw new Error(`OAuth2 token request failed: ${res.status} ${res.statusText}`);
+
+    const data = (await res.json()) as { access_token?: string; expires_in?: number };
+    if (!data.access_token) throw new Error("OAuth2 token response had no access_token.");
+    accessToken = data.access_token;
+
+    const ttlMs = (data.expires_in ?? 3600) * 1000;
+    if (refreshTimer) clearTimeout(refreshTimer);
+    refreshTimer = setTimeout(() => {
+      void refreshToken().catch((error) => console.error("[dev proxy] OAuth2 token refresh failed:", error));
+    }, Math.max(ttlMs - REFRESH_SKEW_MS, 30_000));
+    refreshTimer.unref?.();
+  }
+
+  // Warm the token before the first request; a failure is logged, not fatal (the request will 401).
+  void refreshToken().catch((error) => console.error("[dev proxy] initial OAuth2 token fetch failed:", error));
+
+  return {
+    "/api": {
+      target: EVERYSK_API_URL,
+      changeOrigin: true,
+      xfwd: true,
+      rewrite: (p) => p.replace(/^\/api(?=\/|$)/, ""),
+
+      configure: (proxy) => {
+        proxy.on("proxyReq", (proxyReq) => {
+          proxyReq.removeHeader("origin");
+          proxyReq.removeHeader("referer");
+
+          if (accessToken) {
+            proxyReq.setHeader("Authorization", `Bearer ${accessToken}`);
+          }
+        });
+      },
+    },
+  };
+}

package/src/vitest/index.ts

@@ -0,0 +1,81 @@
+import { fileURLToPath, URL } from "node:url";
+
+import { defineConfig, mergeConfig, type ViteUserConfig } from "vitest/config";
+
+import react from "@vitejs/plugin-react";
+
+/**
+ * defineAppTestConfig
+ *
+ * The Vitest configuration every Everysk app shares:
+ *
+ * ```ts
+ * import { defineAppTestConfig } from "@everysk/apps-devkit/vitest";
+ * export default defineAppTestConfig();
+ * ```
+ *
+ * Standalone from the Vite config on purpose — the same split the template kept. The library
+ * build, the dev proxy and the React Compiler pass are irrelevant to tests; all they need is
+ * the React transform, the `@` alias and jsdom.
+ *
+ * Notable defaults:
+ *
+ * - `setupFiles` points at `@everysk/apps-sdk/test/setup`, which installs the jsdom gaps MUI
+ *   needs (matchMedia, ResizeObserver). It seeds no page globals: an app injects configuration
+ *   per test with `renderWithProviders(ui, { appId, appEnvironmentVar })`.
+ * - `testTimeout` is 30s, not Vitest's 5s. The template's default trips MUI transition-driven
+ *   tests under `--coverage`, and every app had to raise it by hand.
+ * - Coverage thresholds at 80% on all four counters, which the deploy gate enforces. `branches`
+ *   is listed explicitly: leaving it out does not inherit the others, it leaves that counter
+ *   unenforced, and an untested `if` is exactly what a coverage floor is there to catch. Barrels
+ *   are excluded at
+ *   exactly one level deep. A recursive glob would also swallow every `index.tsx` and quietly
+ *   drop real components out of the report — which is what happened while building the SDK.
+ *
+ * @param {ViteUserConfig} [overrides] - Merged over the preset with Vite's `mergeConfig`.
+ */
+export const defineAppTestConfig = (overrides: ViteUserConfig = {}) => {
+    const preset: ViteUserConfig = {
+        plugins: [react()],
+
+        resolve: {
+            alias: {
+                "@": fileURLToPath(new URL("./src", `file://${process.cwd()}/`)),
+            },
+        },
+
+        test: {
+            globals: true,
+            environment: "jsdom",
+            setupFiles: ["@everysk/apps-sdk/test/setup"],
+            css: false,
+            clearMocks: true,
+            restoreMocks: true,
+            include: ["src/**/*.{test,spec}.{ts,tsx}"],
+            testTimeout: 30_000,
+            coverage: {
+                provider: "v8",
+                reportsDirectory: "./coverage",
+                reporter: ["text", "html"],
+                include: ["src/**/*.{ts,tsx}"],
+                exclude: [
+                    "src/**/*.{test,spec}.{ts,tsx}",
+                    "src/test/**",
+                    "src/main.tsx",
+                    "src/index.ts",
+                    "src/*/index.ts",
+                    "src/**/types.ts",
+                    "src/types/**",
+                ],
+                thresholds: {
+                    lines: 80,
+                    functions: 80,
+                    statements: 80,
+                    branches: 80,
+                },
+            },
+        },
+    };
+
+    return defineConfig(mergeConfig(preset, overrides));
+};

package/tsconfig/app.json

@@ -0,0 +1,35 @@
+{
+  "$comment": [
+    "Base TypeScript options for an Everysk app. Extend it from the app's tsconfig.app.json:",
+    "  { \"extends\": \"@everysk/apps-devkit/tsconfig\", \"include\": [\"src\"] }",
+    "",
+    "`paths` is deliberately NOT set here. TypeScript resolves the paths of a config relative",
+    "to the file that DECLARES them, so an `@/*` mapping written in this package would point",
+    "at this package's own src, not the app's. Each app declares its own:",
+    "  \"compilerOptions\": { \"paths\": { \"@/*\": [\"./src/*\"] } }"
+  ],
+  "compilerOptions": {
+    "target": "ES2022",
+    "useDefineForClassFields": true,
+    "lib": ["ES2022", "DOM", "DOM.Iterable"],
+    "module": "ESNext",
+    "types": ["vite/client"],
+    "skipLibCheck": true,
+
+    /* Bundler mode */
+    "moduleResolution": "bundler",
+    "allowImportingTsExtensions": true,
+    "verbatimModuleSyntax": true,
+    "moduleDetection": "force",
+    "noEmit": true,
+    "jsx": "react-jsx",
+
+    /* Linting */
+    "strict": true,
+    "noUnusedLocals": true,
+    "noUnusedParameters": true,
+    "erasableSyntaxOnly": true,
+    "noFallthroughCasesInSwitch": true,
+    "noUncheckedSideEffectImports": true
+  }
+}

package/tsconfig/node.json

@@ -0,0 +1,25 @@
+{
+  "$comment": "For an app's build-time files (vite.config.ts, vitest.config.ts). Extend with \"include\".",
+  "compilerOptions": {
+    "target": "ES2023",
+    "lib": ["ES2023"],
+    "module": "ESNext",
+    "types": ["node"],
+    "skipLibCheck": true,
+
+    /* Bundler mode */
+    "moduleResolution": "bundler",
+    "allowImportingTsExtensions": true,
+    "verbatimModuleSyntax": true,
+    "moduleDetection": "force",
+    "noEmit": true,
+
+    /* Linting */
+    "strict": true,
+    "noUnusedLocals": true,
+    "noUnusedParameters": true,
+    "erasableSyntaxOnly": true,
+    "noFallthroughCasesInSwitch": true,
+    "noUncheckedSideEffectImports": true
+  }
+}

package/tsconfig/vitest.json

@@ -0,0 +1,10 @@
+{
+  "$comment": [
+    "For an app's test files. Extend it from the app's tsconfig.vitest.json, which must also",
+    "re-declare `paths` — see the note in app.json."
+  ],
+  "extends": "./app.json",
+  "compilerOptions": {
+    "types": ["vitest/globals", "@testing-library/jest-dom", "node", "vite/client"]
+  }
+}