npm - @barefootjs/cli - Versions diffs - 0.30.6 → 0.31.1 - Mend

@barefootjs/cli 0.30.6 → 0.31.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (14) hide show

package/dist/docs/core/adapters/csr.md +17 -11
package/dist/docs/core/adapters/go-template-adapter.md +2 -8
package/dist/docs/core/adapters/hono-adapter.md +11 -17
package/dist/docs/core/adapters/perl-adapter.md +20 -11
package/dist/docs/core/adapters/php-adapter.md +20 -14
package/dist/docs/core/adapters/python-adapter.md +10 -7
package/dist/docs/core/adapters/ruby-adapter.md +10 -7
package/dist/docs/core/adapters/rust-adapter.md +10 -7
package/dist/docs/core/advanced/code-splitting.md +18 -142
package/dist/docs/core/advanced/xyflow-browser-bundle.md +11 -0
package/dist/docs/core/llms.txt +1 -1
package/dist/docs/core/quick-start.mdx +4 -4
package/dist/index.js +1512 -3692
package/package.json +7 -5

package/dist/docs/core/adapters/csr.md CHANGED Viewed

@@ -17,25 +17,31 @@ When you do control the server (Hono, Go, etc.), prefer SSR + hydration instead.
 ## Configuration
-Use `createConfig` from `@barefootjs/client/build` in `barefoot.config.ts`. It wires the in-package `CSRAdapter` and skips marked template output automatically — no `clientOnly` flag is needed:
+Pass `CSRAdapter` (from `@barefootjs/client/csr-adapter`) as the `adapter` option to `@barefootjs/vite`'s `barefoot()` plugin. Its `generate()` always returns empty output — CSR has no template-language backend — so `templates` stays unset; the Vite plugin verifies that claim itself:
 ```typescript
-// barefoot.config.ts
-import { createConfig } from '@barefootjs/client/build'
-export default createConfig({
-  components: ['./components'],
-  outDir: 'dist',
+// vite.config.ts
+import { defineConfig } from 'vite'
+import { barefoot } from '@barefootjs/vite'
+import { CSRAdapter } from '@barefootjs/client/csr-adapter'
+export default defineConfig({
+  build: { outDir: 'dist' },
+  plugins: [
+    barefoot({
+      adapter: new CSRAdapter(),
+      components: ['./components'],
+    }),
+  ],
 })
 ```
-Build output:
+Build output (`vite build`):
 ```
 dist/
-└── components/
-    ├── barefoot.js        # client runtime bundle
-    └── Counter.client.js  # compiled component
+└── assets/
+    └── Counter.tsx-<hash>.js  # compiled component (imports the runtime as a shared chunk)
 ```
 ## API

package/dist/docs/core/adapters/go-template-adapter.md CHANGED Viewed

@@ -280,15 +280,9 @@ Client components register their scripts via the `.Scripts` interface:
 The `ScriptCollector` tracks needed scripts and renders `<script>` tags at page end. Each script loads at most once.
