Enjoying Blockend?

Give us a star on GitHub

Star on GitHub
blockend

Blockend

01 getting started

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-limiter

If you omit the block name, the CLI shows the blocks that support your configured framework:

pnpm dlx blockend-cli add

What the CLI does

  1. Finds blockend.json, walking up from the current directory.
  2. Fetches the registry manifest from GitHub.
  3. Filters blocks by your framework and adapter map.
  4. Lets you choose a block and a storage variant when needed.
  5. Checks your existing dependencies for missing or conflicting versions.
  6. Asks before installing missing packages.
  7. Downloads the selected files and rewrites imports for your alias and module strategy.
  8. Records the block in the installed array in blockend.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
  redis

Interactive 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.ts

A block with a root entry point:

src/
└── blocks/
    └── env-config/
        ├── index.ts
        └── index.test.ts

Some 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

OptionAliasDefaultDescription
[block]Block key, such as rate-limiter or logger.
--yes-yfalseSkip prompts, install dependencies, and overwrite conflicts.
--jsonfalseWrite machine-readable output.
--multi-mfalseSelect multiple blocks in one session.

Multi-select

pnpm dlx blockend-cli add --multi

Each 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 init

Block not found

Run list to see the registry keys available for your framework:

pnpm dlx blockend-cli list

Block 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.

On this page