@entryscape/blocks-bundler

Convention-based Rollup plugin + CLI that bundles an EntryScape Blocks source tree into a single IIFE script which assigns to window.__entryscape_config.

Quickstart

From an empty directory on a fresh machine — no install needed, npx fetches the package on demand:

mkdir my-blocks && cd my-blocks
npx @entryscape/blocks-bundler create

(Equivalent on pnpm: pnpm dlx @entryscape/blocks-bundler create.)

If the package is already a devDependency in the project, use the locally installed binary instead:

pnpm add -D @entryscape/blocks-bundler
pnpm exec blocks-bundler create

This bootstraps a full project: the source layout (src/config.js, src/collections.js, src/style.css, src/blocks/example.js, plus a src/README.md orientation note), a top-level README.md and .gitignore, a package.json with dev / build / serve scripts, and a minimal demo/index.html that loads the built bundle alongside the EntryScape Blocks CDN runtime. Existing files are never overwritten. Pass --name <pkg> to set the package.json name (defaults to the cwd basename); path flags (--blocks-dir, --config, --collections, --style) still control source destinations.

After scaffolding:

pnpm install
pnpm start  # runs dev + serve together; demo at http://localhost:5173/demo/

(pnpm dev and pnpm serve are also available individually.)

Or lay out your source like this by hand (all roots are optional):

src/
  config.js          export default { namespaces, bundles, ... }
  collections.js     export default [ ...collections ]
  style.css          (read as a string and attached as `style:`)
  blocks/
    myBlock.js       export default { extends: "template", template: ... }
    other/
      another.js     export default { ... }
    scripts.js       (helper module; not registered as a block)

In each block file omit the block: property — the bundler injects it from the filename. extends: can be a built-in name ("template", "searchList", ...) or an imported block module:

import myBlock from '../myBlock.js';
export default { extends: myBlock, template: `...` };

The build resolves the imported reference to a string at compile time, so the final bundle has extends: "myBlock" directly — no runtime helpers.

Add to your package.json:

{
  "scripts": {
    "build":       "blocks-bundler",
    "build:watch": "blocks-bundler --watch"
  }
}

pnpm build produces dist/blocks.js (readable IIFE) and dist/blocks.min.js (terser-minified). Load dist/blocks.js from your HTML.

CLI options

blocks-bundler [command] [options]

Commands:
  (default)              Bundle the source tree.
  create                 Scaffold the default source structure.

Options:
  -w, --watch            Rebuild on source changes.
      --no-minify        Skip the minified bundle.
      --outfile <path>   Readable bundle output (default: dist/blocks.js).
      --min-outfile <p>  Minified bundle output (default: <outfile>.min.js).
      --banner <text>    Banner comment for both bundles (default: empty).
      --blocks-dir <d>   Blocks source directory (default: src/blocks).
      --config <file>    Config file (default: src/config.js).
      --collections <f>  Collections file (default: src/collections.js).
      --style <file>     Style file (default: src/style.css).
  -h, --help             Show this help.

Conventions

| Path | Role | |-------------------------------------|-----------------------------------------------------| | src/config.js | export default { ... } spread into the bundle | | src/collections.js | export default [ ... ] attached as collections: | | src/style.css | Read as a string, attached as style: | | src/blocks/<name>.js | One block; name = filename without .js | | src/blocks/<group>/<name>.js | Subdirectories are organization only, no namespacing | | src/blocks/scripts.js | Shared helpers; not registered as a block | | src/blocks/**/scripts/*.js | Entire scripts directories are skipped |

Plugin API

If you need a custom rollup.config.js, import the plugin directly:

import blocksBundler from '@entryscape/blocks-bundler';

export default {
  input: 'virtual:blocks-bundler-entry',
  plugins: [blocksBundler({ /* override defaults if needed */ })],
  output: { file: 'dist/blocks.js', format: 'iife' },
};

Output shape

window.__entryscape_config = [].concat(window.__entryscape_config)
  .filter(Boolean)
  .concat([{ ...config, style: "...", collections, blocks: [...] }]);

Blocks are toposorted so each block's extends target appears before it. Cyclic extends chains fail the build with a clear error.