菜单
Configures and optimizes the JS/TS build toolchain — tsconfig plus a bundler (Vite/esbuild/Rollup/tsup/webpack) — for correct module output (ESM/CJS/dual + types), code splitting, tree-shaking, sourcemaps, env injection, and fast incremental builds.
默认使用会先检查来源的 Prompt；你也可以切换为直接命令，或下载本地副本。
决定是否安装前，请先阅读 SKILL.md，以及 SkillsMP 当前展示的配套文件。
用 Codex 或 Claude 帮你安装 复制这段 Prompt，粘贴到 Codex、Claude 或其他助手里，让它检查 Skill 页面并帮你完成安装。
直接命令不会经过审查 Prompt；运行前请先检查来源。
npx skills add https://github.com/Sir-chawakorn/sanook-cli --skill configure-bundler-build命令会保持在同一行。复制前请横向滚动并检查完整内容。
想先保存到本地？可下载 SkillsMP 当前能够提供的文件。
正在显示 SKILL.md
| name | configure-bundler-build |
| description | Configures and optimizes the JS/TS build toolchain — tsconfig plus a bundler (Vite/esbuild/Rollup/tsup/webpack) — for correct module output (ESM/CJS/dual + types), code splitting, tree-shaking, sourcemaps, env injection, and fast incremental builds. |
| when_to_use | Setting up or fixing how an app or library compiles and bundles — wrong module format, broken tree-shaking, missing/incorrect types, slow builds, tsconfig errors. Distinct from dockerfile-optimize (container images) and optimize-core-web-vitals (browser runtime metrics). |
Reach for this skill when the problem is how source compiles and emits, not how it runs in a browser or container:
require()" (or vice versa) — dual-package outputCould not find a declaration file" — missing/mislocated .d.tstsc/vite build is slow" — switch transform to esbuild/swc, add a persistent cachedefine/import.meta.env isn't replacing my env var" or a secret leaked into the client bundlemodule/moduleResolution mismatch, "x.js" has no exported member, paths not resolvingNOT this skill:
npm publish, files/publishConfig, provenance, version bump → publish-package-registry.nvmrc, Volta) → pin-toolchain-versionsPick the bundler by build target — do not default to webpack.
| Target | Use | Why |
|---|---|---|
| App (SPA/SSR, has an entry HTML or framework) | Vite | Rollup-based prod build, esbuild dev, HMR, code-splitting out of the box |
| Library (published to npm, consumers bundle it) | tsup (esbuild) or Rollup | dual ESM+CJS + .d.ts in one config; Rollup when you need fine-grained chunking |
| Node tool / CLI / serverless fn (single self-run entry) | esbuild | fastest, bundle deps in, --platform=node, no chunk graph needed |
| Legacy app needing module federation / exotic loaders | webpack | only when a Vite/Rollup plugin doesn't exist |
Default: app → Vite, library → tsup, node-tool → esbuild. One tool emits JS; tsc emits types (or tsup --dts / vite-plugin-dts wraps it). Never run tsc as the bundler for shipping code — it doesn't bundle, tree-shake, or split.
Set the tsconfig essentials — moduleResolution is the #1 footgun. Pick the resolution mode by who resolves modules:
| Scenario | module | moduleResolution |
|---|---|---|
| Bundler handles resolution (Vite/tsup/esbuild) | ESNext (or Preserve) | bundler |
| Node runs the output directly (Node ESM/CJS) | NodeNext | nodenext |
// tsconfig.json — app/library baseline
{
"compilerOptions": {
"target":
moduleResolution: node (classic) with modern packages. Fails to resolve exports-map-only packages. Use bundler (bundler resolves) or nodenext (Node resolves) — never the legacy node/node10.types condition placed last in the exports map. TS reads conditions top-down and takes the first match; if import/require come before types, the consumer gets "no declaration file." types must be the first key in each condition block..cjs file emitting export {} (or .mjs with require). The exports map points at the wrong file per condition, or "type": "module" mismatches the extension. ESM → .js/.mjs, CJS → .cjs. Verify with node -e "require('your-pkg')" and a separate import."sideEffects": false on a package that has side effects. Tree-shaking drops a polyfill/CSS/registration import → feature silently missing in prod only. List the real side-effect files instead of a blanket false.VITE_/defined var. It's inlined into client JS and shipped to every browser. Only public values get VITE_/NEXT_PUBLIC_; secrets stay server-side at runtime.paths alias resolves in the editor but Cannot find module '@/x' at build. tsc/paths is type-only; the bundler needs its own alias (vite-tsconfig-paths, resolve.alias, or tsconfig-paths). Configure both.isolatedModules errors on export { Foo } where Foo is a type. esbuild/swc compile each file alone and can't tell types from values. Use export type { Foo } / import type (enforced by verbatimModuleSyntax).rm -rf dist && <build> exits 0 and dist/ contains the expected entry files (.js, .cjs, .d.ts, .map).npx @arethetypeswrong/cli --pack reports no ❌ — no "masquerading as CJS/ESM", no missing types per condition.npx publint is clean — exports, main/module/types, and file extensions all consistent.node -e "import('your-pkg').then(m=>console.log(Object.keys(m)))" and node -e "console.log(Object.keys(require('your-pkg')))" both print the API — no ERR_REQUIRE_ESM / ERR_PACKAGE_PATH_NOT_EXPORTED.tsc --noEmit exits 0 (proves the build path didn't skip a type error).--metafile shows unused siblings absent from output. Bundle size drops when an unused heavy import is removed.dist/assets/).grep -r "<a known secret substring>" dist/ returns nothing; only intended public VITE_*/NEXT_PUBLIC_* values appear..map or trigger an error — stack trace points to original src/ lines, not minified columns.Done = clean build emits the correct module formats + types, attw and publint are clean, both import() and require() load the API, tsc --noEmit passes, tree-shaking and code-splitting are confirmed in the output, no secret leaked into dist/, and warm rebuilds are fast.
paths are a type-level alias only — the bundler must be told too (Vite resolve.alias, tsup/esbuild via vite-tsconfig-paths/esbuild alias, or tsconfig-paths). tsc does not rewrite them in emitted JS.
For a library, emit dual ESM+CJS with a correct exports map — the exports map is the contract, file extensions are the proof. tsup config:
// tsup.config.ts
import { defineConfig } from "tsup";
export default defineConfig({
entry: ["src/index.ts"],
format: ["esm", "cjs"], // → index.js (esm) + index.cjs
dts: true, // → index.d.ts (+ .d.cts for cjs types)
sourcemap: true,
treeshake: true,
clean: true,
target: "node18",
external: [/^node:/], // never bundle node builtins
});
// package.json — types condition MUST come first in each block
{
"type": "module",
"exports": {
".": {
"import": { "types": "./dist/index.d.ts", "default": "./dist/index.js" },
"require": { "types": "./dist/index.d.cts", "default": "./dist/index.cjs" }
},
"./package.json": "./package.json"
},
"main": "./dist/index.cjs", // legacy fallback for old resolvers
"module": "./dist/index.js",
"types": "./dist/index.d.ts",
"sideEffects": false,
"files": ["dist"]
}
Keep peerDependencies (react, etc.) in external so you don't bundle two copies into the consumer.
App: split code with dynamic import(), then control chunks deliberately. Route-level const Page = lazy(() => import('./Page')) and import('heavy-lib') create async chunks automatically. Pull stable vendor deps into their own long-cached chunk:
// vite.config.ts
build: {
sourcemap: true,
rollupOptions: {
output: {
manualChunks: { vendor: ["react", "react-dom"] }, // or a function for finer control
},
},
chunkSizeWarningLimit: 500,
}
Don't over-split (HTTP/2 helps, but hundreds of tiny chunks add request + parse overhead). Split on real route/feature boundaries, not per-file.
Enable tree-shaking — it only works on static ESM. Author with import/export (no require, no module.exports); CJS interop defeats it. Mark the package "sideEffects": false (or list the few files with real side effects, e.g. ["**/*.css", "./src/polyfill.ts"]) so the bundler may drop unused modules. Annotate top-level calls that look impure but aren't with /*#__PURE__*/:
export const icon = /*#__PURE__*/ createIcon(path); // droppable if `icon` is unused
A "sideEffects": false lie (a module that does mutate global state on import) causes silently-missing behavior — list those files.
Inject env at build time via define/import.meta.env — never bake a secret. Static replacement only:
// vite: only VITE_* are exposed to client; access via import.meta.env.VITE_API_URL
// esbuild/tsup: define: { "process.env.NODE_ENV": JSON.stringify("production") }
Anything bundled for the browser is public. Put API keys/DB URLs behind a server route or read them at runtime on the server (process.env) — a define'd secret is grep-able in dist/. Gate dev-only code behind if (import.meta.env.DEV) / process.env.NODE_ENV !== "production" so it tree-shakes out of prod.
Always emit sourcemaps; choose by environment. sourcemap: true (full, external .map) for libraries and CI artifacts. For a public web app, ship hidden sourcemaps (uploaded to your error tracker, not referenced in the bundle) so stack traces de-minify without exposing source to every visitor. Never eval/inline sourcemaps in production.
Make builds fast and incremental. Use an esbuild/swc transform (Vite and tsup already do) instead of ts-loader/babel for the JS transform — 10–100× faster. Keep type-checking out of the bundle path: run tsc --noEmit (or vite build + a parallel tsc -b --watch) so a type error doesn't block fast iteration but still gates CI. Turn on the persistent cache (Vite caches in node_modules/.vite; for tsc -b use incremental: true + tsBuildInfoFile). Add --metafile (esbuild) / rollup-plugin-visualizer to find what's bloating the bundle.
Verify the output shape before declaring done (see Verify) — publint + @arethetypeswrong/cli catch the dual-package and types-resolution bugs that don't surface until a consumer installs you.
peerDependencies (react, etc.) into a library. Consumer gets two React copies → "invalid hook call." Mark peers external.tsc as the production bundler. It transpiles per-file but doesn't bundle, tree-shake, split, or rewrite paths — output has unresolved aliases and no chunking. Use a real bundler for JS; tsc only for .d.ts.hidden for public web), upload to the error tracker.ES5/old lib by reflex. Forces heavy down-leveling and polyfills for runtimes that support modern JS. Set target/lib to your actual lowest runtime.Gets machine-parseable JSON out of an LLM reliably — prefer provider-enforced grammar (OpenAI `response_format:{type:"json_schema",strict:true}`, Anthropic tool-calling / `tool_choice:{type:"tool"}`, Gemini `responseSchema`) over a "respond in JSON" prompt, define the contract once as a Pydantic/Zod model and validate every response (never trust the string), use constrained decoding / grammars for open weights (Outlines, llguidance, llama.cpp GBNF, vLLM `guided_json`), keep schemas SHALLOW with required fields + enums + `additionalProperties:false`, and build a repair-and-retry loop that handles refusals, `length`/`max_tokens` truncation, and streaming partial JSON (`partial-json-parser`). Schema-guided generation eliminates parse-error retries; validate-and-repair is the backstop, not the primary mechanism.
Builds production data grids that stay fast and accessible at 10k–1M+ rows — decide server-side vs client-side sort/filter/paginate by the dataset-fits-in-memory test (client only under ~10k rows, otherwise push to the API and treat the table as a controlled view of server state), ROW-VIRTUALIZE with TanStack Virtual or react-window so only the visible window mounts (fixed estimateSize, overscan 5–10, measureElement for dynamic rows, contain:strict, and a real scroll container — never table-layout:auto over thousands of rows), build the headless logic with TanStack Table v8 (or AG Grid when you need pinning/grouping/enterprise out of the box), add column resize/reorder/pin, inline edit with optimistic update + rollback on error, row selection with a stable rowId, full keyboard nav with roving tabindex over an ARIA grid (role=grid/row/gridcell, aria-sort, aria-rowcount/aria-rowindex so virtualization stays announced), position:sticky headers, streaming CSV export that doesn't block the main thread, and explici
Builds semantic/vector search — pick an embedding model + dimensionality (and whether to truncate Matryoshka dims) and the matching distance metric (cosine/dot/L2, normalize to unit length so cosine == dot and IP is correct), an ANN index with the recall/latency/memory tradeoff understood (HNSW M/efConstruction/efSearch for low-latency RAM-resident; IVF-PQ nlist/nprobe/PQ for billion-scale compressed; flat/exact for <100k) in pgvector/Qdrant/Milvus/FAISS/Pinecone, chunking + overlap + per-chunk metadata for filtering, HYBRID retrieval fusing BM25 + dense by Reciprocal Rank Fusion (RRF, k≈60) not score addition, a cross-encoder/Cohere reranker over the top-50→k, correct pre-filter-vs-ANN interaction (filterable HNSW, not post-filter that starves k), and offline eval with recall@k / nDCG@10 / MRR against a labeled qrels set. Quantize (scalar/PQ) only after measuring recall loss; tune efSearch/nprobe to a recall target, not a guess.
基于 SOC 职业分类