-## Importmap (externals)
+## Vendor code-splitting
-This adapter sets `importMapInjection: 'html-snippet'`, so when you configure [`externals`](../advanced/code-splitting.md), `bf build` emits a ready-to-include `barefoot-importmap.html` next to `barefoot-externals.json`. Parse the build output directory into your template set and include the snippet in your page `<head>`:
-```go-template
-{{ template "barefoot-importmap.html" . }}
-```
-See [Code splitting & externals](../advanced/code-splitting.md#template-string-adapters) for what the snippet contains and how the manifest is generated.
+Vendor code-splitting is Vite's job now, via stock `build.rollupOptions.output.manualChunks` — see [Vendor code-splitting](../advanced/code-splitting.md). There is no BarefootJS-specific importmap manifest to generate or include: Vite resolves and bundles component + vendor chunks ahead of time, and `combineGoTypes`'s generated `components.go` only carries type definitions, not asset URLs.
 ## Go Helper Functions

package/dist/docs/core/adapters/hono-adapter.md CHANGED Viewed

@@ -200,21 +200,15 @@ Loop markers (`<!--bf-loop-->...<!--bf-/loop-->`) are used for reconciliation. F
 ## Deploying to Cloudflare Workers
-`bf build` writes browser-served files (`barefoot.js`, `*.client.js`, vendor chunks) and server/build-only files (the SSR `.tsx` templates, `manifest.json`, `barefoot-externals.json`, `.bfemit.json`, `.buildcache.json`, `.dev/`) into the same `outDir`. With Workers Assets, `assets.directory` serves that whole directory, so a naive `wrangler deploy` would upload the server-only files too — shipping the SSR template source and build internals as publicly fetchable assets.
-To prevent this, `bf build` maintains a [`.assetsignore`](https://developers.cloudflare.com/workers/static-assets/#ignoring-assets) in `outDir` whenever the project targets Workers (detected by a `wrangler.toml` / `wrangler.json` / `wrangler.jsonc` next to `barefoot.config.ts`). The server/build-only outputs are listed in a managed block that's regenerated on every build:
-```
-# >>> barefoot managed block (generated by `bf build`) >>>
-# Server/build-only barefoot outputs — not browser-served. Regenerated on
-# every `bf build`; add your own entries outside this block.
-.bfemit.json
-.buildcache.json
-.dev/
-barefoot-externals.json
-components/Counter.tsx
-components/manifest.json
-# <<< barefoot managed block <<<
+`@barefootjs/hono/vite`'s `barefoot()` plugin takes separate `templates` and `build.outDir` options — the compiled SSR `.tsx` templates land under `templates` (a server-side source directory your app imports from), while Vite's own client build (`barefoot.js`, `*.client.js`, vendor chunks) lands under stock `build.outDir`. Point Workers Assets' `assets.directory` at `build.outDir` only; the SSR template directory never needs to be — and should not be — publicly served. No `.assetsignore` bookkeeping is required: the two output trees are separate directories by construction, e.g.:
+```ts
+// vite.config.ts
+export default defineConfig({
+  build: { outDir: 'dist/static/components' }, // → assets.directory
+  plugins: barefoot({
+    components: ['components'],
+    templates: 'dist/components',              // server-only, not deployed as an asset
+  }),
+})
 ```
-Anything you add outside the managed markers is preserved across rebuilds. The browser-served outputs (`barefoot.js`, `*.client.js`, vendor chunks) are intentionally left out so they still deploy.

package/dist/docs/core/adapters/perl-adapter.md CHANGED Viewed

@@ -66,14 +66,18 @@ Scaffold a runnable starter:
 npm create barefootjs@latest -- --adapter mojo
 ```
-Configure the build (`barefoot.config.ts`):
+Configure the build (`vite.config.ts`):
 ```typescript
-import { createConfig } from '@barefootjs/mojolicious/build'
-export default createConfig({
-  components: ['./components'],
-  outDir: 'dist',
+import { defineConfig } from 'vite'
+import { barefoot } from '@barefootjs/mojolicious/vite'
+export default defineConfig({
+  build: { outDir: 'dist/client' },
+  plugins: barefoot({
+    components: ['./components'],
+    templates: 'dist/templates',
+  }),
 })
 ```
@@ -108,11 +112,16 @@ npm create barefootjs@latest -- --adapter xslate
 ```
 ```typescript
-import { createConfig } from '@barefootjs/xslate/build'
-export default createConfig({
-  components: ['./components'],
-  outDir: 'dist',
+// vite.config.ts
+import { defineConfig } from 'vite'
+import { barefoot } from '@barefootjs/xslate/vite'
+export default defineConfig({
+  build: { outDir: 'dist/client' },
+  plugins: barefoot({
+    components: ['./components'],
+    templates: 'dist/templates',
+  }),
 })
 ```

package/dist/docs/core/adapters/php-adapter.md CHANGED Viewed

@@ -63,18 +63,21 @@ is shared unchanged between `TwigBackend` and `BladeBackend`.
 npm install @barefootjs/twig
 ```
-Configure the build (`barefoot.config.ts`):
+Configure the build (`vite.config.ts`):
 ```typescript
-import { createConfig } from '@barefootjs/twig/build'
-export default createConfig({
-  components: ['./src/components'],
-  outDir: './dist',
+import { defineConfig } from 'vite'
+import { barefoot } from '@barefootjs/twig/vite'
+export default defineConfig({
+  plugins: barefoot({
+    components: ['./src/components'],
+    templates: './dist/templates',
+  }),
 })
 ```
-`bf build` emits `.twig` templates plus client JS under `outDir`. On the PHP
+`vite build` emits `.twig` templates plus client JS under `templates` / Vite's own `build.outDir`. On the PHP
 side, require `barefootjs/twig` via Composer and point a `TwigBackend` at the
 emitted templates — it builds a `FilesystemLoader`-backed `Twig\Environment`
 with the defaults the templates assume (`autoescape: 'html'`,
@@ -105,18 +108,21 @@ backends.
 npm install @barefootjs/blade
 ```
-Configure the build (`barefoot.config.ts`):
+Configure the build (`vite.config.ts`):
 ```typescript
-import { createConfig } from '@barefootjs/blade/build'
-export default createConfig({
-  components: ['./src/components'],
-  outDir: './dist',
+import { defineConfig } from 'vite'
+import { barefoot } from '@barefootjs/blade/vite'
+export default defineConfig({
+  plugins: barefoot({
+    components: ['./src/components'],
+    templates: './dist/templates',
+  }),
 })
 ```
-`bf build` emits `.blade.php` templates plus client JS under `outDir`. Blade
+`vite build` emits `.blade.php` templates plus client JS under `templates` / Vite's own `build.outDir`. Blade
 runs on `illuminate/view` used **standalone** — no Laravel application or
 service container required. Construct a `Factory` (`Filesystem` + an event
 `Dispatcher` + an `EngineResolver` registering a `blade` engine over a

package/dist/docs/core/adapters/python-adapter.md CHANGED Viewed

@@ -55,18 +55,21 @@ array/string helpers, `spread_attrs`, `query`, …).
 npm install @barefootjs/jinja
 ```
-Configure the build (`barefoot.config.ts`):
+Configure the build (`vite.config.ts`):
 ```typescript
-import { createConfig } from '@barefootjs/jinja/build'
-export default createConfig({
-  components: ['./src/components'],
-  outDir: './dist',
+import { defineConfig } from 'vite'
+import { barefoot } from '@barefootjs/jinja/vite'
+export default defineConfig({
+  plugins: barefoot({
+    components: ['./src/components'],
+    templates: './dist/templates',
+  }),
 })
 ```
-`bf build` emits `.jinja` templates plus client JS under `outDir`. On the
+`vite build` emits `.jinja` templates plus client JS under `templates` / Vite's own `build.outDir`. On the
 Python side, vendor `python/barefootjs/` (from `@barefootjs/jinja`) into
 your app and render a component by constructing a `jinja2.Environment` over
 a `FileSystemLoader` pointed at the emitted templates, with the exact

package/dist/docs/core/adapters/ruby-adapter.md CHANGED Viewed

@@ -48,18 +48,21 @@ that already produce finished HTML (e.g. `spread_attrs`) share one
 npm install @barefootjs/erb
 ```
-Configure the build (`barefoot.config.ts`):
+Configure the build (`vite.config.ts`):
 ```typescript
-import { createConfig } from '@barefootjs/erb/build'
-export default createConfig({
-  components: ['./components'],
-  outDir: 'dist',
+import { defineConfig } from 'vite'
+import { barefoot } from '@barefootjs/erb/vite'
+export default defineConfig({
+  plugins: barefoot({
+    components: ['./components'],
+    templates: 'dist/templates',
+  }),
 })
 ```
-`bf build` emits one `.erb` file per component plus the client JS bundle. On
+`vite build` emits one `.erb` file per component plus the client JS bundle. On
 the Ruby side, vendor `lib/barefoot_js.rb` (from `@barefootjs/erb`) into your
 app and construct the ERB backend against the output directory:

package/dist/docs/core/adapters/rust-adapter.md CHANGED Viewed

@@ -78,18 +78,21 @@ array/string helpers, `spread_attrs`, `query`, …).
 npm install @barefootjs/rust
 ```
-Configure the build (`barefoot.config.ts`):
+Configure the build (`vite.config.ts`):
 ```typescript
-import { createConfig } from '@barefootjs/rust/build'
-export default createConfig({
-  components: ['./src/components'],
-  outDir: './dist',
+import { defineConfig } from 'vite'
+import { barefoot } from '@barefootjs/rust/vite'
+export default defineConfig({
+  plugins: barefoot({
+    components: ['./src/components'],
+    templates: './dist/templates',
+  }),
 })
 ```
-`bf build` emits `.j2` templates plus client JS under `outDir`. On the Rust
+`vite build` emits `.j2` templates plus client JS under `templates` / Vite's own `build.outDir`. On the Rust
 side, depend on the `barefootjs` crate, build the `Environment` via
 `build_environment` (per the contract above), and render a component
 through a `RenderSession` + root `BfInstance`:

package/dist/docs/core/advanced/code-splitting.md CHANGED Viewed

@@ -1,157 +1,33 @@
 ---
 title: Vendor code-splitting
-description: Split large vendor libraries into separately-cached browser chunks via barefoot.config.ts externals
+description: Split large vendor libraries into separately-cached browser chunks via Vite's own `manualChunks`
 ---
 # Vendor code-splitting
-Apps that embed large libraries (xyflow, yjs, etc.) alongside BarefootJS components can reach 700–800 KB of client JS on first visit. Splitting those libraries out as separate browser chunks dramatically cuts repeat-visit transfer:
+Apps that embed large libraries (xyflow, yjs, etc.) alongside BarefootJS components can reach 700–800 KB of client JS on first visit. Splitting those libraries out as separate browser chunks dramatically cuts repeat-visit transfer.
-- **Cold visit**: ~36 % smaller because the common vendor bundle is served from disk cache
-- **Warm visit**: ~70 % faster because only the changed component JS hits the network
-## Configuration
-Add an `externals` map to `barefoot.config.ts`. The CLI copies each package's browser-ready bundle to your output directory and emits `barefoot-externals.json`.
+BarefootJS has no config of its own for this — vendor code-splitting is Vite's job. Use stock Vite/Rollup config alongside the `barefoot()` plugin:
 ```ts
-// barefoot.config.ts
-import { defineConfig } from 'barefootjs/config'
-import { HonoAdapter } from '@barefootjs/hono/adapter'
+// vite.config.ts
+import { defineConfig } from 'vite'
+import { barefoot } from '@barefootjs/vite'
 export default defineConfig({
-  adapter: HonoAdapter(),
-  minify: true,
-  externalsBasePath: '/static/components/',
-  externals: {
-    // Local chunk — CLI copies the package's umd/unpkg/import entry
-    '@barefootjs/xyflow': true,
-    // Preload hint — adds <link rel="modulepreload"> to the importmap manifest
-    yjs: { preload: true },
-    // CDN passthrough — no local copy, importmap points at the remote URL
-    lodash: { url: 'https://esm.sh/lodash@4.17.21', preload: true },
+  plugins: [barefoot({ /* ... */ })],
+  build: {
+    rollupOptions: {
+      output: {
+        // Split heavy vendor libraries into their own cacheable chunk.
+        manualChunks: {
+          xyflow: ['@barefootjs/xyflow'],
+          yjs: ['yjs'],
+        },
+      },
+    },
   },
 })
 ```
-### ExternalSpec
-| Shape | Effect |
-|---|---|
-| `true` | Copy browser-ready entry to `outDir`, auto-resolve via `umd` → `unpkg` → `jsdelivr` → `import` |
-| `{ preload: true }` | Same as `true`, also adds a preload hint to `barefoot-externals.json` |
-| `{ url: string }` | CDN passthrough — skip copy, use URL as-is in importmap |
-| `{ url: string, preload: true }` | CDN passthrough + preload hint |
-### externalsBasePath
-URL prefix for vendor chunk entries in the emitted importmap. Defaults to `/<runtimeSubdir>/` (e.g., `/components/` when using the default output layout). Set this explicitly if your static files are served from a different path:
-```ts
-externalsBasePath: '/static/components/'
-```
-## What the CLI emits
-After build, `dist/barefoot-externals.json` contains three sections:
-```json
-{
-  "importmap": {
-    "imports": {
-      "@barefootjs/xyflow":          "/static/components/xyflow.js",
-      "yjs":                         "/static/components/yjs.js",
-      "lodash":                      "https://esm.sh/lodash@4.17.21",
-      "@barefootjs/client":          "/static/components/barefoot.js",
-      "@barefootjs/client/runtime":  "/static/components/barefoot.js",
-      "@barefootjs/client/reactive": "/static/components/barefoot.js"
-    }
-  },
-  "preloads": [
-    "/static/components/yjs.js",
-    "https://esm.sh/lodash@4.17.21"
-  ],
-  "externals": [
-    "@barefootjs/xyflow",
-    "yjs",
-    "lodash",
-    "@barefootjs/client",
-    "@barefootjs/client/runtime",
-    "@barefootjs/client/reactive"
-  ]
-}
-```
-**`@barefootjs/client*` dedup is automatic.** Whenever `externals` is non-empty, the three `@barefootjs/client*` importmap entries are added unconditionally. This prevents reactive-primitive duplication — a class of silent failure where forgetting one entry inlines a second copy of the reactive runtime and breaks signals / context across the module boundary (see #927).
-## Wiring the importmap into your renderer
-Read `barefoot-externals.json` at startup and inject it into the HTML shell:
-```tsx
-// renderer.tsx
-import externalsManifest from './dist/barefoot-externals.json'
-const importMapScript = JSON.stringify(externalsManifest.importmap)
-export const renderer = jsxRenderer(({ children }) => (
-  <html>
-    <head>
-      <script type="importmap" dangerouslySetInnerHTML={{ __html: importMapScript }} />
-      {externalsManifest.preloads.map(href => (
-        <link rel="modulepreload" href={href} />
-      ))}
-    </head>
-    <body>
-      {children}
-      <BfScripts />
-    </body>
-  </html>
-))
-```
-## Template-string adapters
-Some adapters have no render-time component like Hono's `BfImportMap` to read the manifest — they target a template-string language where you hand-write the HTML `<head>`. An adapter declares this by setting `importMapInjection: 'html-snippet'` (component-based adapters set `'component'` instead). For `html-snippet` adapters, `bf build` also emits a ready-to-include **`barefoot-importmap.html`** snippet next to `barefoot-externals.json`, generated from the same manifest:
-```html
-<!-- dist/barefoot-importmap.html -->
-<script type="importmap">{"imports":{"@barefootjs/client":"/static/components/barefoot.js","yjs":"/static/components/yjs.js","lodash":"https://esm.sh/lodash@4.17.21"}}</script>
-<link rel="modulepreload" href="/static/components/yjs.js" crossorigin>
-<link rel="modulepreload" href="https://esm.sh/lodash@4.17.21" crossorigin>
-```
-Include this file in your page `<head>` using your template language's native include directive, and wire the build's output directory into the template search path so it resolves. The exact directive is language-specific — see your adapter's own documentation for the form it uses.
-Which strategy an adapter uses is the single source of truth in its `TemplateAdapter.importMapInjection` value, enforced for every adapter by the cross-adapter importmap-injection contract in `@barefootjs/adapter-tests` — so this page does not need an entry per adapter.
-## Using the externals list in your own bun build
-The `externals` array in `barefoot-externals.json` lists every package that the browser will load via the importmap. Pass these as `--external` flags when bundling your app entries:
-```sh
-# Shell — build your DeskCanvas.tsx with all externals applied
-EXTERNALS=$(jq -r '.externals[]' dist/barefoot-externals.json | sed 's/^/--external /' | tr '\n' ' ')
-bun build worker/components/canvas/DeskCanvas.tsx \
-  --outfile dist/static/components/canvas.js \
-  --format esm --minify \
-  $EXTERNALS
-```
-Or in JavaScript:
-```ts
-import manifest from './dist/barefoot-externals.json'
-await Bun.build({
-  entrypoints: ['./worker/components/canvas/DeskCanvas.tsx'],
-  outdir: './dist/static/components',
-  naming: 'canvas.[ext]',
-  format: 'esm',
-  minify: true,
-  external: manifest.externals,
-})
-```
+Vite's dev server and production build both content-hash and cache these chunks automatically — no manifest to wire up by hand, and no `--external` flags to compute for a separate bundler pass. See [Vite's own code-splitting docs](https://vite.dev/guide/build.html#chunking-strategy) for `manualChunks`, dynamic `import()`, and `build.rollupOptions.output`.

package/dist/docs/core/advanced/xyflow-browser-bundle.md CHANGED Viewed

@@ -49,6 +49,17 @@ cp node_modules/@barefootjs/xyflow/dist/xyflow.browser.min.js.map \
 The three `@barefootjs/client*` entries all pointing at the same file is what makes the browser deduplicate them into a single module instance, so reactive primitives share one `Listener`/`Owner` global.
+Two things to get right when hand-writing this snippet:
+- **Escape `<` inside the importmap JSON.** A mapped URL containing `</script>` (unlikely for a static local path like the ones above, but possible if a URL is assembled dynamically) would close the `<script type="importmap">` element early. Before writing the serialized JSON into the `<script>` tag, replace every `<` character with its six-character Unicode escape for code point U+003C (backslash, `u`, `0`, `0`, `3`, `c`) — the JSON parser decodes that escape straight back to the original character, so the mapping itself is unaffected.
+- **Add `crossorigin` if you also `modulepreload` a cross-origin URL** — e.g. pointing straight at the unpkg/jsDelivr URL from "package.json fields" below instead of the copied local file:
+  ```html
+  <link rel="modulepreload" href="https://unpkg.com/@barefootjs/xyflow" crossorigin>
+  ```
+  The actual `import` of a cross-origin module is always a CORS fetch, so without `crossorigin` the preload request doesn't match it — the browser discards the preload and fetches the module a second time. Harmless to include on a same-origin preload too, since the credentials mode is the same either way.
 ## package.json fields
 The file is also exposed via the `umd` export condition and the `unpkg`/`jsdelivr` top-level fields:

package/dist/docs/core/llms.txt CHANGED Viewed

@@ -52,7 +52,7 @@
 ## Advanced
-- [Vendor code-splitting](https://barefootjs.dev/docs/advanced/code-splitting.md): Split large vendor libraries into separately-cached browser chunks via barefoot.config.ts externals
+- [Vendor code-splitting](https://barefootjs.dev/docs/advanced/code-splitting.md): Split large vendor libraries into separately-cached browser chunks via Vite's own `manualChunks`
 - [Compiler Internals](https://barefootjs.dev/docs/advanced/compiler-internals.md): How the BarefootJS compiler transforms JSX into marked templates and client JavaScript.
 - [Error Codes Reference](https://barefootjs.dev/docs/advanced/error-codes.md): BF-prefixed compiler error codes with explanations and fixes.
 - [IR Schema Reference](https://barefootjs.dev/docs/advanced/ir-schema.md): JSON tree structure of the Intermediate Representation consumed by adapters and client-JS generation.

package/dist/docs/core/quick-start.mdx CHANGED Viewed

@@ -33,7 +33,7 @@ npm run dev
 `npm run dev` runs three processes in parallel:
-- `bf build --watch` — the BarefootJS compiler. Watches `components/` and emits marked templates plus client JS to `public/components/`.
+- `vite dev` — the BarefootJS compiler, wired in as a Vite plugin. Watches `components/` and serves marked templates plus client JS from `public/components/`.
 - `unocss --watch` — scans your JSX for utility classes and writes `public/uno.css`.
 - `wrangler dev --live-reload` — Cloudflare's local Workers runtime. Serves the app and reloads the browser on rebuilds.
@@ -52,8 +52,8 @@ my-app/
 ├── public/                 # Static assets served by Workers
 │   ├── tokens.css          # CSS design tokens
 │   ├── styles.css          # Counter + page styles
-│   └── components/         # Generated client JS (bf build writes here)
-├── barefoot.config.ts      # Compiler + paths config
+│   └── components/         # Generated client JS (vite build writes here)
+├── vite.config.ts          # Compiler (barefoot plugin) + Vite build config
 ├── wrangler.jsonc          # Cloudflare Workers config
 └── uno.config.ts           # UnoCSS scan patterns
 ```
@@ -148,7 +148,7 @@ When you're ready to ship:
 npm run deploy
 ```
-This runs `bf build`, generates the final `uno.css`, and calls `wrangler deploy`. The first deploy will prompt you to log into Cloudflare. After that, your app is live on `*.workers.dev`.
+This runs `vite build`, generates the final `uno.css`, and calls `wrangler deploy`. The first deploy will prompt you to log into Cloudflare. After that, your app is live on `*.workers.dev`.
 ## Next steps