@asd14/vblocks

中文文档

6.2.0发布于 2026/10/29MITTypeScriptES Module构建来源已验证近 30 天下载 1920

Zero-config React builds, as a static site or a single HTML file

文档目录15 节

Table of contents
Quick Start
Several apps in one project
Vocabulary
How to
Use environment variables
Stop using ../../../ everywhere
Use CSS Modules
Replace a default config
Style with Tailwind
Add VBlocks to an existing project
References
Commands
Templates
License

@asd14/vblocks

Zero-config React builds, as a static site or a single HTML file

✂️ Zero config
Needs only src/index.tsx and src/index.html

🔋 Maximal support
SWC, PostCSS, CSS Modules, MDX, React Refresh, Dotenv

📦 Several apps, one install
Apps share one package.json and node_modules/. A new app reuses the installed packages

🤖 Optimized for AI agents
The agent's context holds only the app: no Webpack, PostCSS or TypeScript config to write, read or fix

[!IMPORTANT]
VBlocks needs Node ^22.22.3, ^24.15.0 or >=26.0.

Quick Start
- Several apps in one project
Vocabulary
How to
References
- Commands
- Templates
License

Quick Start

Scaffold a minimal React project

npx @asd14/vblocks init my-vblocks-app
cd my-vblocks-app
npm install

my-vblocks-app/
 ├─ src/
 │    ├─ index.tsx
 │    ├─ index.html
 │    └─ index.css
 ├─ .gitignore
 ├─ tsconfig.json
 └─ package.json      # react, react-dom and the vblocks scripts

Start a development server
```
npx vblocks serve
```

Build

npx vblocks build               # production bundle in dist/
npx vblocks build --single-file # one dist/index.html, every asset inlined

Several apps in one project

Several apps, eg. demos or MVP sketches, can share one package.json and one node_modules/:

Add the plumbing

npx @asd14/vblocks init sketches --only plumbing

sketches/
 ├─ .gitignore
 └─ package.json

Add an app

npx @asd14/vblocks init sketches/flow-diagram --template xyflow --only app
cd sketches
npm install

 sketches/
+ ├─ flow-diagram/
+ │   ├─ src/          # the files of the xyflow template
+ │   ├─ postcss.config.js
+ │   └─ tsconfig.json
  ├─ .gitignore
! └─ package.json      # + @xyflow/react, tailwindcss, @tailwindcss/postcss, cssnano

Start a development server for one app

npx vblocks serve --prefix flow-diagram

Vocabulary

Term	Means
Plumbing	The project files `init` writes: `package.json`, `.gitignore`
Project folder	The folder with `package.json`
App folder	The folder with `src/index.tsx` and `src/index.html`
Bundle	The files `build` writes to `dist/`

How to

Use environment variables

Add a .env file to your app folder
```
API_URL=https://api.example.com
```
Read the variable in your code
```
const apiUrl = process.env["API_URL"]
```

Webpack replaces each process.env["NAME"] with the value of NAME, and undefined when .env does not set it. Webpack leaves out of the bundle every variable your code does not read.

[!WARNING]
Never expose a secret, eg. an API key, through process.env. Anyone who loads the page can read it.

[!NOTE]
The client types declare process.env and nothing else from Node, because Webpack replaces nothing else.

Stop using `../../../` everywhere

VBlocks resolves @self to the src/ of your app folder:

// Instead of: import { Component } from "../../../components"
import { Component } from "@self/components"

[!NOTE]
VBlocks compiles TypeScript with SWC and does not typecheck. Run tsc yourself. Your tsconfig.json needs the same alias as Webpack.
The tsconfig.json that vblocks init writes already has it. Otherwise, add:
 {
   "compilerOptions": {
+    "paths": { "@self/*": ["./src/*"] }
   }
 }

Use CSS Modules

Name the file *.module.css

/* src/button.module.css */
.primary-button {
  color: tomato;
}

Import it as an object

/* src/button.tsx */
import styles from "./button.module.css"

export const Button = () => <button className={styles.primaryButton} />

camelCase keys - .primary-button becomes styles.primaryButton
Class names - a bare hash in production mode, [local]__[hash] in development mode

[!NOTE]
The client types declare .css, image and font imports.

Replace a default config

Each config in your app folder replaces the default of the same name:

webpack.config.js
postcss.config.js
- postcss-preset-env, which compiles nesting, oklch() and color-mix() for older browsers and adds vendor prefixes
- cssnano in production
.swcrc
- browser targets > 0.25%, not dead

Eject the default into your app folder

cd flow-diagram
npx vblocks eject swc > .swcrc

Update the ejected file

[!NOTE]
VBlocks does not merge your config with the default, with two exceptions:

.swcrc -> env.targets: VBlocks adds the default when yours is missing

.swcrc -> jsc.transform.react.refresh: VBlocks adds the React Refresh transform when serve runs in development mode

Style with Tailwind

VBlocks does not include Tailwind. Add it through a postcss.config.js in your app folder:

[!NOTE]
The xyflow and xyflow-tabs templates of vblocks init have this setup.

