config-vp 1.0.0 → 1.2.0

package/README.md

@@ -10,7 +10,7 @@ One shared [vite-plus](https://viteplus.dev) config for all your packages. Pick
 - **Pre-commit checks** — staged files are checked and auto-fixed.
 - **VSCode setup** — a one-command task to wire up the oxc extension at your workspace root.
 
-Everything is opinionated and works out of the box. You can still override or extend any piece (see [Customizing](#customizing)).
+Everything is opinionated and works out of the box. You can still customize any piece (see [Customizing](#customizing)).
 
 ## Prerequisites
 
@@ -47,13 +47,13 @@ This also pulls in everything the config needs (`oxlint`, `oxfmt`, and the lint
 **2. Create `vite.config.ts`:**
 
 ```ts
-import { defineConfig } from 'config-vp';
+import { defineVitePlusConfig } from 'config-vp';
 
-const config = defineConfig({ type: 'lib' });
+const config = defineVitePlusConfig({ type: 'lib' });
 export default config;
 ```
 
-> **Important:** Assign to a `const` and export it — don't write `export default defineConfig(...)` inline. `vp` reads your default export statically to discover tasks; a direct call hides them and `vp run` reports "Task not found". See [Troubleshooting](#troubleshooting).
+> **Important:** Assign to a `const` and export it — don't write `export default defineVitePlusConfig(...)` inline. `vp` reads your default export statically to discover tasks; a direct call hides them and `vp run` reports "Task not found". See [Troubleshooting](#troubleshooting).
 
 **3. Run something:**
 
@@ -81,36 +81,34 @@ Set `type` to match what you're building. It drives Vue lint rules, library pack
 
 ### Recipes
 
-**Library** — dual ESM + CJS output:
+Customize with the `config` hook — it receives the fully built config (see [Customizing](#customizing)).
+
+**Plain package** — lint + format + tests only, no build/dev (e.g. a config or scripts-only package). Just call `defineVitePlusConfig()` with no `type`:
 
 ```ts
-import { defineConfig } from 'config-vp';
+import { defineVitePlusConfig } from 'config-vp';
 
-const config = defineConfig({
-  type: 'lib',
-  overrides: {
-    pack: {
-      entry: ['src/index.ts'],
-      format: ['esm', 'cjs'],
-    },
-  },
-});
+const config = defineVitePlusConfig();
 export default config;
 ```
 
-**Vue library** — same, with `type: 'lib:vue'` for SFC/template lint rules.
+**Vue app** — a Vite-based Vue application, with plugins and a path alias:
 
 ```ts
-import { defineConfig } from 'config-vp';
-
-const config = defineConfig({
-  type: 'lib:vue',
-  overrides: {
-    pack: {
-      entry: ['src/index.ts'],
-      format: ['esm', 'cjs'],
+import vue from '@vitejs/plugin-vue';
+import { defineVitePlusConfig } from 'config-vp';
+import { fileURLToPath, URL } from 'node:url';
+import vueDevTools from 'vite-plugin-vue-devtools';
+
+const config = defineVitePlusConfig({
+  type: 'vue',
+  config: c => ({
+    ...c,
+    plugins: [vue(), vueDevTools()],
+    resolve: {
+      alias: { '@': fileURLToPath(new URL('./src', import.meta.url)) },
     },
-  },
+  }),
 });
 export default config;
 ```
@@ -120,11 +118,11 @@ export default config;
 ```ts
 // nuxt.config.vite.ts
 import type { NuxtConfig } from 'nuxt/schema';
-import { defineConfig } from 'config-vp';
+import { defineVitePlusConfig } from 'config-vp';
 
-export const vite = defineConfig({
+export const vite = defineVitePlusConfig({
   type: 'nuxt:spa', // or 'nuxt:ssr'
-  overrides: {
+  config: c => {
     // any Vite/vite-plus options the app needs, e.g. plugins, define, test, …
   },
 }) as NuxtConfig['vite'];
@@ -138,14 +136,41 @@ import { vite } from './nuxt.config.vite';
 export default defineNuxtConfig({ vite });
 ```
 
-The `export const vite = …` form is itself a const export, so `vp` discovers any `run.tasks` you add through `overrides.run`.
+The `export const vite = …` form is itself a const export, so `vp` discovers any tasks you add in the `config` hook.
 
-**Plain package** — lint + format + tests only, no build/dev (e.g. a config or scripts-only package). Just call `defineConfig()` with no `type`:
+**Library** — dual ESM + CJS output:
 
 ```ts
-import { defineConfig } from 'config-vp';
+import { defineVitePlusConfig } from 'config-vp';
 
-const config = defineConfig();
+const config = defineVitePlusConfig({
+  type: 'lib',
+  config: c => {
+    c.pack = {
+      ...c.pack,
+      entry: ['src/index.ts'],
+      format: ['esm', 'cjs'],
+    };
+  },
+});
+export default config;
+```
+
+**Vue library** — same, with `type: 'lib:vue'` for SFC/template lint rules.
+
+```ts
+import { defineVitePlusConfig } from 'config-vp';
+
+const config = defineVitePlusConfig({
+  type: 'lib:vue',
+  config: c => {
+    c.pack = {
+      ...c.pack,
+      entry: ['src/index.ts'],
+      format: ['esm', 'cjs'],
+    };
+  },
+});
 export default config;
 ```
 
@@ -172,6 +197,8 @@ Run any task with `vp run <task>`. Tasks are cached and run in dependency order
 | `dev` | any `type` | see [Project types](#project-types) |
 | `release` | `lib*` types | `vp check --fix && vp test --run --passWithNoTests && vp pack && vpx bumpp && pnpm publish` |
 
+> All built-in tasks are emitted as objects, so the `config` hook can tweak one in place — e.g. `c.run.tasks.release.command = '…'`.
+
 **Workspace root only:**
 
 | Task           | Command           |
@@ -188,81 +215,114 @@ Run any task with `vp run <task>`. Tasks are cached and run in dependency order
 
 ## Customizing
 
-Two knobs, same shape — they differ only in how they merge:
-
-- **`overrides`** — _replace_ semantics. Your values overwrite the defaults. Applied first.
-- **`extends`** — _additive_ semantics. Arrays concatenate, objects deep-merge. Applied last, so it's never clobbered by an override.
+There's one customization hook: **`config`**. It receives the fully built config — lint, fmt, staged, run tasks, and (for `lib*`) pack, all already populated — and you change whatever you want with plain JS. Mutate it in place, or return a new object (a returned value wins; otherwise the mutated argument is used). It's fully typed, so autocomplete shows you exactly what's there.
 
 ```ts
-const config = defineConfig({
+const config = defineVitePlusConfig({
   type: 'lib',
-  overrides: {
-    // Replace the pack entry point entirely
-    pack: {
+  config: c => {
+    c.pack = {
+      ...c.pack,
       entry: ['src/index.ts'],
       format: ['esm', 'cjs'],
-    },
-  },
-  extends: {
-    // Add to the lint config without losing built-ins
-    lint: {
-      rules: { 'no-console': 'error' },
-    },
+    }; // tweak packaging
+    c.lint.rules['no-console'] = 'error'; // add a lint rule (base rules stay)
+    c.run.tasks.release.command = 'my-release'; // change a built-in task
   },
 });
 export default config;
 ```
 
-> `lint` is **always** deep-merged (never fully replaced), even under `overrides` — so you can't accidentally wipe the base ruleset.
+Because you hold the real config, there are no merge semantics to learn — you decide what to keep (`{ ...c.pack, … }`) and what to replace (`c.pack = { … }`). To drop something, delete it: `delete c.pack` (skip packaging), `delete c.run.tasks.release`.
+
+### Mutate or return
+
+The hook works two ways — use whichever reads better:
+
+```ts
+// Mutate in place and return nothing — best for a few targeted tweaks:
+defineVitePlusConfig({
+  type: 'lib',
+  config: c => {
+    c.pack = {
+      ...c.pack,
+      entry: ['src/index.ts'],
+    };
+  },
+});
+
+// Return a new object — best when you want to build the result explicitly:
+defineVitePlusConfig({
+  type: 'lib',
+  config: c => ({
+    ...c,
+    pack: {
+      ...c.pack,
+      entry: ['src/index.ts'],
+    },
+  }),
+});
+```
+
+A returned value wins; if you return nothing, the mutated argument is used. Don't do both.
 
 ### Your existing Vite config goes here
 
-`overrides` and `extends` accept **any** vite-plus `UserConfig` field, not just config-vp's own keys. So a whole normal Vite config — `plugins`, `resolve`, `define`, `server`, `optimizeDeps`, `worker`, `test`, `build`, `run.tasks`, … — drops straight into `extends` (additive) or `overrides` (replacing). There's nothing config-vp-specific to learn: keep writing Vite config, just nest it.
+Anything in a normal Vite / vite-plus config — `plugins`, `resolve`, `define`, `server`, `optimizeDeps`, `worker`, `test`, `build`, extra `run.tasks`, … — is just a field you set in the hook. Nothing config-vp-specific to learn; keep writing Vite config.
 
 ```ts
-const config = defineConfig({
+const config = defineVitePlusConfig({
   type: 'nuxt:spa',
-  extends: {
-    plugins: [tailwindcss()],
-    define: { 'import.meta.env.VITE_RELEASE': JSON.stringify(release) },
-    optimizeDeps: { exclude: ['some-wasm-dep'] },
-    server: { fs: { allow: ['../..'] } },
-    test, // your vitest config
-    run: {
-      tasks: {
-        preview: { command: 'nuxt preview', cache: false },
-        deploy: { command: 'vpx tsx scripts/deploy.ts' },
+  config: c => {
+    c.plugins = [...tailwindcss()];
+    c.define = {
+      'import.meta.env.VITE_RELEASE': JSON.stringify(release),
+    };
+    c.optimizeDeps = { exclude: ['some-wasm-dep'] };
+    c.server = {
+      fs: {
+        allow: ['../..'],
       },
-    },
+    };
+    c.test = { exclude: ['e2e/**'] };
+    c.run.tasks.preview = {
+      command: 'nuxt preview',
+      cache: false,
+    };
+    c.run.tasks.deploy = { command: 'vpx tsx scripts/deploy.ts' };
   },
 });
 export default config;
 ```
 
-Your entire app-specific Vite setup lives in `extends`, on top of config-vp's `nuxt:spa` defaults.
-
 ### Ignore patterns (lint + format)
 
-A top-level `ignorePatterns` is forwarded to **both** the linter and the formatter:
+`ignorePatterns` sets the ignore globs for **both** the linter and the formatter. Pass an array to set the whole list, or a function to derive it from the built-in defaults:
 
 ```ts
-defineConfig({
+defineVitePlusConfig({
+  type: 'lib',
+  // add to the defaults:
+  ignorePatterns: defaults => [...defaults, 'generated/**', 'vendor/**'],
+});
+
+defineVitePlusConfig({
   type: 'lib',
-  // Replace the built-in ignore list:
-  overrides: { ignorePatterns: ['only-this/**'] },
-  // …or add to it, keeping the defaults:
-  extends: { ignorePatterns: ['generated/**', 'vendor/**'] },
+  // …or set the list outright:
+  ignorePatterns: ['only-this/**'],
 });
 ```
 
 ### Disable packaging
 
-A `lib*` type includes packaging by default. Turn it off with `pack: false`:
+A `lib*` type includes packaging by default. To skip it, delete `pack` in the hook:
 
 ```ts
-defineConfig({
+defineVitePlusConfig({
   type: 'lib',
-  overrides: { pack: false },
+  config: c => {
+    delete c.pack;
+  },
 });
 ```
 
@@ -271,25 +331,12 @@ defineConfig({
 | Option | Type | Description |
 | --- | --- | --- |
 | `type` | `ProjectType` | `'lib' \| 'lib:vue' \| 'lib:nuxt' \| 'vue' \| 'nuxt:spa' \| 'nuxt:ssr'`. Omit for shared/root packages. |
-| `overrides` | object | Replace-semantics customizations. Accepts `ignorePatterns` and `pack: false`. |
-| `extends` | object | Additive customizations, applied after `overrides`. Same shape. |
-
-### Merge reference
-
-Order: `base → overrides (replace) → extends (additive)`.
-
-| Key             | Under `overrides`                     | Under `extends`      |
-| --------------- | ------------------------------------- | -------------------- |
-| `lint`          | arrays concat, rules deep-merge       | same                 |
-| `fmt`           | shallow-merge                         | recursive deep-merge |
-| `pack`          | shallow-merge (or `false` to disable) | recursive deep-merge |
-| `staged`        | shallow-merge                         | recursive deep-merge |
-| `run`           | shallow-merge, tasks combined         | recursive deep-merge |
-| arrays (others) | replace                               | concatenate          |
+| `ignorePatterns` | `string[] \| (defaults: string[]) => string[]` | Ignore globs for lint **and** fmt. Array sets the list; function derives it from the defaults. |
+| `config` | `(config) => config \| void` | Customization hook — receives the fully built config to mutate in place and/or return. |
 
 ## Default ignore patterns
 
-The base list applied to both linting and formatting (override or extend it via the [ignore-patterns shortcut](#ignore-patterns-lint--format)):
+The base list applied to both linting and formatting (override or extend it via [`ignorePatterns`](#ignore-patterns-lint--format)):
 
 ```
 *.log*               **/.output          **/.vp-tsconfig
@@ -301,7 +348,7 @@ The base list applied to both linting and formatting (override or extend it via
 
 ## API
 
-The package exports a single function, `defineConfig`, along with its `ProjectType` and `ConfigOptions` types for annotation.
+The package exports a single function, `defineVitePlusConfig`, plus the types `ConfigOptions` (its argument), `ProjectType`, and `ResolvedConfig` (the value passed to the `config` hook).
 
 ## Troubleshooting
 
@@ -311,10 +358,10 @@ Your config almost certainly uses an inline default export. `vp` discovers tasks
 
 ```ts
 // ❌ tasks are invisible to `vp run`
-export default defineConfig({ type: 'lib' });
+export default defineVitePlusConfig({ type: 'lib' });
 
 // ✅ assign, then export
-const config = defineConfig({ type: 'lib' });
+const config = defineVitePlusConfig({ type: 'lib' });
 export default config;
 ```
 

package/dist/index.d.mts

@@ -1,22 +1,41 @@
+import { OxlintConfig } from "oxlint";
 import { UserConfig } from "vite-plus";
 
 //#region src/index.d.ts
 type ProjectType = 'lib' | 'lib:nuxt' | 'lib:vue' | 'nuxt:spa' | 'nuxt:ssr' | 'vue';
-type DeepPartial<T> = T extends ((...args: never[]) => unknown) ? T : T extends (infer U)[] ? DeepPartial<U>[] : T extends object ? { [K in keyof T]?: DeepPartial<T[K]> } : T;
+type Run = NonNullable<UserConfig['run']>;
+/** A single task as the object form (config-vp always emits objects, never string shorthands). */
+type Task = Exclude<NonNullable<Run['tasks']>[string], string | string[]>;
+/** The pack config object form (never the multi-output array). */
+type Pack = Exclude<NonNullable<UserConfig['pack']>, readonly unknown[]>;
+/**
+ * The config as config-vp actually builds it: `lint`/`fmt`/`staged`/`run` are always present,
+ * `run.tasks` is a map of task objects, and `pack` (when present) is the object form. This lets
+ * the `config` hook mutate `c.run.tasks.x.command`, spread `c.pack`, etc. without guards.
+ */
+type ResolvedConfig = Omit<UserConfig, 'fmt' | 'lint' | 'pack' | 'run' | 'staged'> & {
+  lint: OxlintConfig;
+  fmt: NonNullable<UserConfig['fmt']>;
+  staged: NonNullable<UserConfig['staged']>;
+  run: Omit<Run, 'tasks'> & {
+    tasks: Record<string, Task>;
+  };
+  pack?: Pack;
+};
 interface ConfigOptions {
-  /** Project type — drives vue lint, pack inclusion, and dev/build/release tasks. */
+  /** Project type — drives Vue lint rules, library packaging, and dev/build/release tasks. */
   type?: ProjectType;
-  /** Replace semantics: values replace defaults, objects shallow-merge at known keys. Exception: lint is always additive (deep-merged). Pass `pack: false` to suppress pack inclusion. */
-  overrides?: DeepPartial<UserConfig> & {
-    ignorePatterns?: string[];
-    pack?: unknown;
-  };
-  /** Additive semantics: arrays concatenate, objects deep-merge. Applied AFTER overrides. Pass `pack: false` to suppress pack inclusion. */
-  extends?: DeepPartial<UserConfig> & {
-    ignorePatterns?: string[];
-    pack?: unknown;
-  };
+  /**
+   * Ignore globs for both lint and fmt. An array sets the list; a function receives the built-in
+   * defaults and returns the final list (e.g. `(defaults) => [...defaults, 'generated/**']`).
+   */
+  ignorePatterns?: ((defaults: string[]) => string[]) | string[];
+  /**
+   * Final customization hook. Receives the fully built config and may mutate it in place and/or
+   * return a new one (a returned value wins; otherwise the mutated argument is used).
+   */
+  config?: (config: ResolvedConfig) => ResolvedConfig | undefined;
 }
-declare function defineConfig(options?: ConfigOptions): UserConfig;
+declare function defineVitePlusConfig(options?: ConfigOptions): UserConfig;
 //#endregion
-export { ConfigOptions, ProjectType, defineConfig };
+export { ConfigOptions, ProjectType, ResolvedConfig, defineVitePlusConfig };

package/dist/index.mjs

@@ -635,54 +635,8 @@ const vueLint = {
 };
 //#endregion
 //#region src/index.ts
-const DEEP_MERGE_KEYS = new Set([
-	"fmt",
-	"pack",
-	"staged"
-]);
-function deepExtend(target, source) {
-	if (source === void 0) return target;
-	if (Array.isArray(target) && Array.isArray(source)) return [...target, ...source];
-	if (target !== null && typeof target === "object" && !Array.isArray(target) && source !== null && typeof source === "object" && !Array.isArray(source)) {
-		const result = { ...target };
-		for (const [key, value] of Object.entries(source)) result[key] = key in result ? deepExtend(result[key], value) : value;
-		return result;
-	}
-	return source;
-}
-function mergeLayers(base, ...layers) {
-	const result = { ...base };
-	for (const layer of layers) {
-		if (layer.lint) {
-			const { extends: layerExtends, ...layerLintRest } = layer.lint;
-			const baseArr = result.lint ? [result.lint] : [];
-			const combined = layerExtends !== void 0 ? [...baseArr, ...Array.isArray(layerExtends) ? layerExtends : [layerExtends]] : baseArr;
-			result.lint = combined.length > 0 ? {
-				extends: combined,
-				...layerLintRest
-			} : { ...layerLintRest };
-		}
-		if (layer.run) result.run = {
-			...result.run,
-			...layer.run,
-			tasks: {
-				...result.run?.tasks,
-				...layer.run.tasks
-			}
-		};
-		for (const [key, value] of Object.entries(layer)) {
-			if (key === "lint" || key === "run") continue;
-			if (DEEP_MERGE_KEYS.has(key)) result[key] = {
-				...result[key],
-				...value
-			};
-			else result[key] = value;
-		}
-	}
-	return result;
-}
+/** Merge OxlintConfig objects: arrays concat, nested objects shallow-merge, scalars replace. */
 function mergeLintConfigs(...configs) {
-	if (configs.length === 0) return {};
 	if (configs.length === 1) return { ...configs[0] };
 	return configs.reduce((acc, config) => {
 		const merged = { ...acc };
@@ -698,64 +652,32 @@ function mergeLintConfigs(...configs) {
 		return merged;
 	});
 }
-function defineConfig(options = {}) {
+function defineVitePlusConfig(options = {}) {
 	const t = options.type;
 	const isVue = t === "lib:vue" || t === "lib:nuxt" || t === "vue" || t === "nuxt:spa" || t === "nuxt:ssr";
 	const isLib = t === "lib" || t === "lib:vue" || t === "lib:nuxt";
-	const overridesPack = options.overrides?.pack;
-	const extendsPack = options.extends?.pack;
-	const isPack = (isLib || !!overridesPack || !!extendsPack) && overridesPack !== false && extendsPack !== false;
-	const lintLayers = [lint];
-	if (isVue) lintLayers.push(vueLint);
-	if (options.overrides?.lint) lintLayers.push(options.overrides.lint);
-	if (options.extends?.lint) lintLayers.push(options.extends.lint);
-	let mergedLint = mergeLintConfigs(...lintLayers);
-	if (options.overrides?.ignorePatterns) mergedLint = {
-		...mergedLint,
-		ignorePatterns: options.overrides.ignorePatterns
-	};
-	if (options.extends?.ignorePatterns) mergedLint = {
-		...mergedLint,
-		ignorePatterns: [...mergedLint.ignorePatterns ?? [], ...options.extends.ignorePatterns]
-	};
-	let mergedFmt = fmt;
-	if (options.overrides?.ignorePatterns) mergedFmt = {
-		...mergedFmt,
-		ignorePatterns: options.overrides.ignorePatterns
-	};
-	if (options.extends?.ignorePatterns) mergedFmt = {
-		...mergedFmt,
-		ignorePatterns: [...mergedFmt?.ignorePatterns ?? [], ...options.extends.ignorePatterns]
-	};
+	const mergedLint = isVue ? mergeLintConfigs(lint, vueLint) : mergeLintConfigs(lint);
+	const defaultIgnore = mergedLint.ignorePatterns ?? [];
+	const ignorePatterns = typeof options.ignorePatterns === "function" ? options.ignorePatterns(defaultIgnore) : options.ignorePatterns ?? defaultIgnore;
 	const run = buildRunConfig({
 		lib: isLib,
 		nuxt: t === "nuxt:spa" ? "spa" : t === "nuxt:ssr" ? "ssr" : void 0,
 		vueApp: t === "vue"
 	});
-	let result = {
-		lint: mergedLint,
-		fmt: mergedFmt,
+	const base = {
+		lint: {
+			...mergedLint,
+			ignorePatterns
+		},
+		fmt: {
+			...fmt,
+			ignorePatterns
+		},
 		staged,
 		run,
-		...isPack && { pack }
+		...isLib && { pack }
 	};
-	if (options.overrides) {
-		const { lint: _l, ignorePatterns: _ip, pack: _p, ...rest } = options.overrides;
-		const layer = overridesPack !== void 0 && overridesPack !== false ? {
-			...rest,
-			pack: overridesPack
-		} : rest;
-		if (Object.keys(layer).length > 0) result = mergeLayers(result, layer);
-	}
-	if (options.extends) {
-		const { lint: _l, ignorePatterns: _ip, pack: _p, ...rest } = options.extends;
-		const layer = extendsPack !== void 0 && extendsPack !== false ? {
-			...rest,
-			pack: extendsPack
-		} : rest;
-		if (Object.keys(layer).length > 0) result = deepExtend(result, layer);
-	}
-	return result;
+	return options.config ? options.config(base) ?? base : base;
 }
 //#endregion
-export { defineConfig };
+export { defineVitePlusConfig };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "config-vp",
-  "version": "1.0.0",
+  "version": "1.2.0",
   "description": "Shared vite-plus configuration — opinionated defaults for linting, formatting, task running, staged checks, and VSCode setup. Optional Vue and pack layers with deep-merge overrides.",
   "keywords": [
     "config",
@@ -47,10 +47,10 @@
   },
   "dependencies": {
     "@stylistic/eslint-plugin": "^5.10.0",
-    "eslint-plugin-perfectionist": "^5.8.0",
+    "eslint-plugin-perfectionist": "^5.9.0",
     "jsonc-parser": "^3.3.1",
-    "oxfmt": "^0.45.0",
-    "oxlint": "^1.60.0"
+    "oxfmt": "^0.53.0",
+    "oxlint": "^1.68.0"
   },
   "devDependencies": {
     "@types/node": "^24.10.1",