@asd14/vblocks
v7.1.0
Published
Zero-config React builds of an SPA (single-page application), as a folder or a single HTML file
Maintainers
Readme
@asd14/vblocks
Zero-config React builds of an SPA (single-page application), as a folder or a single HTML file
VBlocks is a zero-config React bundler, like Create React App or Parcel. It has no SSR (server-side rendering) or SSG (static site generation), as Next.js does.
✂️ Zero config
- Needs only
src/index.tsxandsrc/index.html
🔋 Maximal support
- SWC, PostCSS, CSS Modules, MDX, React Refresh,
.envfiles
📦 Several apps, one install
- Apps share one
package.jsonandnode_modules/. A new app reuses the installed packages
🤖 Built for AI agents
use-vblocksskill: teaches an agent to write, serve and build a VBlocks app- Agentation in development: click an element and write what to change. The agent gets the annotation with the element's selector, text and React components
- Small context:
- By default, the agent does not write, read or fix a Webpack, PostCSS or SWC config
- VBlocks shows you color, icons and a header in a terminal. When an agent runs VBlocks, it gets the same facts without them
Table of contents
- Quick Start
- How to
- Keep several apps in one project
- Use
.envvariables - Import from
src/with@self - Use CSS Modules
- Import a file as text
- Write a page in Markdown or MDX
- Pick the browsers
- Replace a default config
- Style with Tailwind
- Send UI annotations to an AI agent
- Open the page from another device
- Build a single HTML file
- Add VBlocks to an existing project
- More docs
- Develop
- License
Quick Start
[!IMPORTANT]
VBlocks needs Node^22.22.3,^24.15.0or>=26.0.
Scaffold a minimal React project
npx @asd14/vblocks init my-vblocks-app cd my-vblocks-app npm installmy-vblocks-app/ ├─ src/ │ ├─ index.tsx # mounts App, and the Agentation toolbar in development │ ├─ index.app.tsx # App, your code starts here │ ├─ index.html │ └─ index.css ├─ .env.example ├─ .gitignore ├─ tsconfig.json └─ package.json # react, react-dom, agentation and the vblocks scriptsStart a development server
npx vblocks serveThe server runs at
http://localhost:8080, or the next free port. It opens the page in the browser.Build
npx vblocks build # production bundle in dist/
How to
Keep several apps in one project
Several apps, eg. demos or MVP sketches, can share one package.json and one
node_modules/. The project folder
contains the plumbing, and each
app folder contains one app:
Create the project folder
npx @asd14/vblocks init sketches --only plumbingsketches/ ├─ .gitignore └─ package.jsonAdd an app
npx @asd14/vblocks init sketches/flow-diagram --template xyflow --only app cd sketches npm installsketches/ + ├─ flow-diagram/ + │ ├─ src/ # the files of the xyflow template + │ ├─ .env.example + │ ├─ postcss.config.js + │ └─ tsconfig.json ├─ .gitignore ! └─ package.json # + @xyflow/react, tailwindcss, @tailwindcss/postcss, ! # cssnano, agentationStart a development server for one app
npx vblocks serve --prefix flow-diagram
Use .env variables
Create a
.envfile in your app folderAPI_URL=https://api.example.comRead 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, throughprocess.env. Anyone who loads the page can read it.
[!NOTE]
The client types declare onlyprocess.env. The browser has no other part of Node'sprocess.
Import from src/ with @self
VBlocks resolves @self to the src/ of your app folder:
// Instead of: import { Button } from "../../../components/button.tsx"
import { Button } from "@self/components/button.tsx"[!NOTE]
VBlocks compiles TypeScript with SWC and does not typecheck. Runtscyourself. Yourtsconfig.jsonneeds the same alias as Webpack.
Thetsconfig.jsonthatvblocks initwrites 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"]} />
Each class name is a bare hash in production mode, and [local]__[hash] in
development mode.
[!NOTE]
The client types declare each*.module.cssimport as an object of class names.
Import a file as text
Add ?raw to the import path, as in Vite:
import greeting from "./greeting.txt?raw"
// greeting => "Hello from a text file\n"[!NOTE]
The client types declare each?rawimport as astring.
Write a page in Markdown or MDX
Import an .md or .mdx file as a React component:
import Intro from "./intro.mdx"
const App = () => <Intro />Pass components to replace the element MDX renders for a tag, eg. each #
heading:
<Intro components={{ h1: Title }} />[!NOTE]
The client types declare each.mdand.mdximport as a React component.
Pick the browsers
SWC, Webpack and postcss-preset-env compile for the browsers of the app's
browserslist config, from the app folder up:
- a
.browserslistrc - or the
browserslistfield ofpackage.json
Without one, they compile for the VBlocks default, > 0.25%, not dead.
Eject the default into your app folder
npx vblocks eject browserslist > .browserslistrcUpdate the query, see the queries of browserslist
Replace a default config
A config in your app folder replaces the VBlocks default of the same name:
webpack.config.jspostcss.config.js, the default runs:postcss-preset-env, which compiles nesting,oklch()andcolor-mix()for older browsers and adds vendor prefixescssnanoinproduction
.swcrc.browserslistrc, the default> 0.25%, not dead
Eject the default into your app folder
cd my-vblocks-app npx vblocks eject swc > .swcrcAn ejected config loads its plugins and loaders from the project folder, not from VBlocks. Install them there.
Update the ejected file
[!NOTE]
VBlocks does not merge your config with the default, with two exceptions:
.swcrc -> env.path: VBlocks adds the app folder when yours is missing, so SWC reads the browserslist config.swcrc -> jsc.transform.react.refresh: VBlocks adds the React Refresh transform whenserveruns indevelopmentmode
Style with Tailwind
VBlocks does not include Tailwind. Add it through a postcss.config.js in your
app folder:
[!NOTE]
Thexyflowandxyflow-tabstemplates ofvblocks inithave this setup.
Install Tailwind, its PostCSS plugin and cssnano, which the ejected config imports
npm install --save-dev tailwindcss @tailwindcss/postcss cssnanoEject the default PostCSS config into your app folder
npx vblocks eject postcss > postcss.config.jsReplace
postcss-preset-envwith 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-envrewrites Tailwind's@layerrules 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/.- Without it, Tailwind scans the folder you run VBlocks from. With
--prefix, that is the project folder, which contains every app. Each app's CSS then also gets the classes of the other apps
- Without it, Tailwind scans the folder you run VBlocks from. With
Send UI annotations to an AI agent
Agentation is a toolbar to send annotations on the
UI to a coding agent. vblocks init writes it into src/index.tsx. The toolbar
shows in development mode, the default of serve.
Configure the agentation-mcp server, see Agentation's docs
Set
AGENTATION_ENDPOINTin the.envof the app folder, as in.env.exampleAGENTATION_ENDPOINT=http://localhost:4747
[!NOTE]
Agentation's license is PolyForm Shield 1.0.0, not MIT. To remove Agentation, remove its lines fromsrc/index.tsxand runnpm uninstall agentation.
Open the page from another device
The server listens on localhost, so another device cannot open the page. Pass
-- --host 0.0.0.0 to expose it to the network:
npx vblocks serve -- --host 0.0.0.0Build a single HTML file
--single-file builds one standalone dist/index.html, every asset inlined,
with no robots.txt:
npx vblocks build --single-file[!IMPORTANT]
A browser opens it from disk. There,history.pushStateto another path throws, so keep the route in the URL hash.
Add VBlocks to an existing project
Install VBlocks
npm install --save-dev @asd14/vblocks # needs react and react-dom ^18 or ^19Add the client types and the
@selfalias to yourtsconfig.json{ "compilerOptions": { + "types": ["@asd14/vblocks/client"], + "paths": { "@self/*": ["./src/*"] } } }
[!NOTE]
An import may name the file tsc emits, eg../button.jsforbutton.tsx, as TypeScript'snodenextresolution requires. VBlocks resolves it tobutton.tsx.
Put your entry at
src/index.tsxand your page atsrc/index.htmlRemove the tag that loads your entry from
src/index.html, eg. Vite's<script type="module" src="/src/main.tsx"></script>VBlocks builds
dist/index.htmlfromsrc/index.htmland adds the script and stylesheet tags to it.Start a development server
npx vblocks serve
More docs
- Reference: every command, template and environment variable, in docs/REFERENCE.md
- Decisions: why the code is this way, in docs/DECISIONS.md
- Release history: what each version added, fixed and removed, in GitHub releases
Develop
vblocks/
├── bin/ # vblocks, and one file per command in vblocks.d/
├── defaults/ # the configs that eject prints
├── template/ # the templates of init
└── types/ # client.d.ts| Script | Does |
| :------------------ | :----------------------------------------------------------------- |
| npm run lint | Runs ESLint |
| npm run typecheck | Typechecks the code and the client types |
| npm run unit-test | Typechecks, builds and serves every template vblocks init writes |
License
MIT