Install Tailwind, the Tailwind plugin for PostCSS and cssnano, which the ejected config imports
```
npm install --save-dev tailwindcss @tailwindcss/postcss cssnano
```
Eject the default PostCSS config into your app folder
```
npx vblocks eject postcss > postcss.config.js
```

Replace postcss-preset-env with the Tailwind plugin

+import tailwindcss from "@tailwindcss/postcss"
 import cssnano from "cssnano"
-import postcssPresetEnv from "postcss-preset-env"

 export default ({ mode }) => ({
   plugins: [
-    postcssPresetEnv({ stage: 2 }),
+    tailwindcss({ optimize: mode === "production" }),
     ...(mode === "production" ? [cssnano({ preset: "default" })] : []),
   ],
 })

[!IMPORTANT]
Tailwind 4 compiles nesting and adds vendor prefixes itself. With both plugins, postcss-preset-env rewrites Tailwind's @layer rules into :not(#\#) selectors. The CSS file grows.

Add the Tailwind import to src/index.css
```
@import "tailwindcss" source(".");
```
source(".") limits Tailwind's class scan to the folder of the CSS file, src/.

[!NOTE]
Without source("."), Tailwind scans the current folder. With --prefix, you run VBlocks from the project folder, which holds every app. Each app's CSS then also gets the classes of the other apps.

Add VBlocks to an existing project

Install VBlocks

npm install --save-dev @asd14/vblocks    # needs react and react-dom ^18 or ^19

Add the client types and the @self alias to your tsconfig.json

 {
   "compilerOptions": {
+    "types": ["@asd14/vblocks/client"],
+    "paths": { "@self/*": ["./src/*"] }
   }
 }

Ensure index.tsx and index.html are in src/

[!NOTE]
VBlocks builds dist/index.html from src/index.html and adds the script and stylesheet tags to it. Drop the tag that loads your entry, eg. Vite's <script type="module" src="/src/main.tsx"></script>.

Start a development server
```
npx vblocks serve
```

References

Commands

Each command prints its own help with --help, eg. npx vblocks serve --help.

`vblocks init`

Write a template's plumbing, app, or both into <directory>.

vblocks init <directory>
  [--template <plain|xyflow|xyflow-tabs>]
  [--only <app|plumbing>]

<directory>
- The folder to write into. It must be missing or empty
--template (default: plain)
- The template to write, see Templates
--only (default: both)
- Write one part of the template
- plumbing: package.json, .gitignore
- app: src/, tsconfig.json and the template's configs. init adds the template's dependencies to the package.json of the project folder, the parent of <directory>. Without a package.json there, init fails

`vblocks serve`

Start the development server.

Runs at http://localhost:8080, or the next free port
Listens on localhost, so another device on your network, eg. a phone, cannot open the page
Opens the page in the browser

vblocks serve
  [--mode <development|production>]
  [--prefix <directory>]
  [--analyze]
  [--log-level <error|warn|info|verbose>]
  [-- <webpack option>...]

--mode (default: development)
- The Webpack mode
- React Refresh runs only in development
--prefix (default: the current folder)
- The app folder, which must exist
--analyze
- Run the bundle analyzer, on a free port
--log-level (default: warn)
- How much Webpack and its development server print
-- <webpack option>...
- Any webpack serve option
- serve passes each one to Webpack unchanged
- eg. -- --host 0.0.0.0, to listen on the network

`vblocks build`

Build the app into a bundle in the dist/ of the app folder.

By default, build:

Writes JS and CSS files with content-hashed names
Writes a react chunk, and a vendors chunk when your other dependencies total over 20 KB (10 KB in development)
Inlines jpg, gif, png and svg files up to 10 KB
Writes larger images to dist/ with content-hashed names
Writes woff, woff2, ttf and eot files to dist/fonts/
Copies src/public/favicon.svg and src/public/robots.txt of your app, or the defaults of VBlocks

vblocks build
  [--mode <development|production>]
  [--prefix <directory>]
  [--single-file|--single]
  [--log-level <error|warn|info|verbose>]
  [-- <webpack option>...]

--mode (default: production)
- The Webpack mode
- In production, build minifies JS, HTML and, with the default PostCSS config, CSS
--prefix (default: the current folder)
- The app folder, which must exist
--single-file|--single
- Write one standalone dist/index.html, every asset inlined
- A browser opens the file from disk, with no server and no network
- The bundle has no robots.txt
- Keep the route in the URL hash
  - On file://, history.pushState to another path throws
--log-level (default: warn)
- How much Webpack prints
-- <webpack option>...
- Any webpack build option
- build passes each one to Webpack unchanged
- eg. -- --devtool source-map, to write source maps

`vblocks eject`

Print a default config to stdout.

vblocks eject <webpack|postcss|swc>

<webpack|postcss|swc>
- The config to print

Run it in your app folder and save the output there, to replace the default:

npx vblocks eject webpack > webpack.config.js
npx vblocks eject postcss > postcss.config.js
npx vblocks eject swc > .swcrc

An ejected config loads its plugins and loaders from your project. Install them in the project folder, eg. postcss-preset-env and cssnano for the PostCSS config.

Templates

All templates scaffold src/index.html, src/index.css and tsconfig.json.

