Add Blocks

The add command downloads a backend block from the Blockend registry and installs it directly into your project.

Each block is framework-aware, TypeScript-first, and follows your project's existing configuration defined in blockend.json.

npx blockend-cli add <block>

For example:

npx blockend-cli add auth

If no block name is provided, Blockend launches an interactive block picker.

npx blockend-cli add

How It Works

When you run the command, Blockend performs several steps automatically.

1. Finds your blockend.json configuration.
2. Connects to the Blockend Registry.
3. Retrieves all blocks available for your framework.
4. Lets you select a block (if one isn't provided).
5. Detects the appropriate storage variant.
6. Installs missing dependencies.
7. Downloads the block source code.
8. Writes the files into your configured blocks directory.

Everything happens automatically—no copying files or manually installing packages.

Interactive Block Selection

Running the command without a block name opens an interactive selector.

npx blockend-cli add

Example:

? Which backend block would you like to inject?

❯ auth
  pagination
  upload
  cache
  logger

Only blocks compatible with your configured framework are displayed.

Framework Aware

Every block is generated specifically for your backend framework.

Currently supported environments include:

• Express.js
• Fastify
• Next.js (App Router)
• Hono

If a block is unavailable for your framework, Blockend will notify you before downloading anything.

Storage Variants

Some blocks support multiple storage implementations.

For example:

• Memory
• Redis
• Database

If multiple variants are available, Blockend asks which implementation you want.

? Which architectural storage variant do you want?

❯ Memory
  Redis

If Redis is enabled in your blockend.json, the Redis variant is selected automatically whenever available.

Automatic Dependency Installation

Many backend blocks require external packages.

Before downloading a block, Blockend checks your project's dependencies.

If required packages are missing, you'll be prompted to install them.

Example:

Missing required infrastructure packages:

- redis
- zod

Would you like the CLI to install them automatically?

❯ Yes

Blockend automatically detects your package manager.

Supported package managers:

• pnpm
• npm

After installation completes, the block download continues automatically.

Generated Files

Downloaded files are placed inside the blocks directory configured during initialization.

Example:

src/
└── blocks/
    └── auth/
        ├── auth.ts
        └── store-redis.ts

Simple blocks may generate a single file.

src/
└── blocks/
    └── pagination.ts

Existing Files

If a block already exists, Blockend never overwrites it without confirmation.

Example:

Block component already exists.

Overwrite existing files?

❯ No

Selecting No safely aborts the operation and preserves your code.

Examples

Generate an rate limiter block:

npx blockend-cli add rate-limiter

Generate a env-config block:

npx blockend add env-config

Generate an upload block:

npx blockend-cli add upload

Open the interactive selector:

npx blockend-cli add

Requirements

Before using the add command, make sure your project has been initialized.

npx blockend-cli init

Blockend also requires:

• A valid blockend.json
• A TypeScript project
• A supported backend framework
• Internet access to download blocks from the Blockend Registry

Common Errors

blockend.json not found

blockend.json not found.
Run 'npx blockend-cli init' first.

Initialize your project before adding blocks.

npx blockend-cli init

Block not found

Block "auth" does not exist.

The requested block either doesn't exist or hasn't been published yet.

Run the interactive command to see all available blocks.

npx blockend-cli list

Unsupported Framework

The block "upload" does not support your environment.

Some blocks are framework-specific and may not be available for every backend.

Failed to Download Registry

Failed to fetch the component registry.

Verify your internet connection and try again.

Next Steps

After generating a block, import it into your application and customize it as needed.

Every generated block is fully owned by you—there are no runtime dependencies on Blockend.