Add blocks
Choose a block, pick a variant, and write its source files into your project.
The add command copies a block from the registry into the directory in blockend.json. The files are normal source files. You can edit, delete, or commit them.
The CLI currently requires a TypeScript project. It exits if blockend.json has "language": "javascript".
Quick start
pnpm dlx blockend-cli init
pnpm dlx blockend-cli add rate-limiterIf you omit the block name, the CLI shows the blocks that support your configured framework:
pnpm dlx blockend-cli addWhat the CLI does
- Finds
blockend.json, walking up from the current directory. - Fetches the registry manifest from GitHub.
- Filters blocks by your framework and adapter map.
- Lets you choose a block and a storage variant when needed.
- Checks your existing dependencies for missing or conflicting versions.
- Asks before installing missing packages.
- Downloads the selected files and rewrites imports for your alias and module strategy.
- Records the block in the
installedarray inblockend.json.
Frameworks
The CLI supports Express, Fastify, Next.js App Router, and Hono. A block appears only when it has an adapter for your framework. Universal blocks with "frameworks": ["*"], such as env-config and password-hash, work with every framework, including Next.js.
Storage variants
Some blocks offer more than one implementation. For example, the rate limiter has memory and Redis stores.
? Select a storage variant for rate-limiter:
❯ memory
redisInteractive mode asks. If includeRedis is true and a Redis variant exists, it selects Redis. With --yes, it selects memory when available, otherwise the first variant.
Dependencies
Before writing files, the CLI compares the block's required production and development packages with your package.json. Missing packages are listed in a prompt. Declining the prompt skips dependency installation, but the block files are still written.
Installation runs pnpm add when packageManager is pnpm, and npm install for every other value. If your project uses yarn or bun, decline the prompt and install the listed packages with your package manager.
Version conflicts are reported as warnings. If you accept the dependency install, the CLI installs the version required by the block, which can replace an incompatible version in your project.
Generated files
Files go under paths.blocks from blockend.json.
The rate limiter, for example:
src/
└── blocks/
└── rate-limiter/
├── adapters/
│ ├── express.ts
│ └── express.test.ts
├── core/
│ └── core.ts
├── utils/
│ ├── ip.ts
│ └── ip.test.ts
└── variants/
├── memory-store.ts
└── memory-store.test.tsA block with a root entry point:
src/
└── blocks/
└── env-config/
├── index.ts
└── index.test.tsSome blocks have no root index.ts. The block page tells you the correct import path.
Import rewriting
The CLI writes imports in the style your project uses:
- With a TypeScript path alias, imports use your configured alias, such as
@/blocks/<block>/.... - Without an alias, imports stay relative.
- With
importRewriteStrategy: "rewrite", internal imports end in.js. - With
"remove", internal extensions are stripped.
If an import in the docs points to @/blocks, run init again or edit blockend.json if your alias differs.
Existing files
When a block file already exists, the CLI asks before overwriting it. The default answer is no. Declining leaves the existing file untouched and stops the operation.
With --yes, the CLI overwrites conflicts and installs missing dependencies without prompting. Use it in scripts only after you have reviewed the target files.
Options
| Option | Alias | Default | Description |
|---|---|---|---|
[block] | Block key, such as rate-limiter or logger. | ||
--yes | -y | false | Skip prompts, install dependencies, and overwrite conflicts. |
--json | false | Write machine-readable output. | |
--multi | -m | false | Select multiple blocks in one session. |
Multi-select
pnpm dlx blockend-cli add --multiEach selected block is processed in order with its own dependency check, conflict prompt, and file download. If one block fails, the CLI skips it and continues with the rest. The final count includes only the blocks that succeeded.
Common problems
blockend.json not found
Run init from your project root, or from a directory inside it:
pnpm dlx blockend-cli initBlock not found
Run list to see the registry keys available for your framework:
pnpm dlx blockend-cli listBlock does not support your framework
The block has no adapter for your configured environment. Change environment in blockend.json if it is wrong, or choose a compatible block.
Registry fetch failed
The CLI downloads registry/index.json from GitHub. Check network access, proxy settings, and GitHub availability.
Next steps
After the files are written, open the block page and follow its quick start. Every block page lists the exact import paths and required setup for its framework.