`plain`

"Hello World!" in src/index.tsx.

Adds no packages

`xyflow`

One diagram, and a details panel for the selected node or edge.

Adds @xyflow/react, tailwindcss, @tailwindcss/postcss and cssnano to the package.json of the project folder
Writes a postcss.config.js that configures Tailwind

src/
├── index.tsx           # the layout: header, diagram, details panel, the selected id
├── diagram.tsx         # the nodes and edges, placed and sized in grid cells
├── details.tsx         # the panel for the selected node or edge
└── utils/grid.ts       # CELL_SIZE and toPixels

`xyflow-tabs`

One tab per diagram, each with its own details panel.

Adds the same packages and postcss.config.js as xyflow

src/
├── index.tsx              # the layout: header, tab bar, details panel, the selected id
├── pages/
│   ├── build/
│   │   ├── diagram.tsx    # the nodes and edges of one tab, in grid cells
│   │   └── details.tsx    # the panel for its selected node or edge
│   └── serve/             # the same two files
├── ui/zoom-level.tsx      # the zoom level, and a Reset to 100%
└── utils/grid.ts          # CELL_SIZE and toPixels

License

MIT

版本与发布记录

@asd14/vblocks 共发布 14 个版本，首次发布于 2025/09/18；过去 12 个月发布了 13 个版本。最新版本附带 npm provenance 构建来源证明，可追溯到公开的 CI 构建记录。

版本	发布日期	距今
`6.2.0`latest	2026/10/29	10 天前
`6.1.0`	2026/10/23	16 天前
`6.0.0`	2026/10/20	19 天前
`5.4.0`	2026/10/17	22 天前
`5.3.0`	2026/10/17	22 天前
`5.2.0`	2026/10/17	22 天前

关于 @asd14/vblocks 的常见问题

@asd14/vblocks 是什么？

Zero-config React builds, as a static site or a single HTML file

如何安装 @asd14/vblocks？

在项目目录运行 npm install @asd14/vblocks，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：react（^18 || ^19）、react-dom（^18 || ^19）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。它还提供命令行工具 vblocks，可以用 npx vblocks 直接运行。

@asd14/vblocks 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

@asd14/vblocks 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node.js 20.19+ / 22.12+ 可以直接 require() 不含顶层 await 的 ES Module，更早的版本需要改用动态 import()。

@asd14/vblocks 需要什么版本的 Node.js？

package.json 的 engines 字段要求 Node.js ^22.22.3 || ^24.15.0 || >=26.0。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

@asd14/vblocks 可以商用吗？

@asd14/vblocks 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

@asd14/vblocks 的下载量有多少？

根据 npm 官方下载统计，@asd14/vblocks 在 2026/10/07 – 2026/11/05 这 30 天内被下载 1,920 次，日均约 64 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

@asd14/vblocks 还在维护吗？

最新版本 6.2.0 发布于 2026/10/29（10 天前）；至今共发布 14 个版本，其中过去 12 个月发布了 13 个；首次发布于 2025/09/18。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。

npm install @asd14/vblocks

pnpmpnpm add @asd14/vblocks
yarnyarn add @asd14/vblocks
bunbun add @asd14/vblocks

peer 依赖react ^18 || ^19react-dom ^18 || ^19

npm 7+ 与 pnpm 8+ 会自动安装必需的 peer 依赖，Yarn 需手动安装。

命令行npx vblocks

在你的项目目录中运行此命令。

近 30 天下载

1,920

约 1920 次日均 64 次

统计周期 2026/10/07 – 2026/11/05
数据来自 npm 官方下载统计，1 天前更新

最新版本6.2.0发布于 10 天前

开源许可MIT宽松许可

包体积125 kB42 个文件 · 解压后

运行依赖20 个另有 2 个 peer 依赖

模块格式ES Module无副作用，可 tree-shake

TypeScript自带类型

Node.js^22.22.3 || ^24.15.0 || >=26.0

发布版本14 个近 12 个月 13 个

首次发布2025/09/181.1 年前

元数据更新2026/10/29

每一个软件包背后，
都有分享与创造的人。

@asd14/vblocks

@asd14/vblocks

Table of contents

Quick Start

Several apps in one project

Vocabulary

How to

Use environment variables

Stop using ../../../ everywhere

Use CSS Modules

Replace a default config

Style with Tailwind

Add VBlocks to an existing project

References

Commands

vblocks init

vblocks serve

vblocks build

vblocks eject

Templates

plain

xyflow

xyflow-tabs

License

版本与发布记录

关于 @asd14/vblocks 的常见问题

@asd14/vblocks 是什么？

如何安装 @asd14/vblocks？

@asd14/vblocks 支持 TypeScript 吗？

@asd14/vblocks 支持 ESM 还是 CommonJS？

@asd14/vblocks 需要什么版本的 Node.js？

@asd14/vblocks 可以商用吗？

@asd14/vblocks 的下载量有多少？

@asd14/vblocks 还在维护吗？

Stop using `../../../` everywhere

`vblocks init`

`vblocks serve`

`vblocks build`

`vblocks eject`

`plain`

`xyflow`

`xyflow-tabs`