@icebreakers/monorepo-templates 0.1.10 → 0.1.11

package/assets/AGENTS.md

@@ -0,0 +1,50 @@
+# Repository Guidelines
+
+## Project Structure & Module Organization
+
+This pnpm + Turbo monorepo keeps template sources under `templates/` (`cli`, `client`, `server`, `vitepress`, `tsup`, `tsdown`, `unbuild`, `vue-lib`) and reusable tooling under `packages/` (e.g., `monorepo`, `create-icebreaker`). Shared TypeScript and build settings live in root configs such as `turbo.json`, `tsconfig.json`, and `eslint.config.js`. Tests sit alongside their targets in `test/*.test.ts`, and each app owns its public assets (`public/`, `worker/`) to keep deployments self-contained.
+
+## Build, Test, and Development Commands
+
+- `pnpm install` — set up workspaces; ensure Node 20+ as defined in `package.json`.
+- `pnpm dev` — run `turbo run dev --parallel` for all apps that expose a `dev` script.
+- `pnpm build` — execute `turbo run build` to build every workspace with caching.
+- `pnpm test` / `pnpm test:dev` — run Vitest suites once or in watch mode across packages.
+- `pnpm lint` — invoke `turbo run lint` to apply ESLint/Stylelint policies repo-wide.
+- `pnpm script:sync` & `pnpm script:clean` — use the monorepo helper to align dependency versions or clear generated artifacts.
+
+## Coding Style & Naming Conventions
+
+Follow the root `.editorconfig`: two-space indentation, LF line endings, UTF-8. Prefer TypeScript (`.ts`/`.tsx`) and Vue SFCs; name files with kebab-case (`user-table.vue`) and exported symbols with PascalCase for components or camelCase for utilities. ESLint (`@icebreakers/eslint-config`) and Stylelint enforce formatting; run `pnpm lint` before committing, and rely on Husky + lint-staged to auto-fix staged files. Any style-related code changes (CSS, SCSS, Less, Vue style blocks, and similar files) must pass Stylelint checks before commit. All changed code must pass ESLint checks before commit.
+
+`lint-staged.config.js` must include Stylelint checks for staged style files so style validation also runs during pre-commit.
+
+When a single code file exceeds 300 lines, treat it as a refactor signal and split it into smaller modules.
+
+When splitting code, do not create suffix-based sibling files such as `xxx.config.ts` or `xxx.filter.ts` just to move logic around. Create a dedicated folder (for example `xxx/`) and place the split modules inside it with clear responsibilities.
+
+All generated code must pass ESLint checks, and all generated style files must pass Stylelint checks.
+
+## Testing Guidelines
+
+Vitest powers unit tests located in `test/*.test.ts`. Mirror existing naming by matching the unit under test (`monorepo` utilities map to `packages/monorepo/test/*.test.ts`). Aim for meaningful assertions rather than snapshot defaults, and add coverage checks with `pnpm test -- --coverage`, which writes reports to `coverage/`. When introducing new public APIs, include integration-style tests in the relevant app workspace. AI-assisted validation must run a full test matrix when available, including unit, integration, and E2E tests.
+
+Before running tests, build the packages first and run tests against build artifacts instead of source-only execution to better match real delivery behavior.
+
+TypeScript issues must be fixed before commit. Do not commit with unresolved TypeScript compile or type-check errors.
+
+TypeScript code must be validated with `tsc` (`pnpm typecheck` or the relevant workspace `typecheck` script) and must not contain type errors.
+
+When building TypeScript libraries (type-focused APIs or public type definitions), add and maintain `tsd` type tests to verify exported type behavior.
+
+## Commit & Pull Request Guidelines
+
+Commits must conform to Conventional Commit syntax; recent history uses prefixes like `feat`, `fix`, and `chore`. Example: `feat(server): add auth router`. Use `pnpm commit` (commitlint prompt) or ensure your manual message passes `pnpm commitlint --edit`. Before opening a PR, make sure `pnpm lint` and `pnpm test` succeed, link related issues, and provide screenshots or logs for user-facing changes. Touching publishable packages requires a changeset (`pnpm changeset`) so releases stay traceable.
+
+For AI-generated or AI-assisted changes, use this verification order before commit or PR:
+
+1. Run build first (`pnpm build` or the relevant workspace build command).
+2. Run lint checks, ensuring all changed code passes ESLint and style-related code passes Stylelint.
+3. Run TypeScript checks and fix all type errors before proceeding.
+4. For TypeScript libraries, run `tsd` type tests and fix all failures before proceeding.
+5. Run tests against built artifacts, including unit, integration, and E2E suites (when available in the affected workspace).

package/assets/package.json

@@ -3,7 +3,7 @@
   "type": "module",
   "version": "0.0.0",
   "private": true,
-  "packageManager": "pnpm@10.29.3",
+  "packageManager": "pnpm@10.30.2",
   "author": "ice breaker <hi@sonofmagic.top>",
   "repository": {
     "type": "git",
@@ -46,21 +46,21 @@
   },
   "devDependencies": {
     "@changesets/cli": "^2.29.8",
-    "@commitlint/cli": "^20.4.1",
+    "@commitlint/cli": "^20.4.2",
     "@icebreakers/changelog-github": "^0.2.0",
-    "@icebreakers/commitlint-config": "^1.2.7",
-    "@icebreakers/eslint-config": "^1.6.19",
+    "@icebreakers/commitlint-config": "^1.2.8",
+    "@icebreakers/eslint-config": "^1.6.21",
     "@icebreakers/monorepo": "workspace:*",
     "@icebreakers/stylelint-config": "^2.0.2",
     "@types/fs-extra": "^11.0.4",
-    "@types/node": "^25.2.3",
+    "@types/node": "^25.3.0",
     "@types/semver": "^7.7.1",
     "@vitest/coverage-v8": "~4.0.18",
     "ci-info": "^4.4.0",
     "cross-env": "^10.1.0",
     "defu": "^6.1.4",
     "es-toolkit": "^1.44.0",
-    "eslint": "^10.0.0",
+    "eslint": "^10.0.2",
     "execa": "^9.6.1",
     "fs-extra": "^11.3.3",
     "husky": "^9.1.7",
@@ -68,13 +68,13 @@
     "only-allow": "^1.2.2",
     "pathe": "^2.0.3",
     "pkg-types": "^2.3.0",
-    "rimraf": "^6.1.2",
+    "rimraf": "^6.1.3",
     "stylelint": "^17.3.0",
     "tsdown": "0.20.3",
     "tslib": "^2.8.1",
     "tsup": "^8.5.1",
     "tsx": "^4.21.0",
-    "turbo": "^2.8.8",
+    "turbo": "^2.8.10",
     "type-fest": "^5.4.4",
     "typescript": "^5.9.3",
     "unbuild": "^3.6.1",

package/assets-data.mjs

@@ -12,6 +12,7 @@ const coreAssetTargets = [
   'stylelint.config.js',
   'monorepo.config.ts',
   'package.json',
+  'AGENTS.md',
   // pnpm
   'pnpm-workspace.yaml',
   // base tsconfig

package/dist/index.d.mts

@@ -29,6 +29,9 @@ interface PrepareAssetsOptions {
 }
 declare function prepareAssets(options?: PrepareAssetsOptions): Promise<void>;
 //#endregion
+//#region src/runtime-assets.d.ts
+declare function ensureTemplateAssetsPrepared(): Promise<void>;
+//#endregion
 //#region src/scaffold.d.ts
 type TargetMode = 'prepare' | 'ensure' | 'skip';
 interface ScaffoldTemplateOptions {
@@ -74,4 +77,4 @@ declare const templateSourceMap: Record<string, string>;
 declare const templateTargetMap: Record<string, string>;
 declare const templateMap: Record<string, string>;
 //#endregion
-export { Command, type TemplateChoice, type TemplateDefinition, assetTargets, assetsDir, checkbox, createTemplateCopyFilter, execaCommand, getAssetTargets, input, isGitignoreFile, packageDir, prepareAssets, program, runCommand, scaffoldTemplate, scaffoldWorkspace, select, shouldSkipTemplatePath, skeletonDir, templateChoices, templateMap, templateSourceMap, templateTargetMap, templatesDir, toPublishGitignorePath, toWorkspaceGitignorePath };
+export { Command, type TemplateChoice, type TemplateDefinition, assetTargets, assetsDir, checkbox, createTemplateCopyFilter, ensureTemplateAssetsPrepared, execaCommand, getAssetTargets, input, isGitignoreFile, packageDir, prepareAssets, program, runCommand, scaffoldTemplate, scaffoldWorkspace, select, shouldSkipTemplatePath, skeletonDir, templateChoices, templateMap, templateSourceMap, templateTargetMap, templatesDir, toPublishGitignorePath, toWorkspaceGitignorePath };

package/dist/index.mjs

@@ -1,7 +1,7 @@
 import * as path$1 from "node:path";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
-import fs from "node:fs/promises";
+import fs, { access, open, rm } from "node:fs/promises";
 import { execa, execaCommand } from "execa";
 import checkbox from "@inquirer/checkbox";
 import input from "@inquirer/input";
@@ -23,6 +23,7 @@ const coreAssetTargets = [
 	"stylelint.config.js",
 	"monorepo.config.ts",
 	"package.json",
+	"AGENTS.md",
 	"pnpm-workspace.yaml",
 	"tsconfig.json",
 	"turbo.json",
@@ -172,7 +173,7 @@ function createTemplateCopyFilter(rootDir) {
 
 //#endregion
 //#region src/prepare.ts
-async function pathExists(targetPath) {
+async function pathExists$1(targetPath) {
 	try {
 		await fs.access(targetPath);
 		return true;
@@ -199,7 +200,7 @@ async function renameGitignoreFiles(targetDir) {
 	}));
 }
 async function resetDir(targetDir, overwriteExisting) {
-	if (!overwriteExisting && await pathExists(targetDir)) return;
+	if (!overwriteExisting && await pathExists$1(targetDir)) return;
 	try {
 		await fs.rm(targetDir, {
 			recursive: true,
@@ -212,7 +213,7 @@ async function resetDir(targetDir, overwriteExisting) {
 	await fs.mkdir(targetDir, { recursive: true });
 }
 async function copyEntry(from, to, overwriteExisting, filter) {
-	if (!overwriteExisting && await pathExists(to)) return;
+	if (!overwriteExisting && await pathExists$1(to)) return;
 	try {
 		await fs.cp(from, to, {
 			recursive: true,
@@ -228,7 +229,7 @@ async function copyEntry(from, to, overwriteExisting, filter) {
 async function copyAssets(repoRoot, overwriteExisting) {
 	for (const target of assetTargets$1) {
 		const from = path$1.join(repoRoot, target);
-		if (!await pathExists(from)) continue;
+		if (!await pathExists$1(from)) continue;
 		const to = path$1.join(assetsDir, toPublishGitignorePath(target));
 		const stats = await fs.stat(from);
 		await copyEntry(from, to, overwriteExisting, target === ".husky" ? (src) => !/[\\/]_$/.test(src) : void 0);
@@ -238,7 +239,7 @@ async function copyAssets(repoRoot, overwriteExisting) {
 async function copyTemplates(repoRoot, overwriteExisting) {
 	for (const template of templateChoices$1) {
 		const from = path$1.join(repoRoot, "templates", template.source);
-		if (!await pathExists(from)) continue;
+		if (!await pathExists$1(from)) continue;
 		const to = path$1.join(templatesDir, template.source);
 		const filter = (src) => !shouldSkipTemplatePath(from, src);
 		await copyEntry(from, to, overwriteExisting, filter);
@@ -248,13 +249,77 @@ async function copyTemplates(repoRoot, overwriteExisting) {
 async function prepareAssets(options = {}) {
 	const overwriteExisting = options.overwriteExisting ?? true;
 	const repoRoot = path$1.resolve(packageDir, "..", "..");
-	if (!await pathExists(path$1.join(repoRoot, "templates"))) return;
+	if (!await pathExists$1(path$1.join(repoRoot, "templates"))) return;
 	await resetDir(assetsDir, overwriteExisting);
 	await resetDir(templatesDir, overwriteExisting);
 	await copyAssets(repoRoot, overwriteExisting);
 	await copyTemplates(repoRoot, overwriteExisting);
 }
 
+//#endregion
+//#region src/runtime-assets.ts
+const lockFileName = ".prepare-assets.lock";
+const lockPollIntervalMs = 200;
+const lockTimeoutMs = 3e4;
+let ensurePromise = null;
+async function pathExists(targetPath) {
+	try {
+		await access(targetPath);
+		return true;
+	} catch {
+		return false;
+	}
+}
+async function acquireLock(lockPath) {
+	try {
+		return await open(lockPath, "wx");
+	} catch (error) {
+		if (error.code === "EEXIST") return null;
+		throw error;
+	}
+}
+async function isPrepared() {
+	const checks = [
+		path.join(assetsDir, "AGENTS.md"),
+		path.join(assetsDir, "LICENSE"),
+		path.join(templatesDir, "unbuild")
+	];
+	return (await Promise.all(checks.map(pathExists))).every(Boolean);
+}
+async function waitForPrepared() {
+	const deadline = Date.now() + lockTimeoutMs;
+	while (Date.now() < deadline) {
+		if (await isPrepared()) return true;
+		await new Promise((resolve) => setTimeout(resolve, lockPollIntervalMs));
+	}
+	return false;
+}
+async function runEnsure() {
+	if (await isPrepared()) return;
+	const lockPath = path.join(packageDir, lockFileName);
+	let lockHandle = await acquireLock(lockPath);
+	if (!lockHandle) {
+		if (await waitForPrepared()) return;
+		lockHandle = await acquireLock(lockPath);
+		if (!lockHandle) throw new Error(`Failed to prepare template assets: lock is held at ${lockPath}`);
+	}
+	try {
+		await prepareAssets({
+			overwriteExisting: false,
+			silent: true
+		});
+	} finally {
+		await lockHandle.close().catch(() => {});
+		await rm(lockPath, { force: true }).catch(() => {});
+	}
+}
+async function ensureTemplateAssetsPrepared() {
+	if (!ensurePromise) ensurePromise = runEnsure().finally(() => {
+		ensurePromise = null;
+	});
+	await ensurePromise;
+}
+
 //#endregion
 //#region src/scaffold.ts
 async function isEmptyDir(dir) {
@@ -291,12 +356,13 @@ async function copyDirContents(sourceDir, targetDir, options = {}) {
 		const targetName = renameEntry(entry.name);
 		const to = path.join(targetDir, targetName);
 		if (entry.isDirectory()) {
-			await copyDirContents(from, to, {
+			const nestedOptions = {
 				rootDir,
 				filter,
-				renameEntry,
-				skipRootBasenames: options.skipRootBasenames
-			});
+				renameEntry
+			};
+			if (options.skipRootBasenames) nestedOptions.skipRootBasenames = options.skipRootBasenames;
+			await copyDirContents(from, to, { ...nestedOptions });
 			continue;
 		}
 		if (entry.isSymbolicLink()) {
@@ -307,18 +373,24 @@ async function copyDirContents(sourceDir, targetDir, options = {}) {
 		await fs.cp(from, to);
 	}
 }
+function isDefaultTemplatesPath(sourceDir) {
+	const resolvedSource = path.resolve(sourceDir);
+	const resolvedTemplatesRoot = path.resolve(templatesDir);
+	return resolvedSource === resolvedTemplatesRoot || resolvedSource.startsWith(`${resolvedTemplatesRoot}${path.sep}`);
+}
 async function scaffoldTemplate(options) {
 	const { sourceDir, targetDir, ensureTargetDir = true, filter, renameEntry, skipRootBasenames } = options;
+	if (isDefaultTemplatesPath(sourceDir)) await ensureTemplateAssetsPrepared();
 	if (ensureTargetDir) await fs.mkdir(targetDir, { recursive: true });
-	await copyDirContents(sourceDir, targetDir, {
-		rootDir: sourceDir,
-		filter,
-		renameEntry,
-		skipRootBasenames
-	});
+	const copyOptions = { rootDir: sourceDir };
+	if (filter) copyOptions.filter = filter;
+	if (renameEntry) copyOptions.renameEntry = renameEntry;
+	if (skipRootBasenames) copyOptions.skipRootBasenames = skipRootBasenames;
+	await copyDirContents(sourceDir, targetDir, copyOptions);
 }
 async function scaffoldWorkspace(options) {
 	const { targetDir, templateKeys = [], assetsDir: assetsDir$1 = assetsDir, templatesDir: templatesDir$1 = templatesDir, includeAssets = true, targetMode = "prepare", force = false } = options;
+	if (includeAssets && path.resolve(assetsDir$1) === path.resolve(assetsDir) || templateKeys.length > 0 && path.resolve(templatesDir$1) === path.resolve(templatesDir)) await ensureTemplateAssetsPrepared();
 	if (targetMode === "prepare") await prepareTargetDir(targetDir, { force });
 	else if (targetMode === "ensure") await fs.mkdir(targetDir, { recursive: true });
 	if (includeAssets) await copyDirContents(assetsDir$1, targetDir, { rootDir: assetsDir$1 });
@@ -352,4 +424,4 @@ const templateTargetMap = Object.fromEntries(templateChoices.map((item) => [item
 const templateMap = templateSourceMap;
 
 //#endregion
-export { Command, assetTargets, assetsDir, checkbox, createTemplateCopyFilter, execaCommand, getAssetTargets, input, isGitignoreFile, packageDir, prepareAssets, program, runCommand, scaffoldTemplate, scaffoldWorkspace, select, shouldSkipTemplatePath, skeletonDir, templateChoices, templateMap, templateSourceMap, templateTargetMap, templatesDir, toPublishGitignorePath, toWorkspaceGitignorePath };
+export { Command, assetTargets, assetsDir, checkbox, createTemplateCopyFilter, ensureTemplateAssetsPrepared, execaCommand, getAssetTargets, input, isGitignoreFile, packageDir, prepareAssets, program, runCommand, scaffoldTemplate, scaffoldWorkspace, select, shouldSkipTemplatePath, skeletonDir, templateChoices, templateMap, templateSourceMap, templateTargetMap, templatesDir, toPublishGitignorePath, toWorkspaceGitignorePath };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@icebreakers/monorepo-templates",
   "type": "module",
-  "version": "0.1.10",
+  "version": "0.1.11",
   "description": "Template assets for icebreaker monorepo scaffolding",
   "author": "ice breaker <hi@sonofmagic.top>",
   "license": "MIT",
@@ -39,9 +39,9 @@
     "node": ">=18.0.0"
   },
   "dependencies": {
-    "@inquirer/checkbox": "^5.0.4",
-    "@inquirer/input": "^5.0.4",
-    "@inquirer/select": "^5.0.4",
+    "@inquirer/checkbox": "^5.1.0",
+    "@inquirer/input": "^5.0.8",
+    "@inquirer/select": "^5.1.0",
     "commander": "^14.0.3",
     "execa": "^9.6.1"
   },

package/templates/cli/package.json

@@ -22,7 +22,8 @@
     "dev": "tsup --watch --sourcemap",
     "build": "tsup",
     "lint": "eslint .",
-    "lint:fix": "eslint . --fix"
+    "lint:fix": "eslint . --fix",
+    "typecheck": "tsc -p tsconfig.json"
   },
   "dependencies": {
     "consola": "^3.4.2"

package/templates/client/AGENTS.md

@@ -0,0 +1,28 @@
+# Template Guidelines (`templates/client`)
+
+This file adds template-local guidance. Global rules are defined in the repository root `AGENTS.md` and still apply.
+
+## Scope
+
+- Template path: `templates/client`
+- Purpose: Vue + Vite + Cloudflare Worker client template
+
+## Structure
+
+- `src/`: app UI, pages, router, stores, trpc client
+- `worker/`: worker/server entry and router definitions
+- `public/`: static assets
+- `tsconfig*.json`: split TS projects (`app`, `node`, `worker`)
+
+## Local Rules
+
+- Keep browser code in `src/` and worker runtime code in `worker/`; avoid cross-layer coupling.
+- Keep `typecheck` aligned with `vue-tsc -b` and project references in `tsconfig.json`.
+- Tailwind ESLint config uses an absolute entry path in `eslint.config.js`; keep that pattern to avoid lint-staged path resolution issues.
+- Prefer small feature folders inside `src/` (for example `src/features/<name>/`) when modules grow.
+
+## Validation
+
+- `pnpm --filter @icebreakers/client lint`
+- `pnpm --filter @icebreakers/client typecheck`
+- `pnpm --filter @icebreakers/client build`

package/templates/client/eslint.config.js

@@ -1,11 +1,14 @@
+import { fileURLToPath } from 'node:url'
 import { icebreaker } from '@icebreakers/eslint-config'
 
+const tailwindEntryPoint = fileURLToPath(new URL('./src/style.css', import.meta.url))
+
 export default icebreaker(
   {
     vue: true,
     typescript: true,
     tailwindcss: {
-      entryPoint: './src/style.css',
+      entryPoint: tailwindEntryPoint,
     },
     ignores: ['**/fixtures/**'],
   },

package/templates/client/package.json

@@ -11,42 +11,43 @@
     "preview": "vite preview",
     "deploy": "wrangler deploy",
     "cf-typegen": "wrangler types",
-    "postinstall": "pnpm cf-typegen"
+    "postinstall": "pnpm cf-typegen",
+    "typecheck": "vue-tsc -b"
   },
   "dependencies": {
     "@faker-js/faker": "^10.3.0",
     "@tanstack/vue-query": "^5.92.9",
     "@tanstack/vue-query-devtools": "^6.1.5",
     "@tanstack/vue-table": "^8.21.3",
-    "@tanstack/vue-virtual": "^3.13.18",
+    "@tanstack/vue-virtual": "^3.13.19",
     "@trpc/client": "^11.10.0",
     "clsx": "^2.1.1",
     "pinia": "^3.0.4",
-    "tailwind-merge": "^3.4.0",
+    "tailwind-merge": "^3.5.0",
     "tailwind-variants": "^3.2.2",
-    "vue": "^3.5.28",
+    "vue": "^3.5.29",
     "vue-i18n": "^11.2.8",
-    "vue-router": "^5.0.2"
+    "vue-router": "^5.0.3"
   },
   "devDependencies": {
-    "@cloudflare/vite-plugin": "^1.25.0",
+    "@cloudflare/vite-plugin": "^1.25.5",
     "@hono/node-server": "^1.19.9",
     "@hono/trpc-server": "^0.4.2",
-    "@tailwindcss/vite": "^4.1.18",
+    "@tailwindcss/vite": "^4.2.1",
     "@trpc/server": "^11.10.0",
     "@vitejs/plugin-vue": "^6.0.4",
     "@vitejs/plugin-vue-jsx": "^5.1.4",
     "@vue/tsconfig": "^0.8.1",
     "consola": "^3.4.2",
-    "hono": "^4.11.9",
-    "tailwindcss": "^4.1.18",
+    "hono": "^4.12.2",
+    "tailwindcss": "^4.2.1",
     "typescript": "~5.9.3",
     "unplugin-vue-router": "^0.19.2",
     "vite": "^7.3.1",
     "vite-plugin-vue-devtools": "^8.0.6",
     "vite-tsconfig-paths": "^6.1.1",
-    "vue-tsc": "3.2.4",
-    "wrangler": "^4.65.0",
+    "vue-tsc": "3.2.5",
+    "wrangler": "^4.68.1",
     "zod": "^4.3.6"
   }
 }

package/templates/server/package.json

@@ -36,7 +36,8 @@
     "lint:fix": "eslint . --fix",
     "deploy": "wrangler deploy",
     "cf-typegen": "wrangler types",
-    "postinstall": "pnpm cf-typegen"
+    "postinstall": "pnpm cf-typegen",
+    "typecheck": "tsc -p tsconfig.json"
   },
   "publishConfig": {
     "exports": {
@@ -53,8 +54,8 @@
   "devDependencies": {
     "@hono/node-server": "^1.19.9",
     "consola": "^3.4.2",
-    "hono": "^4.11.9",
-    "wrangler": "^4.65.0",
+    "hono": "^4.12.2",
+    "wrangler": "^4.68.1",
     "zod": "^4.3.6"
   }
 }

package/templates/tsdown/package.json

@@ -41,7 +41,8 @@
     "test:dev": "vitest",
     "release": "pnpm publish",
     "lint": "eslint .",
-    "lint:fix": "eslint . --fix"
+    "lint:fix": "eslint . --fix",
+    "typecheck": "tsc -p tsconfig.json"
   },
   "publishConfig": {}
 }

package/templates/tsup/package.json

@@ -42,7 +42,8 @@
     "test:dev": "vitest",
     "release": "pnpm publish",
     "lint": "eslint .",
-    "lint:fix": "eslint . --fix"
+    "lint:fix": "eslint . --fix",
+    "typecheck": "tsc -p tsconfig.json"
   },
   "publishConfig": {}
 }

package/templates/unbuild/package.json

@@ -42,7 +42,8 @@
     "test:dev": "vitest",
     "release": "pnpm publish",
     "lint": "eslint .",
-    "lint:fix": "eslint . --fix"
+    "lint:fix": "eslint . --fix",
+    "typecheck": "tsc -p tsconfig.json"
   },
   "publishConfig": {}
 }

package/templates/vitepress/package.json

@@ -19,20 +19,21 @@
     "build": "vitepress build",
     "preview": "vitepress preview",
     "lint": "eslint .",
-    "lint:fix": "eslint . --fix"
+    "lint:fix": "eslint . --fix",
+    "typecheck": "tsc -p tsconfig.json"
   },
   "dependencies": {
-    "vue": "^3.5.28"
+    "vue": "^3.5.29"
   },
   "devDependencies": {
     "@braintree/sanitize-url": "^7.1.2",
-    "@tailwindcss/vite": "^4.1.18",
+    "@tailwindcss/vite": "^4.2.1",
     "cytoscape": "^3.33.1",
     "cytoscape-cose-bilkent": "^4.1.0",
     "dayjs": "^1.11.19",
     "debug": "^4.4.3",
-    "mermaid": "^11.12.2",
-    "tailwindcss": "^4.1.18",
+    "mermaid": "^11.12.3",
+    "tailwindcss": "^4.2.1",
     "vitepress": "^1.6.4",
     "vitepress-plugin-mermaid": "^2.0.17"
   }

package/templates/vitepress/tools/turborepo.md

@@ -49,7 +49,7 @@ npx create-turbo@latest
 
 这会生成一个 monorepo 结构，比如：
 
-```
+```txt
 .
 ├── apps
 │   ├── web     # 前端应用

package/templates/vitepress/tsconfig.json

@@ -0,0 +1,15 @@
+{
+  "compilerOptions": {
+    "target": "ESNext",
+    "module": "ESNext",
+    "moduleResolution": "Bundler",
+    "resolveJsonModule": true,
+    "strict": true,
+    "noEmit": true,
+    "skipLibCheck": true
+  },
+  "include": [
+    "why/examples/2.npm-basic-package/src/**/*.ts",
+    "why/examples/3.npm-basic-package/src/**/*.ts"
+  ]
+}

package/templates/vitepress/why/js-cjs-mjs.md

@@ -14,7 +14,7 @@
 | `.mts`  | TypeScript，**指定生成 ESM**                       | TS 编译器/工具链                                     | 同上；不由 Node 直接执行。编译后产出 `.mjs/.js`（ESM 语义），并可生成 `.d.mts`。                                                                                                                                                  |
 | `.d.ts` | **类型声明文件**（仅类型，无运行时）               | TypeScript 编译器、编辑器/语言服务、打包器的类型阶段 | **永不执行**。仅在类型检查/智能提示/发布类型时被“读取”。若包的 `package.json` 有 `"types": "index.d.ts"`（或在 `exports` 的 `types`/ `typesVersions` 配置），TS 会用它做类型来源。也存在 `.d.mts` / `.d.cts` 变体以对应 ESM/CJS。 |
 
-# 关键规则与细节
+## 关键规则与细节
 
 1. **Node.js 如何决定 CJS vs ESM（针对 `.js`）**
    - 在某个包目录（有 `package.json`）下：

package/templates/vitepress/why/modern/dts.md

@@ -10,13 +10,13 @@
 
 下面这 2 个标志想必大家在 `npmjs` 进行搜索的时候都见到过。
 
-<img width="40" src="../assets/npm-ts.svg" />
+<img width="40" src="../assets/npm-ts.svg" alt="TypeScript built-in types badge" />
 
 这个标志代表这个包发布的时候，本身包里面就自己提供了 `dts`，这个需要在打包生成出 `dts` 之后，在 `package.json` 中，通过 `types` 字段指定了 `dts` 的位置
 
 比如我发的所有包 [weapp-tailwindcss](https://www.npmjs.com/package/weapp-tailwindcss), [weapp-vite](https://www.npmjs.com/package/weapp-vite), [modern-ahocorasick](https://www.npmjs.com/package/modern-ahocorasick) 等等...
 
-<img width="40" src="../assets/npm-dt.svg" />
+<img width="40" src="../assets/npm-dt.svg" alt="DefinitelyTyped badge" />
 
 这个标志代表这个包发布的时候，本身包里面没有 `dts`，但是有好心人给他写了 `dts`，并发布到了 `@types/*` 这个作用域下了，所以这个包等同于也有 `dts`，而且 `vscode` 也在发现你安装了这样的包之后，也会去下载 `@types/*` 这样的包，当然更好的方式是你要显式安装 `@types` 包
 
@@ -29,9 +29,9 @@
 <div class="flex justify-center">
 <div class="flex items-center border p-6">
 
-<img class="w-12" src="../assets/npm-ts.svg" />
+<img class="w-12" src="../assets/npm-ts.svg" alt="TypeScript built-in types badge" />
 <div class="text-5xl mx-5">></div>
-<img class="w-12" src="../assets/npm-dt.svg" />
+<img class="w-12" src="../assets/npm-dt.svg" alt="DefinitelyTyped badge" />
 <div class="text-5xl mx-5">></div>
 <div>什么标志都没有的包</div>
 </div>
@@ -88,6 +88,6 @@ declare function add(a: number, b: number): number
 - 手动编写 `.d.ts`
 - 自动生成（例如通过 `tsc --declaration`）
 - 安装类型定义包：
-  ```
+  ```bash
   npm install --save-dev @types/express
   ```

package/templates/vitepress/why/what-is-npm-package.md

@@ -6,7 +6,7 @@ outline: [2, 4]
 
 在 `Node.js` 中，**npm 包（npm package）** 是指一个通过 [npm（Node Package Manager）](https://www.npmjs.com/) 发布和管理的可重用 `JavaScript` 模块。它可以是一个库、工具、框架、命令行工具，甚至是一个完整的应用程序。
 
-### 什么是 npm？
+## 什么是 npm？
 
 **npm（Node Package Manager）** 是 Node.js 的官方包管理工具，用于：
 
@@ -28,11 +28,11 @@ outline: [2, 4]
 
 ---
 
-### 什么是一个 npm 包？
+## 什么是一个 npm 包？
 
 一个 **npm 包** 通常具有以下结构：
 
-```
+```txt
 my-package/
 ├── package.json     // 包的元数据（名字、版本、依赖等）
 ├── index.js         // 主文件（或其它入口）

package/templates/vue-lib/package.json

@@ -27,7 +27,8 @@
     "test:dev": "vitest",
     "release": "pnpm publish",
     "lint": "eslint .",
-    "lint:fix": "eslint . --fix"
+    "lint:fix": "eslint . --fix",
+    "typecheck": "vue-tsc -b"
   },
   "publishConfig": {
     "exports": {
@@ -46,10 +47,10 @@
     "@vitejs/plugin-vue": "^6.0.4",
     "@vue/test-utils": "^2.4.6",
     "@vue/tsconfig": "^0.8.1",
-    "jsdom": "^28.0.0",
+    "jsdom": "^28.1.0",
     "vite": "^7.3.1",
     "vite-plugin-dts": "^4.5.4",
-    "vue": "^3.5.28",
-    "vue-tsc": "^3.2.4"
+    "vue": "^3.5.29",
+    "vue-tsc": "^3.2.5"
   }
 }